Skip to main content
Login
Sign up
View in Markdown

The live, auto-generated HTTP reference for the Aardvark cloud gateway — rendered inline by the openapi directive on a wide-mode page.

The reference below is the real, user-facing API of the Aardvark cloud gateway — the metered OpenRouter proxy and dashboard backend behind the reader assistant. Chat, reader telemetry, dashboard analytics, account and API-key management, team, billing, and magic-link auth are all here, rendered inline by the {% openapi %} directive on an ordinary Markdown page set to mode: wide — no dedicated page generator, just a component.

It also doubles as the headline demonstration of that directive: every operation below is wired into the left-hand nav, with parameter and response tables, multi-language request samples, and a Try it now form. To splice a single endpoint into a page instead of the whole spec, see OpenAPI under Components.

The spec it renders, openapi/aardvark-gateway.json, isn’t hand-written: it’s extracted from the gateway’s own source — every route’s auth, request fields, query params, response shape, and error codes — and regenerated on every change, so this reference can’t drift from the code it documents. (That’s the same drift-proof loop you’d wire up for your own API.)

Aardvark Gateway API

v1.0.0

User-facing HTTP API of the aardvark cloud gateway — the metered OpenRouter proxy and dashboard backend. Operator-only endpoints (/admin/*, /operator-auth/*, /operator-api/*) and the dashboard / operator SPA shells (/dashboard*, /operator*) are excluded by design.

This document is GENERATED from the gateway source: scripts/gen-openapi.mjs extracts every route’s auth, request fields, query params, response shape, and error codes directly from the handlers, then renders them. Do NOT edit openapi.json (or hand-author its structure) — change the code, and regenerate. Only prose lives in scripts/openapi/descriptions.mjs.

Base URLhttps://gateway.aardvarkdocs.com

Authorization

Public widget key, Authorization: Bearer aardvark_live_… . Origin-scoped. Used in the request samples and Try it now below. Held in memory for this session only.

Metered chat completions.

POST

Chat completion

https://gateway.aardvarkdocs.com/v1/chat/completions

OpenAI-compatible chat-completions endpoint. The gateway authorizes the key, reserves the input cost against the account balance, forwards the request to the configured upstream model, and streams the response back as Server-Sent Events while metering actual spend. The system prompt is always injected by the gateway; client-supplied system messages are stripped. The sampling fields (temperature/top_p/frequency_penalty/presence_penalty) are clamped to valid ranges.

Responses

Body

A single string value.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "How do I install the CLI?"
    }
  ],
  "max_tokens": 512,
  "temperature": 0.3
}'

Response examples

"string"

Reader telemetry ingest.

POST

Authoring beacon

https://gateway.aardvarkdocs.com/v1/authoring-telemetry

Scaffold ingest for a future authoring client. Public-key authed like the other reader beacons; event_type is restricted to letters/digits/‘.’/‘_’/‘-’. Best-effort over the per-account daily cap.

Responses

Body

okbooleannoAlways true; best-effort ack even when the row is dropped over the daily cap.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/authoring-telemetry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "event_type": "draft.generated",
  "detail": "page=quickstart"
}'

Response examples

{
  "ok": true
}
POST

Submit a comment

https://gateway.aardvarkdocs.com/v1/comment

Stores a free-text reader comment, optionally tied to a page path and an island-generated survey/question id. Best-effort over the per-account daily cap. page_url must be a safe site-relative pathname or it is stored as null.

Responses

Body

okbooleannoAlways true on accept; best-effort, so true even when the daily cap drops the row.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/comment' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "comment": "The quickstart was great.",
  "page_url": "/docs/quickstart"
}'

Response examples

{
  "ok": true
}
POST

Engagement beacon

https://gateway.aardvarkdocs.com/v1/engagement

Public-key beacon (migration 0027): the escalation/contact link was SHOWN under a downvoted answer (escalation_shown) or CLICKED (escalation_click). Decoupled from the transcript and subject to a per-account daily row cap; drives the dashboard’s support-deflection metric.

Responses

Body

okbooleannoAlways true on accept; a deduped or over-cap beacon still ACKs 200.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/engagement' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "conversation_id": "c_abc123",
  "kind": "escalation_click",
  "turn": 0
}'

Response examples

{
  "ok": true
}
POST

Rate an answer

https://gateway.aardvarkdocs.com/v1/feedback

Stores a reader's vote on a specific answer turn. Best-effort: over the per-account daily cap the vote is silently dropped but still returns 200. Deduplicated on (account, conversation_id, turn).

Responses

Body

okbooleannoAlways true; the vote is best-effort, so an over-cap drop still ACKs 200.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "vote": "up",
  "conversation_id": "c_abc123",
  "question": "How do I deploy?",
  "turn": 0
}'

Response examples

{
  "ok": true
}
POST

MCP tool-call beacon

https://gateway.aardvarkdocs.com/v1/mcp-telemetry

The docs MCP server posts one beacon per tool call. A short args summary is either supplied (args_summary) or derived from args. Server-side callers (no Origin header) bypass the origin allowlist; browsers must pass it. Best-effort over the per-account daily cap.

Responses

Body

okbooleannoAlways true on a 200; the beacon was accepted (also when silently dropped over the daily cap).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/mcp-telemetry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "tool": "search_docs",
  "args_summary": "query=install cli"
}'

Response examples

{
  "ok": true
}
POST

Submit a rating

https://gateway.aardvarkdocs.com/v1/rating

Public-key capture of a reader star rating for a page (migration 0036), optionally with a comment. Best-effort over the per-account daily cap.

Responses

Body

okbooleannoAlways true on accept; best-effort, so true even when the daily cap drops the row.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/rating' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "rating": 5,
  "comment": "Crystal clear.",
  "page_url": "/docs/quickstart"
}'

Response examples

{
  "ok": true
}
POST

Search activity beacon

https://gateway.aardvarkdocs.com/v1/search-event

Public-key batch beacon (migration 0040): the header search box reports settled queries, result clicks, and Ask-AI escalations. Body is { events: [...] }, each event a query, click, or ask_ai. Subject to a per-account daily row cap and dedup; only AI-enabled sites emit. Powers the dashboard’s Search Analytics.

Responses

Body

okbooleannoAlways true on accept; a deduped, over-cap, or empty batch still ACKs 200.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/search-event' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "events": [
    {
      "kind": "query",
      "session_id": "s_abc",
      "session_seq": 0,
      "term": "install",
      "results": 3,
      "latency_ms": 5
    },
    {
      "kind": "click",
      "session_id": "s_abc",
      "session_seq": 1,
      "term": "install",
      "position": 1,
      "page_url": "/guide/install/"
    }
  ]
}'

Response examples

{
  "ok": true
}
POST

Submit survey answer

https://gateway.aardvarkdocs.com/v1/survey

Public-key capture of a structured reader survey answer (migration 0037) — a single/multi choice or a rating — that the Survey island previously sent only to analytics. Best-effort over the per-account daily cap.

Responses

Body

okbooleannoAlways true on accept; best-effort, so true even when the daily cap drops the row.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/survey' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "question_type": "rating",
  "answer_value": "4",
  "rating_value": 4,
  "survey_id": "csat",
  "question_id": "q1",
  "page_url": "/docs/quickstart"
}'

Response examples

{
  "ok": true
}
POST

Record a Q&A turn

https://gateway.aardvarkdocs.com/v1/transcript

Upserts one conversation turn (question + answer, optionally the model’s reasoning) keyed on (key, conversation_id, turn). At least one of question/answer is required. Best-effort over the per-account daily cap; an out-of-range turn is rejected rather than coerced.

Responses

Body

okbooleannoAlways true; returned on a stored turn or a best-effort ack over the daily cap.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/transcript' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "conversation_id": "c_abc123",
  "turn": 0,
  "question": "How do I build my site?",
  "answer": "Run `vark build`."
}'

Response examples

{
  "ok": true
}

Dashboard analytics.

GET

Live activity rollup

https://gateway.aardvarkdocs.com/v1/activity

Headline metrics over the last days (default 30, capped at 365): conversation/answer/feedback counts, verdict mix, uncertainty rate, engagement, support-deflection rate, and top languages.

daysqueryintegernoWindow length in days (default 30, capped at 365).

Responses

Body

window_daysintegernoResolved look-back window in days (default 30, capped at 365).
sinceintegernoWindow start, epoch-ms (inclusive); until minus window_days.
untilintegernoWindow end, epoch-ms (exclusive); the request time.
conversationsnumbernoDistinct conversations with at least one stored turn in the window.
answersnumbernoTotal stored answer turns (transcript rows) in the window.
feedbackobjectnoReader thumbs vote tallies and the derived satisfaction rate.
feedback.upstringnoCount of thumbs-up votes on answers in the window.
feedback.downstringnoCount of thumbs-down votes on answers in the window.
feedback.satisfaction_ratestringnoup / (up + down) in [0,1], or null when no votes.
verdictsobjectnoAnalysis-pass answer-quality classification distribution.
verdicts.confidentnumbernoTurns classified confident by the analysis pass.
verdicts.unconfidentnumbernoTurns classified unconfident by the analysis pass.
verdicts.not_foundnumbernoTurns classified not_found (no answer in the docs).
verdicts.doc_gapnumbernoTurns classified doc_gap (a documentation coverage gap).
analyzedstringnoTurns with any verdict: sum of the four verdicts counts.
uncertainty_ratestringnoFlagged (unconfident+not_found+doc_gap) over analyzed, or null.
engagementobjectnoEscalation/contact-link beacon counts driving deflection.
engagement.escalation_shownnumbernoTimes the escalation/contact link was shown under a downvoted answer.
engagement.escalation_clicknumbernoTimes a reader clicked the escalation/contact link.
deflection_ratestringno1 − escalation_click / answers, clamped [0,1]; null when no escalations or answers.
languagesarray<object>noTop query languages by turn count (max 12, descending).
languages[].languagestringnoISO query-language code from the analysis pass.
languages[].countintegernoTurns analyzed in this language during the window.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/activity?days={days}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "window_days": 0,
  "since": 0,
  "until": 0,
  "conversations": 0,
  "answers": 0,
  "feedback": {
    "up": "string",
    "down": "string",
    "satisfaction_rate": "string"
  },
  "verdicts": {
    "confident": 0,
    "unconfident": 0,
    "not_found": 0,
    "doc_gap": 0
  },
  "analyzed": "string",
  "uncertainty_rate": "string",
  "engagement": {
    "escalation_shown": 0,
    "escalation_click": 0
  },
  "deflection_rate": "string",
  "languages": [
    {
      "language": "string",
      "count": 0
    }
  ]
}
GET

Authoring analytics

https://gateway.aardvarkdocs.com/v1/authoring-analytics

Per-type counts and the most recent authoring events over the last 90 days. Returns clean empty shapes when no rows exist.

Responses

Body

eventsarray<object>noPer-event_type counts over the last 90 days, busiest type first (≤500 types).
events[].event_typestringnoClient-defined authoring event name, e.g. suggestion_accepted.
events[].countintegernoNumber of events of this event_type recorded within the 90-day window.
recentarray<object>noThe most recent authoring events, newest first (≤50), within the 90-day window.
recent[].event_typestringnoClient-defined authoring event name for this row.
recent[].detailstringnoOptional free-text payload sent with the event; null when omitted.
recent[].tsintegernoEpoch-ms time the event was recorded.
totalintegernoTotal events over the last 90 days, summed from the per-type events counts.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/authoring-analytics' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "events": [
    {
      "event_type": "string",
      "count": 0
    }
  ],
  "recent": [
    {
      "event_type": "string",
      "detail": "string",
      "ts": 0
    }
  ],
  "total": 0
}
GET

Conversation detail

https://gateway.aardvarkdocs.com/v1/conversations

Recent turns grouped into conversations, each with the reader vote and (when available) an automated analysis verdict. filter=needs_attention restricts to low-confidence / doc-gap / not-found turns; verdict/intent/vote/q/tag narrow it further.

verdictquerystringnoRestrict to a single analysis verdict.
filterquerystringnoSet to needs_attention to restrict the result (default all).
intentquerystringnoRestrict to a single detected intent.
votequerystringnoRestrict to up/down votes.
qquerystringnoFree-text search over question/answer.
tagquerystringnoRestrict to a custom tag.
sincequeryintegernoEpoch-ms lower bound; keeps turns with ts >= this (inclusive).
untilqueryintegernoEpoch-ms upper bound; keeps turns with ts < this (exclusive).

Responses

Body

conversationsarray<object>noRecent turns grouped by conversation_id, newest conversation first, turns ascending within.
truncatedbooleannotrue when more matching turns exist beyond the 100-turn list cap.
filterstringnoBack-compat toggle echo: needs_attention when that legacy filter applied, else all.
filtersarray<string>noActive-filter chips, e.g. verdict:doc_gap, intent:troubleshooting, vote:up, tag:<name>, q, date, needs_attention.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/conversations?verdict={verdict}&filter={filter}&intent={intent}&vote={vote}&q={q}&tag={tag}&since={since}&until={until}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "conversations": [
    {}
  ],
  "truncated": true,
  "filter": "string",
  "filters": [
    "string"
  ]
}
GET

Export conversations

https://gateway.aardvarkdocs.com/v1/conversations/export.csv

CSV of the conversation turns matching the same filters as GET /v1/conversations (every cell formula-injection-guarded). An X-Aardvark-Export-Truncated: true response header signals the export cap was hit.

verdictquerystringnoRestrict to a single analysis verdict.
filterquerystringnoSet to needs_attention to restrict the result (default all).
intentquerystringnoRestrict to a single detected intent.
votequerystringnoRestrict to up/down votes.
qquerystringnoFree-text search over question/answer.
tagquerystringnoRestrict to a custom tag.
sincequeryintegernoEpoch-ms lower bound; keeps turns with ts >= this (inclusive).
untilqueryintegernoEpoch-ms upper bound; keeps turns with ts < this (exclusive).

Responses

Body

A single string value.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/conversations/export.csv?verdict={verdict}&filter={filter}&intent={intent}&vote={vote}&q={q}&tag={tag}&since={since}&until={until}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

"string"
GET

Get digest prefs

https://gateway.aardvarkdocs.com/v1/digest

The account’s insight-digest opt-in: whether enabled, the cadence, and when it was last_sent_ts.

Responses

Body

enabledbooleannoWhether the account is opted into the periodic emailed insights digest; false by default.
cadencestringnoDigest frequency, one of week or month; defaults to week.
last_sent_tsintegernoEpoch-ms watermark of the last digest send; 0 when never sent.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/digest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "enabled": true,
  "cadence": "string",
  "last_sent_ts": 0
}
POST

Set digest prefs

https://gateway.aardvarkdocs.com/v1/digest

Opt the account owner into (or out of) a weekly/monthly emailed insights digest. Owner only. Owner only.

Responses

Body

okbooleannoAlways true; the digest preferences were saved.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/digest' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true
}
GET

Thumbs summary

https://gateway.aardvarkdocs.com/v1/feedback

The owner-facing READ of reader thumbs votes — the capture POST is POST /v1/feedback. Returns up/down counts, the satisfaction rate, and recent rated answers. Dashboard-authed (session OR secret key); a public key is rejected at the door.

Responses

Body

upnumbernoCount of thumbs-up votes in the window.
downnumbernoCount of thumbs-down votes in the window.
totalintegernoTotal votes (up + down).
up_ratestringnoup / (up + down) in [0,1], or null when there are no votes.
recentarray<object>noRecent rated answer turns, newest first.
recent[].tsintegernoEpoch-ms time the vote was recorded.
recent[].conversation_idstringnoConversation the rated answer belongs to.
recent[].turnintegernoAnswer index within the conversation.
recent[].votestringnoThe reader’s verdict, up or down.
recent[].questionstringnoThe rated user question.
recent[].answerstringnoThe rated assistant answer.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "up": 0,
  "down": 0,
  "total": 0,
  "up_rate": "string",
  "recent": [
    {
      "ts": 0,
      "conversation_id": "string",
      "turn": 0,
      "vote": "string",
      "question": "string",
      "answer": "string"
    }
  ]
}
GET

Feedback summary

https://gateway.aardvarkdocs.com/v1/feedback/summary

One cross-stream snapshot of the account's reader feedback over a recent 30-day window — thumbs, page ratings, survey responses, and conversation sentiment — powering the metric tiles at the top of the dashboard Feedback panel. Each sub-stream degrades to zeros if its backing table isn't present yet.

Responses

Body

window_daysintegernoLook-back window in days for the snapshot (fixed at 30, matching the Insights tab).
sinceintegernoEpoch-ms start of the window (now - 30 days).
ratingsstringnoPage star-rating aggregates over the window; zeros until that stream's table lands.
thumbsarray<any>noThumbs-vote totals over the window (always present — the feedback table ships on main).
surveysstringnoStructured survey-response aggregates over the window; zeros until that stream's table lands.
sentimentarray<any>noConversation-sentiment distribution over the window; zeros until that stream's table lands.
recent_activitystringnoA small recent-activity feed across the streams for the panel header.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/feedback/summary' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "window_days": 0,
  "since": 0,
  "ratings": "string",
  "thumbs": [],
  "surveys": "string",
  "sentiment": [],
  "recent_activity": "string"
}
POST

Set triage status

https://gateway.aardvarkdocs.com/v1/insight-status

Mark a clustered insight (by label) as e.g. triaged/resolved with an optional note — drives the dashboard’s coverage-gap workflow.

Responses

Body

okbooleannoAlways true; the gap’s triage status (and note) was recorded.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/insight-status' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true
}
GET

Clustered insights

https://gateway.aardvarkdocs.com/v1/insights

The cron-clustered analytics surface: live metrics plus Top Questions and Coverage Gaps for the selected period, with prior-period deltas when available.

daysqueryintegernoRolling window in days.
period_kindquerystringnoNamed period bucket (e.g. week / month).
period_startqueryintegernoPeriod start, epoch ms.

Responses

Body

window_daysintegernoLength of the live-metrics window in days; from ?days=, default 30, capped at 90.
bucket_msintegernoVolume-series bucket width in ms: 3600000 (hourly) when window <=2 days, else 86400000 (daily).
sinceintegernoInclusive start of the live-metrics window, epoch ms (now - window_days*day).
untilintegernoExclusive end of the live-metrics window, epoch ms (request time).
generated_tsintegernoEpoch-ms write time of the shown cluster snapshot (max row ts); null if never clustered.
periodobjectnoThe calendar period this Top Questions / Coverage Gaps snapshot covers; null if never clustered.
period.kindstringnoPeriod granularity: one of week, month, or quarter (legacy for pre-versioning rows).
period.startstringnoInclusive start of the period, epoch ms (week = Monday 00:00 UTC).
period.endstringnoExclusive end of the period, epoch ms (0 for legacy rows).
periodsarray<object>noNavigable history of clustered periods for this kind, newest first.
periods[].kindstringnoPeriod granularity of this history entry: week, month, or quarter.
periods[].startstringnoInclusive start of this history period, epoch ms.
periods[].endstringnoExclusive end of this history period, epoch ms.
has_priorbooleannoTrue when the immediately prior period has clusters to compute per-cluster trends against.
metricsobjectnoLive engagement metrics over the ?days= window (computed on demand, not snapshotted).
metrics.turnsnumbernoCount of answer turns (transcripts) in the window.
metrics.conversationsnumbernoCount of distinct conversations in the window.
metrics.votesobjectnoReader thumbs-up/down tallies over the window.
metrics.votes.upnumbernoNumber of thumbs-up votes in the window.
metrics.votes.downnumbernoNumber of thumbs-down votes in the window.
metrics.verdictsobjectnoDistribution of analysis classifications over turns in the window.
metrics.verdicts.confidentnumbernoTurns classified confident by the analysis pass.
metrics.verdicts.unconfidentnumbernoTurns classified unconfident by the analysis pass.
metrics.verdicts.not_foundnumbernoTurns classified not_found (no answer found) by the analysis pass.
metrics.verdicts.doc_gapnumbernoTurns classified doc_gap (a documentation gap) by the analysis pass.
metrics.seriesarray<object>noTurns-per-time-bucket volume series (sparse; client fills gaps), oldest first.
metrics.series[].bucket_tsintegernoBucket start, epoch ms, floored to bucket_ms.
metrics.series[].countintegernoNumber of turns falling in this bucket.
metrics.engagementobjectnoEscalation/contact-link beacon counts driving the support-deflection metric.
metrics.engagement.escalation_shownnumbernoTimes the escalation/contact link was shown under a downvoted answer.
metrics.engagement.escalation_clicknumbernoTimes the escalation/contact link was clicked.
metrics.languagesarray<object>noReader query-language distribution, most-frequent first (top 12).
metrics.languages[].languagestringnoDetected query language (from conversation_analysis.language).
metrics.languages[].countintegernoNumber of turns in this language within the window.
top_questionsarray<object>noClustered Top Questions for the period, biggest cluster first.
top_questions[].labelstringnoShort human label naming the question theme.
top_questions[].countintegernoApproximate number of reader questions in this cluster.
top_questions[].examplesstringnoUp to 3 representative example questions for this cluster.
coverage_gapsarray<object>noClustered Coverage Gaps (flagged turns grouped into doc-gap topics), biggest first.
coverage_gaps[].labelstringnoShort human label naming the coverage-gap topic.
coverage_gaps[].findingstringnoWhat readers asked and why the assistant struggled (may be null).
coverage_gaps[].recommendationstringnoConcrete documentation change that would fix the gap (may be null).
coverage_gaps[].countintegernoApproximate number of flagged turns in this cluster.
coverage_gaps[].examplesstringnoUp to 3 representative example questions for this gap.
coverage_gaps[].statusstringnoTriage state set via /v1/insight-status; defaults to open when untouched.
coverage_gaps[].notestringnoOptional triage note attached to this gap; null when none.
coverage_gaps[].status_updated_atstringnoEpoch-ms time the gap's triage status was last set; null when untouched.
sourcesobjectnoDoc-page citation analytics over the metrics window.
sources.pagesarray<object>noMost-cited doc pages in the window, busiest first (up to 20).
sources.pages[].pagestringnoSite-relative path of the cited documentation page.
sources.pages[].citationsnumbernoTimes this page was cited as a source in the window.
sources.pages[].downvotednumbernoOf those citations, how many sat on a downvoted answer.
sources.totalintegernoTotal source-citation events recorded across all pages in the window.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/insights?days={days}&period_kind={period_kind}&period_start={period_start}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "window_days": 0,
  "bucket_ms": 0,
  "since": 0,
  "until": 0,
  "generated_ts": 0,
  "period": {
    "kind": "string",
    "start": "string",
    "end": "string"
  },
  "periods": [
    {
      "kind": "string",
      "start": "string",
      "end": "string"
    }
  ],
  "has_prior": true,
  "metrics": {
    "turns": 0,
    "conversations": 0,
    "votes": {
      "up": 0,
      "down": 0
    },
    "verdicts": {
      "confident": 0,
      "unconfident": 0,
      "not_found": 0,
      "doc_gap": 0
    },
    "series": [
      {
        "bucket_ts": 0,
        "count": 0
      }
    ],
    "engagement": {
      "escalation_shown": 0,
      "escalation_click": 0
    },
    "languages": [
      {
        "language": "string",
        "count": 0
      }
    ]
  },
  "top_questions": [
    {
      "label": "string",
      "count": 0,
      "examples": "string"
    }
  ],
  "coverage_gaps": [
    {
      "label": "string",
      "finding": "string",
      "recommendation": "string",
      "count": 0,
      "examples": "string",
      "status": "string",
      "note": "string",
      "status_updated_at": "string"
    }
  ],
  "sources": {
    "pages": [
      {
        "page": "string",
        "citations": 0,
        "downvoted": 0
      }
    ],
    "total": 0
  }
}
POST

Ask the assistant

https://gateway.aardvarkdocs.com/v1/insights/assistant

Natural-language Q&A over the account's analytics. Metered against the account balance (it calls the model), so it can return 402/429/502/503 like the chat endpoint.

Responses

Body

answerstringnoNatural-language reply about the account's analytics; a canned message when no data exists yet.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/insights/assistant' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "answer": "string"
}
GET

MCP tool analytics

https://gateway.aardvarkdocs.com/v1/mcp-analytics

Top tools, recent calls, and a bucketed time series over a window of days (default 7, max 90). Buckets are hourly for ≤2 days, daily otherwise.

daysqueryintegernoWindow in days (1–90).

Responses

Body

window_daysintegernoResolved look-back window in days (?days=, default 7, capped at 90).
bucket_msintegernoTime-series bucket width in ms: hourly (3600000) for windows ≤2 days, else daily (86400000).
sinceintegernoEpoch-ms start of the window (inclusive); until minus window_days.
untilintegernoEpoch-ms end of the window (exclusive); the request time now.
toolsarray<object>noPer-tool call counts in the window, ordered by count descending then tool name.
tools[].toolstringnoMCP tool name as beaconed by the docs MCP server.
tools[].countintegernoNumber of calls to this tool within the window.
recentarray<object>noMost recent individual tool calls, newest first, up to 100.
recent[].toolstringnoMCP tool name for this individual call.
recent[].args_summarystringnoShort human-readable summary of the call’s arguments; null when none was recorded.
recent[].tsintegernoEpoch-ms time the tool call was recorded.
seriesarray<object>noSparse per-bucket call counts over the window; only non-empty buckets, ascending by time.
series[].bucket_tsintegernoEpoch-ms floored start of the bucket (ts floored to bucket_ms).
series[].countintegernoNumber of tool calls falling in this bucket.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/mcp-analytics?days={days}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "window_days": 0,
  "bucket_ms": 0,
  "since": 0,
  "until": 0,
  "tools": [
    {
      "tool": "string",
      "count": 0
    }
  ],
  "recent": [
    {
      "tool": "string",
      "args_summary": "string",
      "ts": 0
    }
  ],
  "series": [
    {
      "bucket_ts": 0,
      "count": 0
    }
  ]
}
GET

Page ratings

https://gateway.aardvarkdocs.com/v1/page-ratings

The dashboard READ of reader star ratings: the overall average, total count, and a per-page breakdown. Dashboard-authed like /v1/insights.

Responses

Body

overall_avgnumbernoMean star rating across all pages, or null when there are no ratings.
totalintegernoTotal number of ratings submitted.
pagesarray<any>noPer-page rating rollups (path, average, count), busiest first.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/page-ratings' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "overall_avg": 0,
  "total": 0,
  "pages": []
}
GET

Search analytics

https://gateway.aardvarkdocs.com/v1/search-analytics

On-site search analytics over a window of days (default 30, max 90): top searches, zero-result queries, click-through, average clicked position, searches-per-session, no-click rate, Ask-AI escalation rate, top clicked pages, a language split, and a bucketed volume series (hourly for ≤2 days, daily otherwise).

daysqueryintegernoWindow in days (1–90; default 30).

Responses

Body

window_daysintegernoResolved look-back window in days (?days=, default 30, capped at 90).
bucket_msintegernoTime-series bucket width in ms: hourly (3600000) for windows ≤2 days, else daily (86400000).
sinceintegernoEpoch-ms start of the window (inclusive).
untilintegernoEpoch-ms end of the window (exclusive); the request time now.
totalsobjectno
totals.queriesnumbernoNumber of search queries in the window.
totals.clicksnumbernoNumber of result clicks in the window.
totals.askAinumbernoNumber of Ask-AI escalations from search.
totals.sessionsnumbernoDistinct search sessions in the window.
totals.zeroResultsnumbernoNumber of queries that returned no results.
ctrnumbernoClicks divided by queries (a ratio; can exceed 1 when a reader opens several results for one search).
askAiRatenumbernoAsk-AI escalations divided by queries.
searchesPerSessionnumbernoQueries divided by distinct sessions.
noClickSessionRatenumbernoFraction of searching sessions that never clicked a result.
avgPositionnumbernoMean 1-based rank of clicked results; omitted when there are no clicks.
avgLatencyMsnumbernoMean client-side scorer time in ms; omitted when no latency was reported.
topTermsarray<object>no
topTerms[].termstringnoA representative raw query term for the group. Searches are grouped by an accent-folded/lowercased key (so "café"/"Cafe"/"CAFÉ" count as one), but the displayed term is a real raw variant, not the folded key.
topTerms[].searchesnumbernoNumber of searches for this term (across all accent/case variants of it).
topTerms[].zeroResultsnumbernoHow many of those searches returned no results.
zeroResultTermsarray<object>no
zeroResultTerms[].termstringnoA representative raw query term that returned nothing (a content gap), grouped by the same accent-folded/lowercased key as topTerms.
zeroResultTerms[].countnumbernoNumber of zero-result searches for this term.
topClickedPagesarray<object>no
topClickedPages[].pagestringnoA clicked result page path.
topClickedPages[].clicksnumbernoNumber of clicks to this page from search.
byLangarray<object>no
byLang[].langstringnoReader/page language tag.
byLang[].countnumbernoNumber of queries in this language.
seriesarray<object>no
series[].bucket_tsnumbernoEpoch-ms floored start of the bucket.
series[].countnumbernoNumber of queries in this bucket.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/search-analytics?days={days}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "window_days": 0,
  "bucket_ms": 0,
  "since": 0,
  "until": 0,
  "totals": {
    "queries": 0,
    "clicks": 0,
    "askAi": 0,
    "sessions": 0,
    "zeroResults": 0
  },
  "ctr": 0,
  "askAiRate": 0,
  "searchesPerSession": 0,
  "noClickSessionRate": 0,
  "avgPosition": 0,
  "avgLatencyMs": 0,
  "topTerms": [
    {
      "term": "string",
      "searches": 0,
      "zeroResults": 0
    }
  ],
  "zeroResultTerms": [
    {
      "term": "string",
      "count": 0
    }
  ],
  "topClickedPages": [
    {
      "page": "string",
      "clicks": 0
    }
  ],
  "byLang": [
    {
      "lang": "string",
      "count": 0
    }
  ],
  "series": [
    {
      "bucket_ts": 0,
      "count": 0
    }
  ]
}
GET

Reader sentiment

https://gateway.aardvarkdocs.com/v1/sentiment

The positive/neutral/negative distribution of analyzed conversations over a recent window, plus recent example messages, for the reader-feedback panel. Dashboard-authed like /v1/insights.

Responses

Body

positiveintegernoCount of conversations the analysis pass classified positive.
neutralintegernoCount classified neutral.
negativeintegernoCount classified negative.
totalintegernoTotal classified conversations (positive + neutral + negative).
recent_positivestringnoA few recent example messages classified positive.
recent_negativestringnoA few recent example messages classified negative.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/sentiment' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "positive": 0,
  "neutral": 0,
  "negative": 0,
  "total": 0,
  "recent_positive": "string",
  "recent_negative": "string"
}
GET

Survey results

https://gateway.aardvarkdocs.com/v1/surveys

The dashboard READ of structured survey answers: per-question aggregates (choice bars + rating averages) plus recent open-ended survey comments. Dashboard-authed like /v1/usage.

Responses

Body

surveysarray<object>noPer-survey question aggregates.
surveys[].question_idstringnoIsland-defined question id.
surveys[].question_typestringnoQuestion kind: single, multi, rating, or text.
surveys[].totalintegernoNumber of respondents to the question.
surveys[].rating_countintegernoNumber of rating answers folded into rating_avg.
surveys[].choicesarray<object>noPer-option counts for a choice question, most-picked first.
surveys[].choices[].valuestringnoThe chosen option label.
surveys[].choices[].countintegernoHow many respondents picked this option.
surveys[].rating_avgstringnoMean of the rating answers, or null for a non-rating question / no ratings.
commentsarray<object>noRecent open-ended survey comments (the survey-scoped page_comments rows).
comments[].tsintegernoEpoch-ms time the comment was submitted.
comments[].page_urlstringnoSite-relative path the comment was left on, or null.
comments[].commentstringnoReader-supplied open-ended comment text (escaped before display).
truncatedbooleannotrue when more comments exist beyond the returned cap.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/surveys' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "surveys": [
    {
      "question_id": "string",
      "question_type": "string",
      "total": 0,
      "rating_count": 0,
      "choices": [
        {
          "value": "string",
          "count": 0
        }
      ],
      "rating_avg": "string"
    }
  ],
  "comments": [
    {
      "ts": 0,
      "page_url": "string",
      "comment": "string"
    }
  ],
  "truncated": true
}
GET

List custom tags

https://gateway.aardvarkdocs.com/v1/tags

The account’s custom tag vocabulary (tags) and the per-account cap (max).

Responses

Body

tagsarray<object>noThe account’s active (non-deleted) custom tags, sorted alphabetically by name.
tags[].idstringnoOpaque UUID identifying the tag.
tags[].namestringnoDisplay label of the tag, unique per account; no semicolons or control characters.
tags[].descriptionstringnoOptional guidance steering how the analysis pass applies this tag; null if unset.
tags[].tsintegernoEpoch-ms time the tag was created.
tags[].usesnumbernoCount of conversations currently labeled with this tag.
maxnumbernoMaximum active tags allowed per account (default 20).

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/tags' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "tags": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "ts": 0,
      "uses": 0
    }
  ],
  "max": 0
}
POST

Create a custom tag

https://gateway.aardvarkdocs.com/v1/tags

Add a custom tag to the account vocabulary. Owner/admin only; 409 on a duplicate name or when the per-account cap is reached. Owner only.

Responses

Body

okbooleannoAlways true once the tag is created and added to the account vocabulary.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/tags' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true
}
POST

Edit or delete a tag

https://gateway.aardvarkdocs.com/v1/tags/{id}

Edit a tag’s description and/or soft-delete it (deleted: true hides it from the vocabulary without dropping the labels already applied to conversations). Owner/admin only; at least one of description/deleted must be supplied, and 404 if no tag matches the id. Owner only.

idpathstringyesTag id — the trailing path segment after /v1/tags/ (≤100 chars).

Responses

Body

okbooleannoAlways true once the update (or soft-delete) is applied.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/tags/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true
}
GET

List answer turns

https://gateway.aardvarkdocs.com/v1/threads

A flat, cursor-paged feed of answer turns in ascending (ts, conversation_id, turn) order (oldest first) — built for forward incremental sync. Page with next_cursor / has_more.

sincequeryintegernoCursor: return turns at or after this epoch-ms timestamp (inclusive lower bound), or pass a prior page’s next_cursor.
limitqueryintegernoMax turns to return.

Responses

Body

turnsarray<object>noPage of recent answer turns, ascending by the (ts, conversation_id, turn) sort key.
turns[].conversation_idstringnoConversation this turn belongs to; the reader-island session/thread id.
turns[].turnintegernoZero-based turn index within the conversation.
turns[].questionstringnoThe reader's question text for this turn; null if not stored.
turns[].answerstringnoThe assistant's answer text for this turn; null if not stored.
turns[].reasoningstringnoFull model reasoning for the turn (not truncated); null if absent.
turns[].tsintegernoEpoch-ms time the transcript turn was recorded; the pagination sort key.
turns[].votestringnoReader feedback: up, down, or null when no vote was cast.
turns[].classificationstringnoAnalysis verdict: confident, unconfident, not_found, or doc_gap; null until analyzed.
turns[].summarystringnoOne-sentence analysis summary of the turn; null until analyzed.
turns[].intentstringnoConversation kind: troubleshooting, product_discovery, unsupported_feature, competitor, or off_topic; else null.
turns[].languagestringnoReader question’s language as a short ISO code (e.g. en, ja, pt-BR); null if unknown.
countintegernoNumber of turns returned on this page.
next_cursorstringnoOpaque continuation token to pass as since; null when no further page remains.
has_morebooleannoTrue when another non-empty page exists beyond this one.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/threads?since={since}&limit={limit}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "turns": [
    {
      "conversation_id": "string",
      "turn": 0,
      "question": "string",
      "answer": "string",
      "reasoning": "string",
      "ts": 0,
      "vote": "string",
      "classification": "string",
      "summary": "string",
      "intent": "string",
      "language": "string"
    }
  ],
  "count": 0,
  "next_cursor": "string",
  "has_more": true
}
GET

List transcripts

https://gateway.aardvarkdocs.com/v1/transcripts

Returns the account’s stored transcripts grouped into conversations (newest first), each turn carrying its vote. Capped at ~300 turns; truncated signals older history exists.

Responses

Body

conversationsarray<object>noStored conversations, newest first; each holds its turns (turn, question, answer, vote) ascending.
truncatedbooleannotrue when older turns exist beyond the ~300-turn cap and were omitted.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/transcripts' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "conversations": [
    {}
  ],
  "truncated": true
}
GET

Account snapshot

https://gateway.aardvarkdocs.com/v1/usage

The dashboard overview payload: account status, balance, recent usage rows, top-ups, reader feedback/comments, account events, and the payment/auto-top-up configuration. Readable even when the account is suspended.

Responses

Body

accountobjectnoAccount identity and current standing block.
account.idstringnoThe caller's account id.
account.owner_emailstringnoBilling-account owner’s email from the accounts row (not a member’s address).
account.statusstringnoAccount state, e.g. active, suspended, closed, or unknown if the row is missing.
account.suspensionobjectnoActive-suspension summary when status is suspended; otherwise null.
account.suspension.reasonstringnoWhy the account was paused: cost_unavailable, operator, or self_serve.
account.suspension.tsintegernoEpoch-ms time the suspension was recorded.
account.suspension.request_idstringnoRequest id that triggered the suspension, for support correlation.
account.suspension.self_serviceablebooleannoWhether the dashboard Reactivate button applies; true only for a cost_unavailable pause.
balanceobjectnoCurrent balance snapshot from the Durable Object, in USD.
balance.balance_usdnumbernoTotal account balance in USD.
balance.reserved_usdnumbernoFunds reserved against in-flight requests, in USD.
balance.available_usdnumbernoSpendable balance in USD (balance_usd minus reserved_usd).
anomaly_pausedbooleannoWhether the spend-velocity circuit breaker has paused paid AI (free models keep serving). Visible to every caller; resuming is owner/admin via POST /v1/billing/resume-ai.
subscriptionobjectnoThe account’s live subscription plan + included-AI grant meter (the same object GET /v1/billing returns), or null on the free pay-as-you-go plan. Present only for owner/admin callers; omitted for members.
usagearray<object>noUp to 50 most recent metered-request ledger rows, newest first.
usage[].tsintegernoEpoch-ms time the usage row was written.
usage[].modelstringnoUpstream model slug billed for the request.
usage[].prompt_tokensintegernoInput token count for the request.
usage[].completion_tokensintegernoOutput token count for the request.
usage[].openrouter_usdnumbernoPublished OpenRouter list cost in USD (pre-markup; not the operator's backend cost).
usage[].billed_usdnumbernoAmount charged to the account in USD (list cost times markup).
usage[].generation_idstringnoUpstream generation id used to reconcile the final cost.
usage[].cost_sourcestringnoHow the cost was derived: inline, generation_api, or provisional.
usage[].sourcestringno
topupsarray<object>noUp to 20 most recent balance credits, newest first. Present only for owner/admin callers; omitted for members.
topups[].tsintegernoEpoch-ms time the top-up was credited.
topups[].amount_usdnumbernoCredited amount in USD.
topups[].sourcestringnoOrigin of the credit, e.g. stripe, auto_topup, or an operator grant.
topups[].notestringnoOptional free-text note attached to the credit.
feedbackarray<object>noUp to 50 most recent reader thumbs votes, newest first.
feedback[].tsintegernoEpoch-ms time the vote was recorded.
feedback[].conversation_idstringnoConversation the rated answer belongs to.
feedback[].votestringnoReader’s verdict, up or down.
feedback[].questionstringnoThe reader question that the rated answer addressed.
commentsarray<object>noUp to 50 most recent reader page comments, newest first.
comments[].tsintegernoEpoch-ms time the comment was submitted.
comments[].page_urlstringnoSite-relative path the comment was left on, or null.
comments[].commentstringnoReader-supplied open-ended comment text (escaped before display).
eventsarray<object>noUp to 20 most recent account decision-log entries, newest first.
events[].tsintegernoEpoch-ms time the event was recorded.
events[].eventstringnoDecision type: suspended, reactivated, or closed.
events[].reasonstringnoReason code: cost_unavailable, operator, or self_serve.
events[].actorstringnoWho made the change: system, operator, owner, or admin.
events[].request_idstringnoRequest id correlated with the event, if any.
paymentobjectnoCard-on-file and auto-top-up configuration for the Billing section. Present only for owner/admin callers; omitted for members.
payment.stripe_enabledbooleannoWhether the gateway has a Stripe secret key and can accept card payments at all.
payment.has_cardbooleannoWhether a card is saved on file for the account.
payment.cardobjectnoDisplay-only details of the saved card, or null when none.
payment.card.brandstringnoCard brand, e.g. visa.
payment.card.last4stringnoLast four digits of the saved card.
payment.card.exp_monthintegernoCard expiry month, 1-12.
payment.card.exp_yearintegernoCard expiry year, four digits.
payment.auto_topup_enabledbooleannoWhether auto top-up is turned on.
payment.auto_topup_amount_usdnumbernoAmount charged per auto top-up in USD, or null when unset.
payment.auto_topup_failuresintegernoConsecutive auto-top-up charge failures since the last success.
payment.auto_topup_last_errorstringnoMessage from the most recent auto-top-up failure, or null.
payment.low_balance_usdintegernoAvailable-balance threshold in USD that triggers an auto top-up.
payment.min_usdnumbernoMinimum allowed auto-top-up charge amount in USD.
payment.max_usdnumbernoMaximum allowed top-up amount in USD (Stripe per-charge technical limit).
payment_eventsarray<object>noUp to 20 most recent billing-activity entries (card lifecycle, declined charges), newest first. Present only for owner/admin callers; omitted for members.
payment_events[].tsintegernoEpoch-ms time the payment event was recorded.
payment_events[].typestringnoEvent type, e.g. card saved/removed or a charge succeeded/declined.
payment_events[].amount_usdnumbernoCharge amount in USD, or null for non-charge events.
payment_events[].detailstringnoFree-text detail about the event, e.g. a decline reason.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "account": {
    "id": "string",
    "owner_email": "string",
    "status": "string",
    "suspension": {
      "reason": "string",
      "ts": 0,
      "request_id": "string",
      "self_serviceable": true
    }
  },
  "balance": {
    "balance_usd": 0,
    "reserved_usd": 0,
    "available_usd": 0
  },
  "anomaly_paused": true,
  "subscription": {},
  "usage": [
    {
      "ts": 0,
      "model": "string",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "openrouter_usd": 0,
      "billed_usd": 0,
      "generation_id": "string",
      "cost_source": "string",
      "source": "string"
    }
  ],
  "topups": [
    {
      "ts": 0,
      "amount_usd": 0,
      "source": "string",
      "note": "string"
    }
  ],
  "feedback": [
    {
      "ts": 0,
      "conversation_id": "string",
      "vote": "string",
      "question": "string"
    }
  ],
  "comments": [
    {
      "ts": 0,
      "page_url": "string",
      "comment": "string"
    }
  ],
  "events": [
    {
      "ts": 0,
      "event": "string",
      "reason": "string",
      "actor": "string",
      "request_id": "string"
    }
  ],
  "payment": {
    "stripe_enabled": true,
    "has_card": true,
    "card": {
      "brand": "string",
      "last4": "string",
      "exp_month": 0,
      "exp_year": 0
    },
    "auto_topup_enabled": true,
    "auto_topup_amount_usd": 0,
    "auto_topup_failures": 0,
    "auto_topup_last_error": "string",
    "low_balance_usd": 0,
    "min_usd": 0,
    "max_usd": 0
  },
  "payment_events": [
    {
      "ts": 0,
      "type": "string",
      "amount_usd": 0,
      "detail": "string"
    }
  ]
}
GET

Billing usage by member and account key

https://gateway.aardvarkdocs.com/v1/usage/members

Owner/admin billing usage grouped by the team member who minted each key, over an optional [since, until) window. Account-owned secret/admin/CLI usage is listed as one row per key with safe key metadata.

sincequeryintegernoInclusive lower bound, epoch ms (default: 30 days ago).
untilqueryintegernoExclusive upper bound, epoch ms (default: now).

Responses

Body

sinceintegernoInclusive start of the resolved [since, until) window, epoch-ms.
untilintegernoExclusive end of the resolved [since, until) window, epoch-ms (clamped to now).
membersarray<object>noUsage groups, sorted by spend descending with member rows before account-owned key rows on ties.
members[].user_idstringnoUser who minted the keys, or null for an account-owned key row.
members[].emailstringnoMember’s email, or null for an account-owned key row or a since-deleted user.
members[].key_idstringnoId of the account-owned key this row aggregates, or null for a member-attributed row.
members[].key_prefixstringnoNon-secret prefix of the account-owned key, or null for a member-attributed row.
members[].key_labelstringnoDisplay label of the account-owned key, or null for a member-attributed row.
members[].key_modestringnopublic or secret for an account-owned key row, or null for a member-attributed row.
members[].is_account_keybooleannotrue when this row aggregates an account-owned key (user_id is null) rather than a member.
members[].is_clibooleannoBack-compat alias for is_account_key; true when user_id is null.
members[].labelstringnoDisplay name: key label/prefix for account-owned key rows, else the member email, else (member <id8>) for a deleted user.
members[].requestsintegernoNumber of usage-ledger rows (requests) attributed to this member or account-owned key.
members[].prompt_tokensintegernoSummed prompt (input) tokens across this row's requests.
members[].completion_tokensintegernoSummed completion (output) tokens across this row's requests.
members[].total_tokensintegernoSum of prompt_tokens and completion_tokens for this row.
members[].billed_usdnumbernoTotal amount billed to this row over the window, in USD.
totalsobjectnoGrand-total summary across all rows for the window.
totals.requestsintegernoTotal requests across all rows over the window.
totals.prompt_tokensintegernoTotal prompt (input) tokens across all rows.
totals.completion_tokensintegernoTotal completion (output) tokens across all rows.
totals.total_tokensintegernoSum of prompt_tokens and completion_tokens across all rows.
totals.billed_usdnumbernoTotal amount billed across all rows over the window, in USD (summed in micro-USD, converted once).
supportobjectno
support.usersarray<object>no
support.users[].user_idstringno
support.users[].emailstringno
support.users[].labelstringno
support.users[].requestsintegerno
support.users[].prompt_tokensintegerno
support.users[].completion_tokensintegerno
support.users[].total_tokensintegerno
support.users[].billed_usdnumberno
support.totalsobjectno
support.totals.requestsintegerno
support.totals.prompt_tokensintegerno
support.totals.completion_tokensintegerno
support.totals.total_tokensintegerno
support.totals.billed_usdnumberno

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/usage/members?since={since}&until={until}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "since": 0,
  "until": 0,
  "members": [
    {
      "user_id": "string",
      "email": "string",
      "key_id": "string",
      "key_prefix": "string",
      "key_label": "string",
      "key_mode": "string",
      "is_account_key": true,
      "is_cli": true,
      "label": "string",
      "requests": 0,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "billed_usd": 0
    }
  ],
  "totals": {
    "requests": 0,
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "billed_usd": 0
  },
  "support": {
    "users": [
      {
        "user_id": "string",
        "email": "string",
        "label": "string",
        "requests": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0,
        "billed_usd": 0
      }
    ],
    "totals": {
      "requests": 0,
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "total_tokens": 0,
      "billed_usd": 0
    }
  }
}

Support tickets.

GET

List support tickets

https://gateway.aardvarkdocs.com/v1/support

Lists tickets for the account. Plain members see only their own; owners/admins/secret-key callers see the whole account. Capped at 100 (newest first).

Responses

Body

itemsarray<object>noSupport tickets for the account, newest first, capped at 100.
items[].idstringnoTicket's UUID, assigned at submission.
items[].categorystringnoTicket kind: one of bug, feature, question, or other.
items[].messagestringnoSubmitter's free-text message, capped at 4000 characters.
items[].statusstringnoTriage state; defaults to open at creation.
items[].tsintegernoEpoch-ms time the ticket was submitted.
truncatedbooleannotrue when more than 100 tickets exist beyond those returned.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/support' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "items": [
    {
      "id": "string",
      "category": "string",
      "message": "string",
      "status": "string",
      "ts": 0
    }
  ],
  "truncated": true
}
POST

Open a support ticket

https://gateway.aardvarkdocs.com/v1/support

Files a ticket to the gateway operator. Fail-hard over the per-account daily cap (429). Sends a best-effort operator email; the stored row is the source of truth.

Responses

Body

okbooleannoAlways true once the ticket row is stored.
idstringnoServer-minted UUID of the stored support ticket.
statusstringnoInitial triage status of a new ticket; always open.
tsintegernoEpoch-ms time the ticket was stored.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/support' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "bug",
  "message": "The usage chart is blank on Safari."
}'

Response examples

{
  "ok": true,
  "id": "string",
  "status": "string",
  "ts": 0
}

In-dashboard support assistant.

POST

Support assistant turn

https://gateway.aardvarkdocs.com/v1/assistant/chat

One metered turn of the dashboard support assistant. The gateway injects the system prompt (identity, plan-and-approve behavior, the docs index) and the account context, forces the latest Sonnet model, and forwards the conversation to the upstream model. Billed to the account (tagged as support spend), so it can return 402/429/503 like the chat endpoint. The reply may include tool_calls the dashboard renders for the user to approve before running.

Responses

Body

rolestringnoAlways assistant.
contentstringnoThe assistant's reply text (may be null on a pure tool-call turn).
tool_callsarray<object>noProposed tool calls from the known menu, for the user to approve; empty on a final answer.
billed_usdnumbernoWhat this turn cost the account, in USD (published rate).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/assistant/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "role": "string",
  "content": "string",
  "tool_calls": [
    {}
  ],
  "billed_usd": 0
}
GET

Fetch a docs page

https://gateway.aardvarkdocs.com/v1/assistant/doc

Server-side fetch of one aardvark documentation page (Markdown) for the assistant’s fetch_doc grounding tool. The path is validated to a same-origin .md page and the body is size-capped.

pathquerystringnoThe docs page’s .md path (relative, no scheme/traversal), e.g. ai-gateway.md.

Responses

Body

pathstringnoThe resolved page path.
textstringnoThe page's Markdown, truncated to the size cap.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/assistant/doc?path={path}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "path": "string",
  "text": "string"
}
POST

Escalate to a human

https://gateway.aardvarkdocs.com/v1/assistant/escalate

File a support ticket (a GitHub issue in the operator’s repo) with the chat history, attempted actions, and account details, for a human to handle. Per-account rate-limited. Records the escalation and mirrors it to the support list; if GitHub filing is unavailable it still records + mirrors and reports filed: false.

Responses

Body

okbooleannoAlways true once the escalation is recorded.
filedbooleannoWhether a GitHub issue was actually created.
issue_numberintegernoThe created issue number, or null if not filed.
issue_urlstringnoThe created issue URL, or null if not filed.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/assistant/escalate' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true,
  "filed": true,
  "issue_number": 0,
  "issue_url": "string"
}

Account self-service.

POST

Reactivate account

https://gateway.aardvarkdocs.com/v1/reactivate

Lifts the gateway's automatic cost-unavailable suspension. Operator-set holds and closed accounts cannot be reactivated here. Idempotent. Owner/admin only.

Responses

Body

statusstringnoAccount status after the call; active on every success path.
changedbooleannotrue if this call lifted the pause; false when already active (no-op).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/reactivate' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "status": "string",
  "changed": true
}

API key management.

GET

List API keys

https://gateway.aardvarkdocs.com/v1/keys

Returns metadata for every key on the account (prefix, mode, label, allowed origins, revoked flag) — never the hash or secret value.

Responses

Body

keysarray<object>noEvery API key on the account, ordered by mode then created_at; metadata only.
keys[].idstringnoOpaque key identifier, used as :id in the per-key management routes.
keys[].modestringnoKey class: public (origin-gateable reader key) or secret (account master credential).
keys[].key_prefixstringnoShort non-secret prefix of the key value, shown to identify the key.
keys[].labelstringnoHuman-set display nickname, or null if unnamed.
keys[].allowed_originsarray<string>noOrigin allowlist for a public key (null means any origin); always null for secret keys.
keys[].revokedbooleannoWhether the key has been revoked and can no longer authenticate.
keys[].created_atnumbernoEpoch-ms time the key was minted.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/keys' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "keys": [
    {
      "id": "string",
      "mode": "string",
      "key_prefix": "string",
      "label": "string",
      "allowed_origins": [
        "string"
      ],
      "revoked": true,
      "created_at": 0
    }
  ]
}
POST

Mint a new API key

https://gateway.aardvarkdocs.com/v1/keys

Creates a public or secret key. The full key value is returned ONCE. Secret keys are owner-only and capped at one active per account (rotate to replace). Public keys may be origin-scoped.

Responses

Body

key_idstringnoUUID row id of the newly minted key, for later rotate/revoke/update calls.
api_keystringnoThe full key value — shown ONCE.
key_prefixstringnoFirst 20 chars of the key (aardvark_live_ or aardvark_secret_ plus a slice), shown for identification.
modestringnoKey class: public (origin-gated, site-embedded) or secret (full account/CLI credential).
labelstringnoDisplay nickname stored for the key; defaults to aardvark <mode> when none given.
warningsarray<string>noAdvisory notices, e.g. an unscoped public key accepting any origin or a risky wildcard origin.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/keys' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "public",
  "label": "docs site",
  "allowed_origins": [
    "https://docs.example.com"
  ]
}'

Response examples

{
  "key_id": "string",
  "api_key": "string",
  "key_prefix": "string",
  "mode": "string",
  "label": "string",
  "warnings": [
    "string"
  ]
}
POST

Rename / rescope key

https://gateway.aardvarkdocs.com/v1/keys/{id}

Updates a key's label and/or a public key's allowed origins. At least one field is required; an omitted field is left unchanged. Non-owners may only update keys they created.

idpathstringyesIdentifier of the key to update.

Responses

Body

allowed_originsarray<any>noOrigin allowlist now set on the public key; null means any origin is accepted.
warningsarray<string>noNon-fatal advisories, e.g. unrestricted-origin or shared-wildcard cautions about the new config.
labelstringnoNew display nickname after the rename; null when the label was cleared or omitted.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/keys/{id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "allowed_origins": [],
  "warnings": [
    "string"
  ],
  "label": "string"
}
POST

Revoke a public key

https://gateway.aardvarkdocs.com/v1/keys/{id}/revoke

Permanently revokes a PUBLIC key. Secret keys cannot be bare-revoked (rotate them instead) to avoid locking the owner out.

idpathstringyesIdentifier of the public key to revoke.

Responses

Body

revokedbooleannoAlways true on success; a missing or non-public key returns a 404 error instead.
key_idstringnoId of the public key that was revoked, echoing the path {id}.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/keys/{id}/revoke' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "revoked": true,
  "key_id": "string"
}
POST

Hard-rotate a key

https://gateway.aardvarkdocs.com/v1/keys/{id}/rotate

Revokes the key and mints a same-mode replacement atomically. The new value is shown once. Non-owners may only rotate keys they created; a demoted member cannot rotate the account secret key.

idpathstringyesIdentifier of the key to rotate.

Responses

Body

key_idstringnoId of the freshly minted replacement key (a new UUID).
api_keystringnoThe full replacement key value — shown ONCE.
key_prefixstringnoDisplay prefix of the new key value (mode-dependent: public vs secret prefix).
modestringnoMode carried over to the replacement: public or secret.
rotated_fromstringnoId of the now-revoked original key this replacement supersedes.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/keys/{id}/rotate' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "key_id": "string",
  "api_key": "string",
  "key_prefix": "string",
  "mode": "string",
  "rotated_from": "string"
}

Team & invites.

GET

Members & invites

https://gateway.aardvarkdocs.com/v1/team

Returns the account's members. Owners/admins also see pending invites; plain members see members only.

Responses

Body

membersarray<object>noActive members on the shared billing account, oldest membership (the owner) first.
members[].user_idstringnoStable id of the member's user record.
members[].emailstringnoMember’s login email, joined from the users table.
members[].rolestringnoMember’s tier on the account: owner, admin, or member.
members[].statusstringnoMembership state; always active here (invited/removed rows are excluded).
members[].created_atnumbernoEpoch-ms time the membership was created (account join).
invitesarray<object>noPending unconsumed invites; present only for owner/admin callers, else empty.
invites[].emailstringnoEmail the invite was sent to (not yet accepted).
invites[].rolestringnoRole the invite will grant on accept: member or admin.
invites[].expires_atnumbernoEpoch-ms time the invite link expires (~7 days after issue).
invites[].created_atnumbernoEpoch-ms time the invite was issued; newest invites listed first.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/team' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "members": [
    {
      "user_id": "string",
      "email": "string",
      "role": "string",
      "status": "string",
      "created_at": 0
    }
  ],
  "invites": [
    {
      "email": "string",
      "role": "string",
      "expires_at": 0,
      "created_at": 0
    }
  ]
}
POST

Invite a teammate

https://gateway.aardvarkdocs.com/v1/team/invite

Owner/admin only. Emails a magic invite link (valid ~7 days). Owners may invite admins; admins may invite members only. Invites never grant owner. Returns 409 without sending when the plan's editor seats are already in use; acceptance rechecks the snapshotted allowance atomically. Otherwise the response is a neutral 200 regardless of delivery.

Responses

Body

okbooleannoAlways true; the neutral success acknowledgment (returned regardless of email delivery).
emailstringnoNormalized email address the invite link was sent to.
rolestringnoRole the invitee will hold on accepting; member or admin (never owner).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/team/invite' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "teammate@example.com",
  "role": "member"
}'

Response examples

{
  "ok": true,
  "email": "string",
  "role": "string"
}
POST

Cancel an invite

https://gateway.aardvarkdocs.com/v1/team/invite/revoke

Owner/admin only. Cancels an unconsumed invite for an email. Idempotent (revoked: 0 when none pending).

Responses

Body

okbooleannoAlways true once the request validates; the cancel ran (even if nothing matched).
emailstringnoNormalized invitee email whose pending invite was targeted, echoed back.
revokednumbernoCount of pending (unconsumed) invite tokens deleted; 0 when none were pending.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/team/invite/revoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "teammate@example.com"
}'

Response examples

{
  "ok": true,
  "email": "string",
  "revoked": 0
}
POST

Remove a member

https://gateway.aardvarkdocs.com/v1/team/remove

Owner/admin only, with a last-owner guard. Admins may remove non-owners. Removal revokes the member's keys and deletes their invites first.

Responses

Body

okbooleannotrue once the member is removed and their keys/invites revoked.
user_idstringnoEchoes back the removed member's user id.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/team/remove' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "u_abc123"
}'

Response examples

{
  "ok": true,
  "user_id": "string"
}
POST

Change member role

https://gateway.aardvarkdocs.com/v1/team/role

Owner/admin only, with a last-owner guard. Non-owners cannot grant or alter owner/admin. Demotions revoke the member's keys before the change.

Responses

Body

okbooleannoAlways true when the role change was applied successfully.
user_idstringnoIdentifier of the member whose role was changed.
rolestringnoThe member’s new role: owner, admin, or member.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/team/role' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "u_abc123",
  "role": "admin"
}'

Response examples

{
  "ok": true,
  "user_id": "string",
  "role": "string"
}

Card & top-ups.

GET

Plan catalog + live subscription and grant meter

https://gateway.aardvarkdocs.com/v1/billing

The subscription-plan catalog (Free/Pro/Business/Enterprise — operator-editable data), the account's live subscription with its included-AI grant meter (dollars used, the account's own trailing burn rate, an estimated depletion date), the anomaly-breaker state, and recent subscription events. Owner/admin only, like the other billing surfaces.

Responses

Body

plansarray<object>noThe plan catalog, cheapest first.
plans[].idstringnoStable plan slug: free, pro, business, enterprise (operator may add more).
plans[].namestringnoDisplay name.
plans[].price_usdnumbernoMonthly platform price in USD (0 for Free and custom-only plans).
plans[].price_annual_usdnumbernoAnnual price for 12 months in USD (20% off the platform fee, with the grant funded monthly at par — an effective ~12% off the yearly total, up to ~13% on plans whose bundled allowance is a smaller share of the fee), or null when annual isn't offered.
plans[].monthly_grant_usdnumbernoIncluded AI per month, in dollars of BILLED usage (the same units the ledger bills — never opaque credits).
plans[].markup_x100integernoThe plan's published member markup over OpenRouter list cost, ×100 (150 = ×1.50 Free baseline, 140 = ×1.40 Pro, 130 = ×1.30 Business, 120 = ×1.20 Enterprise).
plans[].seats_includedintegernoEditor seats included with the plan.
plans[].seat_price_usdnumbernoPer-seat monthly price of an add-on editor seat on this plan, in USD (0 = the plan sells no add-on seats). Annual subscriptions bill seats at this rate ×12 at par. Exposed so a plan-change confirmation can disclose the seat-charge delta a switch imposes on an account already holding add-on seats.
plans[].activebooleannoWhether the plan is open in the catalog (a retired plan keeps existing subscribers but takes no new ones).
plans[].self_servebooleannoWhether the plan can be subscribed to directly (the Free/PAYG row is the 'no subscription' state and is never self-serve).
subscriptionobjectnoThe live subscription + grant meter: plan/status/interval (+ cancel_at when a cancellation is scheduled), grant (monthly/remaining/rollover/available USD + period bounds), overflow (mode/cap/used + the 2× acknowledgment), seats (add-on editor seats: included/addon/used/limit counts + seat_price_usd per-seat monthly price), burn (last-30-days USD, per-day rate, estimated depletion date), and max_bill_usd — the single worst-case-bill number. Null on the free pay-as-you-go plan.
anomaly_pausedbooleannoWhether the spend-velocity circuit breaker has paused paid AI (free models keep serving).
eventsarray<object>noUp to 20 most recent subscription lifecycle events, newest first.
events[].eventstringnoEvent kind: subscribed, plan_changed, canceled, cancel_unscheduled, grant_reset, overflow_changed, payment_failed, payment_recovered, downgraded, paused, resumed, seats_changed.
events[].actorstringnoWho performed it: owner, admin (a team admin acting for the account), operator, or system.
events[].detailstringnoEvent-specific JSON detail, or null.
events[].tsintegernoEpoch-ms time of the event.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/billing' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "plans": [
    {
      "id": "string",
      "name": "string",
      "price_usd": 0,
      "price_annual_usd": 0,
      "monthly_grant_usd": 0,
      "markup_x100": 0,
      "seats_included": 0,
      "seat_price_usd": 0,
      "active": true,
      "self_serve": true
    }
  ],
  "subscription": {},
  "anomaly_paused": true,
  "events": [
    {
      "event": "string",
      "actor": "string",
      "detail": "string",
      "ts": 0
    }
  ]
}
POST

Cancel the subscription (or undo a scheduled cancellation)

https://gateway.aardvarkdocs.com/v1/billing/cancel

A Stripe-billed subscription cancels at PERIOD END (the customer keeps what they paid for; the webhook performs the downgrade at the boundary) — the scheduled end date is surfaced as the subscription’s cancel_at until then. Pass resume: true to UNDO a scheduled cancellation (409 no_pending_cancel when none is scheduled). An operator-granted subscription downgrades immediately. The prepaid balance is never touched by a lapse.

Responses

Body

resumedbooleannotrue when a scheduled cancellation was undone (resume: true).
subscriptionobjectnoThe refreshed subscription payload (carries the updated cancel_at).
canceledbooleannotrue when a cancellation was scheduled (or performed immediately).
at_period_endbooleannotrue when the plan stays active until the paid period ends; false when the downgrade was immediate (operator-granted).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "resumed": true,
  "subscription": {},
  "canceled": true,
  "at_period_end": true
}
POST

Switch the live subscription to another plan (upgrades apply immediately; downgrades at the next boundary)

https://gateway.aardvarkdocs.com/v1/billing/change-plan

Switches the live subscription to another plan. An UPGRADE (a higher-priced plan) applies IMMEDIATELY — the Stripe price is swapped with the difference prorated onto the next invoice, and the grant/markup/seats re-snapshot now. A DOWNGRADE (a lower-priced plan) is SCHEDULED for the next billing boundary with NO current-period proration: the current plan’s entitlement and billing continue unchanged until then, and the switch applies at that period’s invoice.paid (the response reports the scheduled plan via pending_plan, and switching back before the boundary unschedules it). At most ONE off-cycle re-grant applies per grant period regardless of how many times plans are swapped (swap-proof grant minting). Operator-managed (non-Stripe) subscriptions are refused — the operator re-plans via the admin surface.

Responses

Body

changedbooleannoAlways true on success.
effectivestringno
subscriptionobjectnoThe updated subscription + grant meter (same shape as GET /v1/billing’s subscription).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/change-plan' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "changed": true,
  "effective": "string",
  "subscription": {}
}
POST

Set the included-AI overflow policy

https://gateway.aardvarkdocs.com/v1/billing/overflow

What happens when the monthly included AI runs out: cap_hold (default — paid AI pauses; the plan price is the worst-case bill), payg_fallback (overflow draws the prepaid balance at the plan’s member markup, up to the cap), or shutoff. Raising the cap past 2× the monthly grant requires the explicit acknowledgment.

Responses

Body

okbooleannoAlways true on success.
modestringnoThe saved overflow mode.
cap_usdnumbernoThe saved overflow cap in USD.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/overflow' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "ok": true,
  "mode": "string",
  "cap_usd": 0
}
POST

Resume paid AI after an anomaly pause

https://gateway.aardvarkdocs.com/v1/billing/resume-ai

Lifts the spend-velocity circuit breaker's pause and prevents the same tripped UTC-day spend bucket from immediately re-triggering it; spend attributed to any other UTC day is evaluated normally. Works on every plan including Free — the breaker guards the pay-as-you-go tier too.

Responses

Body

resumedbooleannoAlways true.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/resume-ai' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "resumed": true
}
POST

Set the total add-on editor seat count (block + buy)

https://gateway.aardvarkdocs.com/v1/billing/seats

Sets the ABSOLUTE number of purchased add-on editor seats on a Stripe-billed subscription (migration 0045). The plan’s seats_included are free; each add-on seat bills at the plan’s per-seat monthly rate. Seats are block-and-buy — invites are refused with 403 seat_limit at the limit until more are bought here, so the bill never grows without this call. A REDUCTION can’t drop below the seats already occupied (members + pending invites). Operator-managed (non-Stripe) subscriptions are refused. A positive purchase on a plan that sells no add-on seats is refused with 400 seats_not_available, but a REMOVAL (seats: 0) is NOT blocked by that guard even after a plan’s per-seat price has been zeroed — so a customer holding a still-billing seat item can shed it rather than be trapped. (A removal is still subject to the same 400 seats_in_use floor as any reduction — it can’t drop the limit below the seats already occupied by members + pending invites — and to the suspended/closed-account guards.)

Responses

Body

seats_includedintegernoThe plan's included seats (free).
seats_addonintegernoThe purchased add-on seat count now in effect.
seat_price_usdnumbernoThe current per-add-on-seat monthly price.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/seats' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "seats_included": 0,
  "seats_addon": 0,
  "seat_price_usd": 0
}
POST

Subscribe to a plan (charges the saved card now)

https://gateway.aardvarkdocs.com/v1/billing/subscribe

Creates the Stripe subscription for a self-serve plan and grants the first month’s included AI immediately. Requires a card on file (see POST /v1/payment/checkout). Overflow defaults to cap-and-hold at 1× the grant, so the plan price is also the worst-case bill until the customer opts into fallback.

Responses

Body

subscribedbooleannoAlways true on success.
subscriptionobjectnoThe new subscription + grant meter (same shape as GET /v1/billing’s subscription).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/billing/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "subscribed": true,
  "subscription": {}
}
POST

Auto top-up settings

https://gateway.aardvarkdocs.com/v1/payment/autotopup

Sets the auto-top-up on/off state, charge amount, and low-balance trigger. At least one field is required; the trigger must be below the charge amount. Enabling requires a saved card and an amount. Owner/admin only.

Responses

Body

auto_topup_enabledbooleannoPost-write on/off state of auto top-up after this update.
auto_topup_amount_usdnumbernoAmount charged per auto top-up, in USD; null when none is stored.
low_balance_usdnumbernoLow-balance trigger threshold in USD that arms an auto top-up.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/payment/autotopup' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "amount_usd": 50,
  "low_balance_usd": 20
}'

Response examples

{
  "auto_topup_enabled": true,
  "auto_topup_amount_usd": 0,
  "low_balance_usd": 0
}
POST

Start card setup

https://gateway.aardvarkdocs.com/v1/payment/checkout

Creates (if needed) a Stripe customer and a hosted SetupIntent Checkout Session, returning the redirect URL. No body required. Owner/admin only.

Responses

Body

urlstringnoRedirect URL of the hosted Stripe SetupIntent Checkout Session for card entry.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/payment/checkout' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "url": "string"
}
POST

Finalize saved card

https://gateway.aardvarkdocs.com/v1/payment/method

Server-side re-reads the completed Checkout Session, verifies it belongs to this account, and stores the card on file. Idempotent on a given session_id. Owner/admin only.

Responses

Body

cardobjectnoNon-sensitive details of the card now saved on file, for display.
card.brandstringnoCard network brand (e.g. visa, mastercard); null if Stripe omitted it.
card.last4stringnoLast four digits of the saved card; null if unavailable.
card.exp_monthintegernoCard expiry month, 1–12; null if unavailable.
card.exp_yearintegernoCard expiry year, four-digit; null if unavailable.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/payment/method' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "session_id": "cs_test_abc123"
}'

Response examples

{
  "card": {
    "brand": "string",
    "last4": "string",
    "exp_month": 0,
    "exp_year": 0
  }
}
DELETE

Remove saved card

https://gateway.aardvarkdocs.com/v1/payment/method

Clears the card on file (also disabling auto-top-up) and best-effort detaches it at Stripe. Idempotent; allowed even when card payments are disabled. Owner/admin only.

Responses

Body

removedbooleannoAlways true; confirms the card on file was cleared and auto-top-up disabled.

Request samples

curl -X DELETE 'https://gateway.aardvarkdocs.com/v1/payment/method' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "removed": true
}
POST

Charge saved card

https://gateway.aardvarkdocs.com/v1/payment/topup-now

Immediately charges the saved card for amount_usd and credits the balance. Use a client idempotency_key to make retries safe. A pending charge returns { pending: true } and is credited by the webhook. Set reactivate: true to lift a self-serviceable (cost-unavailable) suspension before charging, so one call reactivates and tops up. Owner/admin only.

Responses

Body

pendingbooleannoPresent when the charge is still settling.
balance_usdnumbernoNew balance after the credit (on a synchronous charge).

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/payment/topup-now' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_usd": 50,
  "idempotency_key": "topup-2026-06-25-1"
}'

Response examples

{
  "pending": true,
  "balance_usd": 0
}

Magic-link sign-in.

POST

Destroy the session

https://gateway.aardvarkdocs.com/auth/logout

Deletes the session row and clears the cookie. Requires the session cookie and the X-Aardvark-Dashboard CSRF header. Idempotent.

Try it now unavailable

This auth endpoint is same-origin to the gateway dashboard, so browser calls from this docs page are blocked by CORS. Use a generated request sample or the dashboard instead.

Responses

Body

okbooleannoAlways true; the session row was deleted and the __Host-av_session cookie cleared.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/auth/logout' \
  -H 'Cookie: __Host-av_session=YOUR_API_KEY'

Response examples

{
  "ok": true
}
GET

Current user & teams

https://gateway.aardvarkdocs.com/auth/me

Returns the authenticated user, the active account, the role there, and all memberships. Returns 401 { authenticated: false } when there is no valid session.

Try it now unavailable

This auth endpoint is same-origin to the gateway dashboard, so browser calls from this docs page are blocked by CORS. Use a generated request sample or the dashboard instead.

Responses

Body

authenticatedbooleannotrue for a valid session; the 401 body instead carries false.
userobjectnoThe signed-in user identity (id and login email).
user.idstringnoStable user id of the signed-in account holder.
user.emailstringnoLogin email of the signed-in user.
active_accountstringnoAccount id the session is currently scoped to for billing and /v1/* access.
rolestringnoCaller’s role in active_account: one of owner, admin, or member.
membershipsarray<object>noAll accounts the user is an active member of, for the account switcher.
memberships[].account_idstringnoAccount id of this membership.
memberships[].rolestringnoUser’s role on that account: owner, admin, or member.
memberships[].owner_emailstringnoOwner email of that account, shown to identify it in the switcher.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/auth/me' \
  -H 'Cookie: __Host-av_session=YOUR_API_KEY'

Response examples

{
  "authenticated": true,
  "user": {
    "id": "string",
    "email": "string"
  },
  "active_account": "string",
  "role": "string",
  "memberships": [
    {
      "account_id": "string",
      "role": "string",
      "owner_email": "string"
    }
  ]
}
POST

Send a sign-in link

https://gateway.aardvarkdocs.com/auth/request-link

Emails a single-use magic link to the address. Neutral 200 regardless of whether the email exists (no account enumeration). Rate limited per IP and per email.

Try it now unavailable

This auth endpoint is same-origin to the gateway dashboard, so browser calls from this docs page are blocked by CORS. Use a generated request sample or the dashboard instead.

Responses

Body

okbooleannoAlways true; the response is neutral and never signals whether the email exists.
messagestringnoNeutral confirmation prose shown regardless of outcome, avoiding account enumeration.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/auth/request-link' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com"
}'

Response examples

{
  "ok": true,
  "message": "string"
}
POST

Switch active account

https://gateway.aardvarkdocs.com/auth/switch

Rotates the session to a different account the user belongs to. Requires the session cookie and the X-Aardvark-Dashboard CSRF header. Rate limited per user.

Try it now unavailable

This auth endpoint is same-origin to the gateway dashboard, so browser calls from this docs page are blocked by CORS. Use a generated request sample or the dashboard instead.

Responses

Body

okbooleannoAlways true once the session is rotated to the target account.
active_accountstringnoAccount id the session is now active on, matching the requested account_id.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/auth/switch' \
  -H 'Cookie: __Host-av_session=YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "account_id": "a_abc123"
}'

Response examples

{
  "ok": true,
  "active_account": "string"
}
GET

Magic-link landing

https://gateway.aardvarkdocs.com/auth/verify

Serves a tiny nonce-CSP HTML page that reads the token from the URL fragment and POSTs it to /auth/verify. The token never reaches the server as a query string.

Try it now unavailable

This endpoint serves the magic-link verification HTML page, not a cross-origin JSON API request. Open the magic link in your browser or start the flow from the dashboard instead.

Responses

Body

A single string value.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/auth/verify'

Response examples

"string"
POST

Redeem a magic link

https://gateway.aardvarkdocs.com/auth/verify

The token in the body is the credential. On success sets the __Host-av_session cookie. NOTE: this endpoint’s responses use the non-standard shape { ok, error } (read by the landing page’s script), not the usual error envelope.

Try it now unavailable

This auth endpoint is same-origin to the gateway dashboard, so browser calls from this docs page are blocked by CORS. Use a generated request sample or the dashboard instead.

Responses

Body

okbooleannotrue when the token was consumed and the __Host-av_session cookie was minted; false carries an error code.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/auth/verify' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "<base64url-token>"
}'

Response examples

{
  "ok": true
}

Stripe webhooks.

POST

Stripe webhook

https://gateway.aardvarkdocs.com/v1/stripe/webhook

Stripe-to-server webhook authenticated by the Stripe-Signature header (HMAC over the raw body). Handles payment_intent.succeeded (durable credit) and payment_intent.payment_failed (audit + auto-top-up streak), plus the subscription lifecycle (migration 0044): customer.subscription.created/customer.subscription.updated (snapshot sync, plan reconcile, lost-insert heal), customer.subscription.deleted (downgrade to Free), invoice.paid (billing history, past-due recovery, scheduled-downgrade apply at the boundary), and invoice.payment_failed (dunning + past_due grace clock). Acks 200 once a delivery is handled or irrelevant; deliberately returns 500 on transient read/write failures so Stripe redelivers instead of losing a money event.

Try it now unavailable

This endpoint is server-to-server only, so browser calls from this docs page are blocked by CORS. Use a generated request sample from your backend instead.

Responses

Body

receivedbooleannoAlways true; acks the verified delivery so Stripe stops its retry storm.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/stripe/webhook' \
  -H 'Stripe-Signature: YOUR_API_KEY'

Response examples

{
  "received": true
}

Docs quality checks.

GET

List capabilities

https://gateway.aardvarkdocs.com/v1/github/capabilities

The static catalog of AI authoring capabilities (e.g. keyword and description generation, the style-guide pass) that can be enabled to run on a connected repo. Readable by any authenticated dashboard user.

Responses

Body

capabilitiesstringnoThe catalog of available authoring capabilities, each with its id, label, and runner command.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/github/capabilities' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "capabilities": "string"
}
POST

Configure repo

https://gateway.aardvarkdocs.com/v1/github/configure

Declarative per-repo automation config: for each capability set whether it’s enabled, its schedule (cron, floored to at most once per hour), run-on-push, base branch, and project dir. A pure DB apply — no GitHub writes. Owner only. Owner only.

Responses

Body

repostringnoEchoes the configured repo owner/name.
automationsarray<object>noThe repo's automation rows after the apply.
automations[].capabilitystringnoCapability id this automation runs.
automations[].enabledstringnoWhether the automation is active after the apply.
automations[].run_on_pushstringnoWhether a matching push fires the automation.
automations[].cronstringnoResolved 5-field cron schedule, or null when unscheduled.
automations[].base_branchstringnoBranch the automation runs against, or null for the repo default.
automations[].project_dirstringnoSubdirectory the vark project lives in, or null for the repo root.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/configure' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "repo": "acme/docs",
  "automations": [
    {
      "capability": "keywords",
      "enabled": true,
      "run_on_push": true,
      "cron": "0 9 * * 1",
      "base_branch": "main"
    }
  ]
}'

Response examples

{
  "repo": "string",
  "automations": [
    {
      "capability": "string",
      "enabled": "string",
      "run_on_push": "string",
      "cron": "string",
      "base_branch": "string",
      "project_dir": "string"
    }
  ]
}
POST

Connect a repo

https://gateway.aardvarkdocs.com/v1/github/connect

Mints a single-use install state and returns the GitHub App install URL carrying it. The browser follows that URL; GitHub echoes state back to the setup callback, which binds the installation to this account. Owner only. Owner only.

Responses

Body

install_urlstringnoGitHub App install URL with the single-use state embedded; redirect the browser here to start the install.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/connect' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "install_url": "string"
}
GET

Connection status

https://gateway.aardvarkdocs.com/v1/github/connection

Everything the dashboard's Docs Quality Checks page needs: whether the integration is configured, the install-URL slug, the account's installations, and each connected repo with its per-capability automation config.

Responses

Body

configuredbooleannoWhether the gateway is fully configured for the integration (app creds, slug, webhook secret, OAuth creds).
app_slugstringnoThe GitHub App's URL slug used to build the install URL, or null when unset.
capabilitiesstringnoThe static catalog of AI authoring capabilities that can be enabled per repo.
installationsarray<object>noGitHub App installations bound to this account.
installations[].installation_idstringnoGitHub's numeric installation id.
installations[].github_loginstringnoThe org/user login the app is installed on.
installations[].account_typestringnoInstallation account type, e.g. Organization or User.
installations[].suspendedbooleannotrue when GitHub has suspended the installation.
installations[].stalebooleannotrue when GitHub no longer recognizes this installation id (the app was reinstalled) — reconnect to fix.
reposarray<object>noRepos reachable through the installations, each with its automation config.
repos[].full_namestringnoRepo owner/name.
repos[].default_branchstringnoRepo default branch (the automation base when none is set).
repos[].privatestringnoWhether the repo is private.
repos[].installation_idstringnoInstallation that grants access to this repo.
repos[].configuredintegernotrue when the repo has at least one automation set up.
repos[].automationsarray<object>noPer-capability automation rows configured on the repo.
repos[].automations[].capabilitystringnoCapability id this automation runs.
repos[].automations[].enabledstringnoWhether the automation is active.
repos[].automations[].run_on_pushstringnoWhether a matching push fires the automation.
repos[].automations[].cronstringnoSchedule (5-field cron, at most hourly), or null.
repos[].automations[].base_branchstringnoBranch the automation runs against, or null for the repo default.
repos[].automations[].project_dirstringnoSubdirectory the vark project lives in, or null for the repo root.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/github/connection' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "configured": true,
  "app_slug": "string",
  "capabilities": "string",
  "installations": [
    {
      "installation_id": "string",
      "github_login": "string",
      "account_type": "string",
      "suspended": true,
      "stale": true
    }
  ],
  "repos": [
    {
      "full_name": "string",
      "default_branch": "string",
      "private": "string",
      "installation_id": "string",
      "configured": 0,
      "automations": [
        {
          "capability": "string",
          "enabled": "string",
          "run_on_push": "string",
          "cron": "string",
          "base_branch": "string",
          "project_dir": "string"
        }
      ]
    }
  ]
}
POST

Disconnect a repo

https://gateway.aardvarkdocs.com/v1/github/disconnect

Stops all automations for a repo by dropping their config rows in one atomic delete. Leaves the app installed (uninstall happens in GitHub) and the repo listed so it can be reconfigured. Owner only. Owner only.

Responses

Body

disconnectedbooleannoAlways true once the repo’s automations are removed.
repostringnoEchoes the repo that was disconnected.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/disconnect' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "repo": "acme/docs"
}'

Response examples

{
  "disconnected": true,
  "repo": "string"
}
POST

Run now

https://gateway.aardvarkdocs.com/v1/github/run

Dispatches a configured capability immediately on the central runner. The run is recorded as queued and advanced by the runner’s claim/complete callbacks. A balance or runner-config problem returns 402/503; an already-running capability returns 409. Owner only. Owner only.

Responses

Body

dispatchedbooleannoAlways true when the run was queued on the central runner.
run_idstringnoServer-minted UUID of the queued run, for correlating later run-history rows.
repostringnoEchoes the repo the run was dispatched for.
capabilitystringnoEchoes the capability the run executes.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "repo": "acme/docs",
  "capability": "keywords"
}'

Response examples

{
  "dispatched": true,
  "run_id": "string",
  "repo": "string",
  "capability": "string"
}
POST

Cancel run

https://gateway.aardvarkdocs.com/v1/github/run/cancel

Cancels the active queued or in-progress run for a repo/capability pair, revokes any already-minted ephemeral inference key, and best-effort cancels the backing GitHub Actions run. Idempotent: idle pairs return cancelled: false. Owner only.

Responses

Body

cancelledbooleanyestrue when an active run was sealed as cancelled; false when no matching run was active.
run_idstringnoServer-minted UUID of the cancelled run. Present only when cancelled is true.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/run/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "repo": "acme/docs",
  "capability": "keywords"
}'

Response examples

{
  "cancelled": true,
  "run_id": "string"
}
POST

Claim a run

https://gateway.aardvarkdocs.com/v1/github/runner/claim

Central-runner callback: the runner claims a queued run and receives an ephemeral inference key plus a repo-scoped GitHub token (minted only once the claim CAS wins). Authed by the runner credential (RUNNER_CALLBACK_TOKEN and/or a GitHub Actions OIDC JWT), never a dashboard session.

Try it now unavailable

This endpoint is server-to-server only, so browser calls from this docs page are blocked by CORS. Use a generated request sample from your backend instead.

Responses

Body

inference_keystringnoEphemeral, per-run secret inference key — returned ONCE, after the claim CAS wins.
repo_tokenstringnoShort-lived GitHub token scoped to the customer repo (contents + pull-requests write).
commandstringnoThe vark runner command to execute for this capability.
full_namestringnoCustomer repo owner/name the run targets.
installation_idstringnoInstallation id whose token grants access to the customer repo.
base_branchstringnoBranch to run against, or null for the repo default.
project_dirstringnoSubdirectory the vark project lives in, or null for the repo root.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/runner/claim' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "run_id": "1f0c…",
  "github_run_id": 1234567890
}'

Response examples

{
  "inference_key": "string",
  "repo_token": "string",
  "command": "string",
  "full_name": "string",
  "installation_id": "string",
  "base_branch": "string",
  "project_dir": "string"
}
POST

Complete a run

https://gateway.aardvarkdocs.com/v1/github/runner/complete

Central-runner callback: reports a finished run. Revokes the run's ephemeral key (stops spend), meters the compute, and records the conclusion plus the PR it opened. Idempotent; a late callback can top up a $0-sealed run. Authed by the runner credential.

Try it now unavailable

This endpoint is server-to-server only, so browser calls from this docs page are blocked by CORS. Use a generated request sample from your backend instead.

Responses

Body

okbooleannoAlways true once the run is finalized (or already was).
already_finalizedbooleannoPresent and true when the run was already billed — an idempotent no-op.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/runner/complete' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "run_id": "1f0c…",
  "billable_ms": 42000,
  "conclusion": "success",
  "pr_url": "https://github.com/acme/docs/pull/7",
  "github_run_id": 1234567890
}'

Response examples

{
  "ok": true,
  "already_finalized": true
}
GET

List runs

https://gateway.aardvarkdocs.com/v1/github/runs

Run history for a connected repo, newest first, optionally filtered by capability. Each row carries status, conclusion, the PR the run opened, and the metered compute cost.

repoquerystringyesRepo owner/name to list runs for (required).
capabilityquerystringnoRestrict to one capability's runs.
limitqueryintegernoMax rows to return (default 50, capped at 200).

Responses

Body

repostringnoEchoes the queried repo owner/name.
runsarray<object>noRun-history rows, newest first.
runs[].idstringnoStable run UUID (the React table key; run_number is null until the run starts).
runs[].capabilitystringnoCapability the run executed.
runs[].triggerstringnoWhat started the run: manual, push, or schedule.
runs[].statusstringnoLifecycle state: queued, in_progress, completed, or skipped.
runs[].conclusionstringnoGitHub Actions conclusion (e.g. success, failure), or null until finished.
runs[].skip_reasonstringnoWhy a skipped run never started (e.g. insufficient_balance), or null.
runs[].run_numberstringnoGitHub Actions run number on our runner repo, or null until claimed.
runs[].pr_urlstringnoURL of the PR the run opened in the customer repo, or null.
runs[].compute_billed_microintegernoMetered compute cost in micro-USD, or null until finalized.
runs[].created_atstringnoEpoch-ms time the run was created.
runs[].updated_atstringnoEpoch-ms time the run row was last updated.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/github/runs?repo={repo}&capability={capability}&limit={limit}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "repo": "string",
  "runs": [
    {
      "id": "string",
      "capability": "string",
      "trigger": "string",
      "status": "string",
      "conclusion": "string",
      "skip_reason": "string",
      "run_number": "string",
      "pr_url": "string",
      "compute_billed_micro": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}
DELETE

Clear a run history entry

https://gateway.aardvarkdocs.com/v1/github/runs/{run_id}

Deletes one terminal GitHub automation run from the account’s dashboard history. Queued and in-progress runs must be cancelled first because they still gate dispatch and key cleanup. Owner only.

run_idpathstringyesStable run UUID from GET /v1/github/runs.

Responses

Body

deletedbooleanyesAlways true once the history entry is removed.
run_idstringyesEchoes the cleared run UUID.

Request samples

curl -X DELETE 'https://gateway.aardvarkdocs.com/v1/github/runs/{run_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "deleted": true,
  "run_id": "string"
}
GET

Read run logs

https://gateway.aardvarkdocs.com/v1/github/runs/{run_id}/logs

Returns the latest GitHub Actions job log text for one Docs Quality Check run. The dashboard polls this endpoint while a row is expanded so queued and in-progress runs can surface logs as soon as GitHub publishes them.

run_idpathstringyesStable run UUID from GET /v1/github/runs.

Responses

Body

run_idstringyesEchoes the requested run UUID.
statusstringyesCurrent dashboard run status.
availablebooleanyesfalse until the runner has claimed the run and GitHub has a job log to download.
logsstringyesNormalized text log payload, or an empty string while unavailable.
truncatedbooleanyestrue when only the tail of an oversized log is returned.
jobobjectnoGitHub Actions job metadata for the selected runner job, or null while unavailable.
job.idnumberno
job.namestringno
job.statusstringno
job.conclusionstringno
updated_atintegeryesEpoch-ms time this log response was generated (refreshed on every request), not a run-row change stamp.
messagestringnoHuman-readable unavailable-state message.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/github/runs/{run_id}/logs' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response examples

{
  "run_id": "string",
  "status": "string",
  "available": true,
  "logs": "string",
  "truncated": true,
  "job": {
    "id": 0,
    "name": "string",
    "status": "string",
    "conclusion": "string"
  },
  "updated_at": 0,
  "message": "string"
}
GET

Install callback

https://gateway.aardvarkdocs.com/v1/github/setup

GitHub redirects the browser here after the app is installed or updated. The single-use state (minted at connect) recovers which account initiated, an identity check proves the user administers the installation, then it binds the install, syncs repos, and 302-redirects back to the dashboard. Authed by state, not a session.

statequerystringnoSingle-use install state minted at connect; the credential that recovers and binds the initiating account.
installation_idqueryintegernoGitHub's numeric id for the new/updated installation.
codequerystringnoOAuth code GitHub appends so the gateway can prove the user administers this installation.

Try it now unavailable

This endpoint is a browser redirect callback, not a cross-origin API call. Start the GitHub connection flow from the dashboard instead.

Responses

Headers

LocationstringDashboard URL to follow, carrying ?connected=1 on success or ?error=<code> otherwise.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/v1/github/setup?state={state}&installation_id={installation_id}&code={code}&state=YOUR_API_KEY'

Response examples

{
  "error": {
    "code": "github_misconfigured",
    "message": "The gateway origin is misconfigured; contact the operator."
  }
}
POST

GitHub webhook

https://gateway.aardvarkdocs.com/v1/github/webhook

GitHub-to-server webhook authenticated by the X-Hub-Signature-256 HMAC over the raw body. Handles installation lifecycle, repo-selection changes, pushes (run-on-push automations), workflow runs (a backstop for the runner’s complete callback), and PRs (PR-url capture). Acks 200 once verified; unrecognized event types are acked and ignored.

Try it now unavailable

This endpoint is server-to-server only, so browser calls from this docs page are blocked by CORS. Use a generated request sample from your backend instead.

Responses

Body

receivedbooleannoAlways true; acks the verified delivery so GitHub stops retrying.

Request samples

curl -X POST 'https://gateway.aardvarkdocs.com/v1/github/webhook' \
  -H 'X-Hub-Signature-256: YOUR_API_KEY'

Response examples

{
  "received": true
}

Health check.

GET

Health check

https://gateway.aardvarkdocs.com/

Unauthenticated root health check; returns a fixed text/plain body.

Responses

Body

A single string value.

Request samples

curl -X GET 'https://gateway.aardvarkdocs.com/'

Response examples

"string"

Was this page helpful?

Edit this pageReport an issueAsk a question