Quick start
As a workspace owner, create a key under Settings → API keys, save the one-time value, and send it as a Bearer token. Keys always include read access; select “Allow this key to run checks” to add checks:run. Requests go to https://api.amendary.com.
All endpoint paths below use the /api/v1 prefix. Your key selects one workspace; no workspace header is needed. Set the AMENDARY_API_KEY environment variable to your saved key before running the curl examples.
curl "https://api.amendary.com/api/v1/corrections?status=pending&limit=20" \
--header "Authorization: Bearer $AMENDARY_API_KEY"GET /api/v1/openapi.json. It includes the Bearer security scheme, parameter constraints, and every response model for client generation.Errors, limits, and pagination
401means the key is missing, malformed, unknown, or revoked. These cases deliberately share one response.422means a query, header, or pointer is invalid. Fork PRs, identical or unreachable ranges, ranges over 100 commits, and uploaded diffs are rejected.429means the request rate (30 requests per minute by default), daily key allowance, or the workspace’s daily usage limit was reached. Honor theRetry-Afterresponse header before retrying.402means the active trial or subscription ended;403means the key lacks the scope or the team is suspended. Reads remain available to authenticated keys.404means the repository or check is unavailable in this workspace.409means the repo is busy or an idempotency key was reused with a different payload.5xxmeans the service could not complete the read. Retry transient failures with exponential backoff.- Only corrections use offset pagination. The response returns
items,limit,offset, andtotal; request the next page whileoffset + items.length < total.
Error bodies (examples include all returned fields):
unauthorized
{
"detail": "Invalid API key"
}forbidden
{
"detail": "API key requires checks:run scope"
}notFound
{
"detail": "Change check not found"
}conflict
{
"detail": "Idempotency key is already bound to a different request"
}invalidPointer
{
"detail": "Fork pull requests are not supported"
}budget
{
"detail": "API key daily check allowance exhausted"
}payment
{
"detail": "Agent-triggered checks require an active trial or subscription"
}validation
{
"detail": [
{
"type": "missing",
"loc": [
"header",
"Idempotency-Key"
],
"msg": "Field required",
"input": null
}
]
}/corrections
Lists corrections newest first, including review text and evidence. Use this endpoint to populate a queue or alert on pending documentation work.
Query: status (optional: pending, approved, rejected, reverted), limit (1 to 200, default 50), offset (0 or greater).
curl "https://api.amendary.com/api/v1/corrections?status=pending&limit=20&offset=0" --header "Authorization: Bearer $AMENDARY_API_KEY"{
"items": [
{
"id": "00000000-0000-4000-8000-000000000003",
"notion_page_id": "00000000-0000-4000-8000-000000000004",
"status": "pending",
"source": "diff",
"source_url": "https://github.com/acme/api/compare/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa...bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"source_ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"changed_paths": [
"src/limits.py"
],
"stale_quote": "The limit is 60 requests per minute.",
"planned_edit": "The limit is 120 requests per minute.",
"context_complete": true,
"ungrounded_tokens": [],
"dropped_tokens": [],
"created_at": "2026-10-02T09:15:20Z"
}
],
"limit": 20,
"offset": 0,
"total": 1
}| Field | Type | Meaning |
|---|---|---|
| id | UUID | Correction identifier. |
| notion_page_id | UUID | Internal page identifier. The name is retained for compatibility and also identifies GitHub-backed pages. |
| status | string | pending, approved, rejected, or reverted. |
| source | string | diff, initial_audit, release, new_page, or diagram. |
| source_url / source_ref | string | null | Evidence link and the release, tag, or commit reference. |
| changed_paths | array | null | Repository paths in the evidence when available. |
| stale_quote / planned_edit | string | null | The passage under review and the text Amendary would write. |
| context_complete | boolean | False when the source input was truncated or otherwise incomplete. |
| ungrounded_tokens / dropped_tokens | array | null | Values that require human attention because the evidence did not support them. |
| created_at | ISO 8601 | When the correction was created. |
/checks/status
Returns one freshness record for every repository in the workspace. There are no query parameters.
curl "https://api.amendary.com/api/v1/checks/status" --header "Authorization: Bearer $AMENDARY_API_KEY"{
"repos": [
{
"repo_id": "00000000-0000-4000-8000-000000000002",
"repo_full_name": "acme/api",
"last_checked_at": "2026-10-02T08:00:00Z",
"last_checked_commit_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"last_check_status": "ok",
"pending_corrections": 1
}
]
}| Field | Type | Meaning |
|---|---|---|
| repo_id / repo_full_name | UUID / string | The repository identifier and owner/name. |
| last_checked_at | ISO 8601 | null | When the last completed check was recorded. |
| last_checked_commit_sha | string | null | The latest commit Amendary compared through. |
| last_check_status | string | null | ok, partial, failed, or interrupted (a restart stopped the check); null before a check is recorded. |
| pending_corrections | integer | Pending corrections across pages mapped to the repo. |
/checks
Queue an engineering-documentation preview for a GitHub PR or base/head range. Requires checks:run and an active trial or subscription.
Send Authorization, Content-Type: application/json, and Idempotency-Key (1 to 200 characters). All request fields are shown below; unused pointer fields may be omitted or null. Extra fields are rejected.
curl "https://api.amendary.com/api/v1/checks" \
--header "Authorization: Bearer $AMENDARY_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: ci-pr-19" \
--data '{"repo":"acme/api","pr_number":19,"base":null,"head":null,"note":"Check the mapped engineering docs for this proposed change.","retry":false}'PR payload
{
"repo": "acme/api",
"pr_number": 19,
"base": null,
"head": null,
"note": "Check the mapped engineering docs for this proposed change.",
"retry": false
}Base/head payload
{
"repo": "acme/api",
"pr_number": null,
"base": "main",
"head": "feature/limits",
"note": null,
"retry": false
}| Field | Type | Meaning |
|---|---|---|
| repo | string | Connected repository owner/name (3 to 255 characters). |
| pr_number | integer | null | PR number, at least 1; mutually exclusive with base/head. |
| base / head | string | null | Both refs are required for a range (1 to 255 characters each). |
| note | string | null | Optional text, at most 2,000 characters. Only its hash is stored; it does not reach a model or influence evidence. |
| retry | boolean | Default false. True requeues a failed request using the original key and payload. |
PRs resolve to GitHub’s merge-base and head; ranges must be reachable. Replays return the original request, and equivalent SHA pairs share a result. Reusing an idempotency key with a changed payload returns 409. Success is an immutable snapshot; a replay does not re-audit edited pages.
202 response
Location: /api/v1/checks/00000000-0000-4000-8000-000000000001
{
"id": "00000000-0000-4000-8000-000000000001",
"repo_id": "00000000-0000-4000-8000-000000000002",
"status": "queued",
"base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"head_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"result": null,
"error": null,
"waiting_for": null,
"token_usage": 0,
"created_at": "2026-10-02T09:15:00Z",
"started_at": null,
"finished_at": null
}Retry a failed check
Use the original API key, idempotency key and payload with retry set to true. It reserves a fresh allowance; prior token usage remains charged.
{
"repo": "acme/api",
"pr_number": 19,
"base": null,
"head": null,
"note": "Check the mapped engineering docs for this proposed change.",
"retry": true
}Defaults: 250,000 tokens reserved per attempt and 1,000,000 tokens per API key per UTC submission day, configurable by the operator. Recovery keeps the original reservation day. Input, output and cache tokens count; uncertain transport or crash spend stays conservatively charged. Unused reservations are released after completion or failure. The workspace’s daily usage limit also applies.
/checks/{request_id}
Poll the request resource with a read key until execution succeeds or fails. Queued and running requests recover after restarts.
curl "https://api.amendary.com/api/v1/checks/00000000-0000-4000-8000-000000000001" --header "Authorization: Bearer $AMENDARY_API_KEY"| Field | Type | Meaning |
|---|---|---|
| id / repo_id | UUID | Request and connected repository identifiers. |
| status | string | queued, running, succeeded or failed. HTTP 200 can contain a failed job. |
| base_sha / head_sha | string | Immutable 40-character resolved GitHub commit SHAs. |
| result | object | null | Available after success; every nested field is shown below. |
| error | string | null | Failure reason; null for queued/running/succeeded. |
| waiting_for | string | null | Set while queued behind another run on the repo; the check fails after 30 minutes of waiting. |
| token_usage | integer | All charged input, output and cache tokens across attempts, including conservative unknown spend. |
| created_at / started_at / finished_at | ISO 8601 | null | Creation is always present; execution times are nullable until reached. |
| Field | Type | Meaning |
|---|---|---|
| result.commits | integer | Commit count in the GitHub range. |
| result.changed_paths | string[] | Paths reported by GitHub. |
| result.source_url / merge_base_sha | string | null / string | GitHub comparison link and merge-base SHA. |
| result.verdict | string | findings, no_findings, incomplete, no_mapped_pages, or nothing_doc_relevant. |
| result.docs_impact | string | Deterministic summary of this check’s outcome. |
| result.pages_checked / pages_unavailable | integer | Pages with findings/verdicts and unreadable eligible pages. |
| result.correction_ids | UUID[] | Find these records in GET /corrections; all need human review. |
| result.evidence_complete | boolean | False if evidence or page coverage was incomplete. |
Check execution status and verdict separately. Succeeded means processing finished; incomplete is never a clean result. No mapped pages and nothing documentation-relevant do not mean pages were judged. Only mapped engineering docs are checked; help-center pages keep their own trigger. A preview never auto-applies edits, posts a changelog entry, or changes scheduled freshness.
running response
{
"id": "00000000-0000-4000-8000-000000000001",
"repo_id": "00000000-0000-4000-8000-000000000002",
"status": "running",
"base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"head_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"result": null,
"error": null,
"waiting_for": null,
"token_usage": 1500,
"created_at": "2026-10-02T09:15:00Z",
"started_at": "2026-10-02T09:15:03Z",
"finished_at": null
}succeeded response
{
"id": "00000000-0000-4000-8000-000000000001",
"repo_id": "00000000-0000-4000-8000-000000000002",
"status": "succeeded",
"base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"head_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"result": {
"commits": 2,
"changed_paths": [
"src/limits.py"
],
"source_url": "https://github.com/acme/api/compare/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa...bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"merge_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"verdict": "findings",
"docs_impact": "Found 1 documentation correction(s).",
"pages_checked": 3,
"pages_unavailable": 0,
"correction_ids": [
"00000000-0000-4000-8000-000000000003"
],
"evidence_complete": true
},
"error": null,
"waiting_for": null,
"token_usage": 8432,
"created_at": "2026-10-02T09:15:00Z",
"started_at": "2026-10-02T09:15:03Z",
"finished_at": "2026-10-02T09:15:25Z"
}incomplete response
{
"id": "00000000-0000-4000-8000-000000000001",
"repo_id": "00000000-0000-4000-8000-000000000002",
"status": "succeeded",
"base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"head_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"result": {
"commits": 2,
"changed_paths": [
"src/limits.py"
],
"source_url": "https://github.com/acme/api/compare/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa...bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"merge_base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"verdict": "incomplete",
"docs_impact": "The evidence or page coverage is incomplete; review the available findings.",
"pages_checked": 2,
"pages_unavailable": 1,
"correction_ids": [
"00000000-0000-4000-8000-000000000003"
],
"evidence_complete": false
},
"error": null,
"waiting_for": null,
"token_usage": 6500,
"created_at": "2026-10-02T09:15:00Z",
"started_at": "2026-10-02T09:15:03Z",
"finished_at": "2026-10-02T09:15:25Z"
}failed response
{
"id": "00000000-0000-4000-8000-000000000001",
"repo_id": "00000000-0000-4000-8000-000000000002",
"status": "failed",
"base_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"head_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"result": null,
"error": "GitHub could not provide the diff; documentation was not checked",
"waiting_for": null,
"token_usage": 0,
"created_at": "2026-10-02T09:15:00Z",
"started_at": "2026-10-02T09:15:03Z",
"finished_at": "2026-10-02T09:15:04Z"
}/usage
Returns the same workspace token and operational usage summary shown in the dashboard.
Query: days (1 to 365, default 30). The response includes totals, daily and purpose/repo breakdowns, today’s daily usage limit, the days it was reached (budget events), cache token counts and operational counts.
curl "https://api.amendary.com/api/v1/usage?days=7" \
-H "Authorization: Bearer $AMENDARY_API_KEY"{
"total_input_tokens": 8000,
"total_output_tokens": 432,
"by_day": [
{
"date": "2026-10-02",
"input_tokens": 8000,
"output_tokens": 432,
"cache_tokens": 1000,
"calls": 2,
"estimated_cost_cents": 3
}
],
"today": {
"tokens": 9432,
"budget": 100000,
"pct": 9,
"paused": false
},
"by_purpose": [
{
"purpose": "diff_summary",
"label": "Change summaries",
"input_tokens": 8000,
"output_tokens": 432,
"calls": 2
}
],
"by_repo": [
{
"repo_id": "00000000-0000-4000-8000-000000000002",
"repo_full_name": "acme/api",
"input_tokens": 8000,
"output_tokens": 432,
"flags": 1
}
],
"totals": {
"input_tokens": 8000,
"output_tokens": 432,
"calls": 2,
"estimated_cost_cents": 3
},
"budget_events": [
{
"date": "2026-10-01",
"tokens_used": 100010,
"daily_budget": 100000
}
],
"operational": {
"diffs_processed": 1,
"releases_processed": 0,
"initial_audits": 0,
"changed_files": 1,
"pages_checked": 3,
"verdicts_no_change": 2,
"flags_created": 1,
"flags_pending": 1,
"flags_applied": 0,
"flags_reverted": 0,
"flags_rejected": 0,
"ranges_skipped": {
"noise_only": 1
}
},
"cache_savings_cents": 1,
"cache_read_tokens": 800,
"cache_write_tokens": 200
}| Field | Type | Meaning |
|---|---|---|
| total_input_tokens / total_output_tokens | integer | Tokens used in the selected window. |
| by_day | array | Daily token, cache, call, and estimated-cost totals. |
| today | object | Tokens used today, the daily usage limit (budget), percentage used, and paused state. Today follows the team's timezone. |
| by_purpose / by_repo | array | Usage grouped by operation and repository. |
| totals | object | Calls, input/output tokens, and estimated cost for the window. |
| budget_events | array | Dates on which the workspace reached its daily usage limit. |
| operational | object | Diffs, releases, pages, verdicts, flags, and skipped ranges processed. |
| cache_read_tokens / cache_write_tokens | integer | Prompt-cache activity in the window. |
| cache_savings_cents | integer | null | Estimated whole cents saved by cache reads. |
/docs
Lists mapped page/repository pairs and their freshness metadata. It returns links and metadata, never the page body.
Query: repo (optional exact owner/name, case-insensitive) and topic (optional case-insensitive title substring). A page mapped to multiple repos appears once for each mapping.
curl "https://api.amendary.com/api/v1/docs?repo=acme%2Fapi&topic=limits" --header "Authorization: Bearer $AMENDARY_API_KEY"{
"docs": [
{
"page_id": "00000000-0000-4000-8000-000000000004",
"title": "API limits",
"page_type": "technical_docs",
"doc_type": "prose",
"source_kind": "notion",
"url": "https://www.notion.so/00000000000040008000000000000004",
"repo_id": "00000000-0000-4000-8000-000000000002",
"repo_full_name": "acme/api",
"last_synced_at": "2026-10-02T07:30:00Z",
"last_checked_at": "2026-10-02T08:00:00Z",
"pending_corrections": 1
}
]
}| Field | Type | Meaning |
|---|---|---|
| page_id / title | UUID / string | The mapped page identifier and title. |
| page_type | string | technical_docs (Engineering docs), customer_success (Help center), or excluded (Checks paused). |
| doc_type | string | prose (Docs & guides), runbook, incident, product_update, or adr. |
| source_kind / url | string / string | null | Where the page lives and its best available destination URL. |
| repo_id / repo_full_name | UUID / string | The mapped repository. |
| last_synced_at / last_checked_at | ISO 8601 | null | Last page sync time and repository check time. |
| pending_corrections | integer | Pending corrections for this page. |