API reference
Control plane REST + OTLP ingest.
The control plane is OpenAPI 3.1: agenko/spec/openapi/control-plane.yaml. SDKs are generated-from-that-shape in spirit (hand-written today, same resource names).
Ingest
| Method | Path | Body |
|---|---|---|
| POST | /api/public/otel/v1/traces | OTLP/HTTP protobuf traces |
Header: X-API-Key: $AGENKO_API_KEY when REQUIRE_API_KEY is on.
Agent connect
| Method | Path | When |
|---|---|---|
| POST | /api/v1/agents/connect | init() with an API key |
JSON: service_name, environment, frameworks[]. Fire-and-forget from the SDK.
Receipts & approvals
Receipts
| Method | Path | When |
|---|---|---|
| POST | /api/v1/receipts/ | @check persists a receipt |
| GET | /api/v1/receipts | List (query verdict, page, page_size) |
Approvals
| Method | Path | When |
|---|---|---|
| POST | /api/v1/approvals/ | @approve creates a pending approval |
| GET | /api/v1/approvals/ | List (query status, page, page_size) |
| GET | /api/v1/approvals/{id} | Poll one |
| POST | /api/v1/approvals/{id}/approve | Approve |
| POST | /api/v1/approvals/{id}/reject | Reject |
Scores
| Method | Path | When |
|---|---|---|
| POST | /api/v1/scores/ | agenko.score() records a Langfuse-shaped score on the active trace |
Prompts
| Method | Path | When |
|---|---|---|
| GET | /api/v1/prompts/by-slug/{project_id}/{slug} | get_prompt() fetches a versioned prompt by label or version |
The control plane is OpenAPI 3.1 at
agenko/spec/openapi/control-plane.yaml. Some SDK-driven endpoints above (POST/api/v1/receipts/, POST/api/v1/scores/, GET/api/v1/prompts/...) are not yet enumerated in that file. Prefer the OpenAPI file when it diverges; otherwise this page matches SDK behavior.
Events
spec/events/receipt-created.yamlspec/events/approval-requested.yaml
Semantic conventions
spec/telemetry/semantic-conventions.yaml — agenko.* plus OpenInference. Keep SDK emits in sync with that file.
SDK surface
Python: init, check, approve, get_client. TypeScript: the same plus shutdown, isInitialized. Details on the Python and TypeScript pages.
Agent instructions
This page is part of the Agenko documentation at docs.agenko.app. Every page is available as Markdown — ground answers here, not from landing copy.
Querying these docs
- Full index: docs.agenko.app/llms.txt · sections: llms-docs.txt, llms-sdk.txt, llms-integrations.txt
- This page as markdown: docs.agenko.app/api-reference.md
- Search API:
curl -sG "https://docs.agenko.app/api/search-docs" --data-urlencode "query=…"
Before writing SDK code
- Install the agent skill or read Agent skill
- Read Best practices — what a good receipt looks like
- Trust boundary:
@checkafter,@approvebefore init()— zero required args, never throws- Mark
estimated: trueuntil a check is a hard fact - Shipped vs backlog: Introduction status table