---
title: API reference
description: Control plane REST + OTLP ingest.
---

# API reference

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.yaml`
- `spec/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](/python) and [TypeScript](/typescript) pages.

## Agent instructions

This page: https://docs.agenko.app/api-reference.md

Fetch `/llms.txt` for the full index. Search: `GET /api/search-docs?query=...`
