← API and MCP overview

Developer reference

REST API reference

The v1 API exposes workspace data and engineering-documentation checks for CI and agents. Read calls spend no model budget. A scoped check uses model tokens to draft findings for human review; it never applies a correction or edits a page.

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"
Machine-readable schema: GET /api/v1/openapi.json. It includes the Bearer security scheme, parameter constraints, and every response model for client generation.

Errors, limits, and pagination

  • 401 means the key is missing, malformed, unknown, or revoked. These cases deliberately share one response.
  • 422 means a query, header, or pointer is invalid. Fork PRs, identical or unreachable ranges, ranges over 100 commits, and uploaded diffs are rejected.
  • 429 means the request rate (30 requests per minute by default), daily key allowance, or the workspace’s daily usage limit was reached. Honor the Retry-After response header before retrying.
  • 402 means the active trial or subscription ended; 403 means the key lacks the scope or the team is suspended. Reads remain available to authenticated keys.
  • 404 means the repository or check is unavailable in this workspace.
  • 409 means the repo is busy or an idempotency key was reused with a different payload.
  • 5xx means the service could not complete the read. Retry transient failures with exponential backoff.
  • Only corrections use offset pagination. The response returns items, limit, offset, and total; request the next page while offset + 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
    }
  ]
}
GET

/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
}
FieldTypeMeaning
idUUIDCorrection identifier.
notion_page_idUUIDInternal page identifier. The name is retained for compatibility and also identifies GitHub-backed pages.
statusstringpending, approved, rejected, or reverted.
sourcestringdiff, initial_audit, release, new_page, or diagram.
source_url / source_refstring | nullEvidence link and the release, tag, or commit reference.
changed_pathsarray | nullRepository paths in the evidence when available.
stale_quote / planned_editstring | nullThe passage under review and the text Amendary would write.
context_completebooleanFalse when the source input was truncated or otherwise incomplete.
ungrounded_tokens / dropped_tokensarray | nullValues that require human attention because the evidence did not support them.
created_atISO 8601When the correction was created.
GET

/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
    }
  ]
}
FieldTypeMeaning
repo_id / repo_full_nameUUID / stringThe repository identifier and owner/name.
last_checked_atISO 8601 | nullWhen the last completed check was recorded.
last_checked_commit_shastring | nullThe latest commit Amendary compared through.
last_check_statusstring | nullok, partial, failed, or interrupted (a restart stopped the check); null before a check is recorded.
pending_correctionsintegerPending corrections across pages mapped to the repo.
POST

/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
}
FieldTypeMeaning
repostringConnected repository owner/name (3 to 255 characters).
pr_numberinteger | nullPR number, at least 1; mutually exclusive with base/head.
base / headstring | nullBoth refs are required for a range (1 to 255 characters each).
notestring | nullOptional text, at most 2,000 characters. Only its hash is stored; it does not reach a model or influence evidence.
retrybooleanDefault 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.

GET

/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"
FieldTypeMeaning
id / repo_idUUIDRequest and connected repository identifiers.
statusstringqueued, running, succeeded or failed. HTTP 200 can contain a failed job.
base_sha / head_shastringImmutable 40-character resolved GitHub commit SHAs.
resultobject | nullAvailable after success; every nested field is shown below.
errorstring | nullFailure reason; null for queued/running/succeeded.
waiting_forstring | nullSet while queued behind another run on the repo; the check fails after 30 minutes of waiting.
token_usageintegerAll charged input, output and cache tokens across attempts, including conservative unknown spend.
created_at / started_at / finished_atISO 8601 | nullCreation is always present; execution times are nullable until reached.
FieldTypeMeaning
result.commitsintegerCommit count in the GitHub range.
result.changed_pathsstring[]Paths reported by GitHub.
result.source_url / merge_base_shastring | null / stringGitHub comparison link and merge-base SHA.
result.verdictstringfindings, no_findings, incomplete, no_mapped_pages, or nothing_doc_relevant.
result.docs_impactstringDeterministic summary of this check’s outcome.
result.pages_checked / pages_unavailableintegerPages with findings/verdicts and unreadable eligible pages.
result.correction_idsUUID[]Find these records in GET /corrections; all need human review.
result.evidence_completebooleanFalse 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"
}
GET

/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
}
FieldTypeMeaning
total_input_tokens / total_output_tokensintegerTokens used in the selected window.
by_dayarrayDaily token, cache, call, and estimated-cost totals.
todayobjectTokens used today, the daily usage limit (budget), percentage used, and paused state. Today follows the team's timezone.
by_purpose / by_repoarrayUsage grouped by operation and repository.
totalsobjectCalls, input/output tokens, and estimated cost for the window.
budget_eventsarrayDates on which the workspace reached its daily usage limit.
operationalobjectDiffs, releases, pages, verdicts, flags, and skipped ranges processed.
cache_read_tokens / cache_write_tokensintegerPrompt-cache activity in the window.
cache_savings_centsinteger | nullEstimated whole cents saved by cache reads.
GET

/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
    }
  ]
}
FieldTypeMeaning
page_id / titleUUID / stringThe mapped page identifier and title.
page_typestringtechnical_docs (Engineering docs), customer_success (Help center), or excluded (Checks paused).
doc_typestringprose (Docs & guides), runbook, incident, product_update, or adr.
source_kind / urlstring / string | nullWhere the page lives and its best available destination URL.
repo_id / repo_full_nameUUID / stringThe mapped repository.
last_synced_at / last_checked_atISO 8601 | nullLast page sync time and repository check time.
pending_correctionsintegerPending corrections for this page.
Using an MCP client instead of REST? The transport, initialization request, tool parameters, and client configuration are in the MCP guide.

Try Amendary on your own help center

Connect Notion, GitHub, Zendesk or Intercom and pick the articles to watch. Your first check shows what Amendary would fix, with the change as proof.

Free for 14 days with no card, and every edit waits for your review. Or free forever with your own Anthropic API key. Code is never touched.