REST API reference

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. Replace https://api.example.com with your Amendary backend origin.

All endpoint paths below use the /api/v1 prefix. Your key selects one workspace and has read access; no workspace header is needed.

curl "https://api.example.com/api/v1/corrections?status=pending&limit=20" \
  --header "Authorization: Bearer amk_your_key_here"

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 parameter is invalid. Follow the bounds and enum values below.
429 means this key exceeded the configured per-minute limit (30 requests by default). Honor the Retry-After response header before retrying.
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.

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–200, default 50), offset (0 or greater).

{
  "items": [{
    "id": "3d84fb2d-3743-44a4-8bb8-adb0f0056554",
    "notion_page_id": "6af45f73-778d-41c5-b7c4-ac4f5d3b7d76",
    "status": "pending",
    "source": "release", "source_ref": "v2.14.0",
    "source_url": "https://github.com/acme/api/releases/tag/v2.14.0",
    "changed_paths": ["src/rate_limit.py"],
    "stale_quote": "The limit is 60 requests per minute.",
    "planned_edit": "The limit is 120 requests per minute.",
    "context_complete": true, "ungrounded_tokens": null,
    "dropped_tokens": null, "created_at": "2026-10-02T09:15:00Z"
  }],
  "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, or new_page.
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.

GET

/checks/status

Returns one freshness record for every repository in the workspace. There are no query parameters.

{
  "repos": [{
    "repo_id": "11f29f32-3f6f-4f94-9c9c-6f75026d3a8d",
    "repo_full_name": "acme/api",
    "last_checked_at": "2026-10-02T08:00:00Z",
    "last_checked_commit_sha": "9d6b4a49b4a904fb84e2210cf15f64246ca75a24",
    "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, or failed; null before a check is recorded.
pending_corrections	integer	Pending corrections across pages mapped to the repo.

GET

/usage

Returns the same workspace token and operational usage summary shown in the dashboard.

Query: days (1–365, default 30). The response includes totals, daily and purpose/repo breakdowns, today’s effective budget, budget events, cache token counts and operational counts.

curl "https://api.example.com/api/v1/usage?days=7" \
  -H "Authorization: Bearer amk_your_key_here"

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, effective budget, percentage used, and paused state.
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 budget.
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.

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.

{
  "docs": [{
    "page_id": "6af45f73-778d-41c5-b7c4-ac4f5d3b7d76",
    "title": "API limits",
    "page_type": "customer_success", "doc_type": "prose",
    "source_kind": "notion",
    "url": "https://www.notion.so/6af45f73778d41c5b7c4ac4f5d3b7d76",
    "repo_id": "11f29f32-3f6f-4f94-9c9c-6f75026d3a8d",
    "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, customer_success, or excluded.
doc_type	string	prose, 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.

Using an MCP client instead of REST? The transport, initialization request, tool parameters, and client configuration are in the MCP guide.