REST API reference¶

All endpoints take Authorization: Bearer <token> (a tenant API key, an OIDC token, or the bootstrap admin key plus X-Tenant-Id). The scope column is the permission the token needs; see Security. Interactive docs are served at /docs and the machine-readable spec at /openapi.json (download).

Operational endpoints without auth: GET /healthz, GET /readyz, GET /metrics. The MCP endpoint is /mcp (see MCP).

Learning loop¶

Method	Path	Scope	Description	Body	Response
`POST`	`/v1/recall`	`learn`	Retrieve learned skills, memories and the user's profile for a task, as ready-to-inject instructions.	`RecallRequest`	`RecallResponse`
`POST`	`/v1/episodes`	`learn`	Record a finished run (messages, tool calls, outcome, verification) so the agent can learn from it.	`EpisodeIn`	`EpisodeOut`
`POST`	`/v1/episodes:batch`	`learn`	Bulk import of historical runs (offline warm-up: ACE showed warm-starting lifts online learning).	`list[EpisodeIn]`	`dict`
`GET`	`/v1/episodes/latest`	`learn`	Most recent episode of a session, so stateless clients can attach feedback to 'the last turn'.		`dict`
`POST`	`/v1/feedback`	`learn`	Rate a recorded episode (0-1), optionally with a comment or the correct answer.	`FeedbackIn`
`POST`	`/v1/traces`	`learn`	Zero-code ingestion of OpenTelemetry GenAI / OpenInference traces.		`dict`
`POST`	`/v1/ask`	`learn`	Answer a question from learned evidence only (skills, memories, profile), with cited evidence ids.	`AskIn`	`AskOut`

Skills¶

Method	Path	Scope	Description	Body	Response
`GET`	`/v1/skills`	`learn`	List an agent's skills (plus tenant-shared ones) with their rules and success rates.		`list[Skill]`
`GET`	`/v1/skills/{ref}`	`learn`	Get one skill by id or name.		`Skill`
`GET`	`/v1/skills/{ref}/SKILL.md`	`learn`	Export a skill as an agentskills.io-compatible SKILL.md.		`str`
`GET`	`/v1/skills/{ref}/versions`	`learn`	List a skill's immutable version history.		`list[dict]`
`POST`	`/v1/skills`	`review`	Create or replace a skill by hand (applied through a governed changeset).	`SkillIn`	`dict`
`POST`	`/v1/skills/import`	`review`	Bring existing SKILL.md files (Anthropic / Hermes / agentskills.io) under learning and governance.	`SkillImport`	`dict`
`POST`	`/v1/skills/{skill_id}/rollback`	`review`	Restore a skill to an earlier version (recorded as a new version).	`RollbackIn`	`dict`
`POST`	`/v1/skills/{skill_id}/pin`	`review`	Pin or unpin a skill. Pinned skills are never archived by the lifecycle.	`PinIn`	`dict`
`POST`	`/v1/skills/{skill_id}/evolve`	`review`	Queue an evolution run for a skill.		`dict`

Memory & profiles¶

Method	Path	Scope	Description	Body	Response
`POST`	`/v1/memories`	`learn`	Add a memory. It is reconciled against existing memories (add, update, supersede or no-op).	`MemoryIn`	`dict`
`GET`	`/v1/memories`	`learn`	List memories, optionally for a user, at a point in time (`as_of`) or with superseded history.		`list[Memory]`
`POST`	`/v1/memories/{memory_id}/approve`	`review`	Approve a memory held for review (e.g. flagged by the safety scan).		`dict`
`DELETE`	`/v1/memories/{memory_id}`	`review`	Hard delete (e.g. data-subject request). Learning itself never hard-deletes; it supersedes.
`GET`	`/v1/profiles/{agent_id}/{user_id}`	`learn`	Get the profile card for a user of an agent.		`dict`

Governance & insights¶

Method	Path	Scope	Description	Body	Response
`GET`	`/v1/changesets`	`review`	List changesets (proposed skill changes), by default those pending review.		`list[Changeset]`
`POST`	`/v1/changesets/{cs_id}/review`	`review`	Approve or reject a pending changeset. Risky changes to proven skills start a canary unless skipped.	`ReviewIn`	`dict`
`POST`	`/v1/agents/{agent_id}/reflect`	`review`	Queue reflection over an agent's unreflected episodes now.		`dict`
`POST`	`/v1/agents/{agent_id}/curate`	`review`	Queue library upkeep for an agent now (dedup, lifecycle, nomination, profiles).		`dict`
`POST`	`/v1/agents/{agent_id}/replay`	`review`	Re-learn from stored episodes (another epoch), e.g. after importing history or changing the model.	`ReplayIn`	`dict`
`GET`	`/v1/agents/{agent_id}/insights`	`learn`	Learning lift vs the holdout group, per-skill success rates, canaries, problem rules and learning cost.		`dict`
`GET`	`/v1/agents/{agent_id}/export`	`review`	Export episodes with rewards as JSON Lines (for analytics, RL or fine-tuning).

Administration¶

Method	Path	Scope	Description	Body	Response
`POST`	`/v1/admin/api-keys`	`admin`	Create a tenant API key with the given scopes. The key is only shown once.	`KeyIn`	`dict`
`DELETE`	`/v1/admin/api-keys/{key_id}`	`admin`	Revoke a tenant API key.
`GET`	`/v1/admin/audit`	`admin`	List the tenant's audit log, newest first.		`list[dict]`
`GET`	`/v1/admin/usage`	`admin`	Learning-side LLM usage per day and purpose (for budgets and chargeback).		`list[dict]`
`DELETE`	`/v1/admin/users/{user_id}`	`admin`	Right to erasure: memories, profile and episodes of a user in this tenant.		`dict`

Schemas¶

Request and response models, from the OpenAPI spec.

`AskIn`¶

Field	Type	Required
`scope`	ref Scope
`question`	string	yes

`AskOut`¶

Field	Type	Required
`answer`	string	yes
`evidence`	array	yes

`Bullet`¶

Field	Type	Required
`id`	string	yes
`section`	string	yes
`content`	string	yes
`issue`	string	yes
`keywords`	array	yes
`helpful`	integer	yes
`harmful`	integer	yes
`neutral`	integer	yes
`used`	integer	yes
`status`	string	yes
`sources`	array	yes

`BulletIn`¶

Field	Type	Required
`section`	string
`content`	string	yes
`issue`	string
`keywords`	array

`BulletRef`¶

Field	Type	Required
`id`	string	yes
`section`	string	yes
`content`	string	yes

`Changeset`¶

Field	Type	Required
`id`	string	yes
`agent_id`	string	yes
`status`	string	yes
`ops`	array	yes
`rationale`	string	yes
`source`	string	yes
`risk`	string	yes
`eval_score`	number \| null	yes
`baseline_score`	number \| null	yes
`safety_findings`	array	yes
`episode_ids`	array	yes
`reviewer`	string \| null	yes
`review_comment`	string \| null	yes
`created_at`	string	yes

`EpisodeIn`¶

Field	Type	Required
`scope`	ref Scope
`idempotency_key`	string \| null
`session_id`	string \| null
`recall_id`	string \| null
`task`	string \| null
`messages`	array
`tool_calls`	array
`outcome`	ref Outcome
`verification`	Verification \| null
`error`	string \| null
`duration_ms`	integer \| null
`framework`	string \| null
`skills_loaded`	array
`metadata`	object

`EpisodeOut`¶

Field	Type	Required
`episode_id`	string	yes
`reflection_scheduled`	boolean	yes

`FeedbackIn`¶

Field	Type	Required
`episode_id`	string	yes
`score`	number	yes
`comment`	string \| null
`correction`	string \| null
`source`	string

`KeyIn`¶

Field	Type	Required
`name`	string	yes
`scopes`	array

`Memory`¶

Field	Type	Required
`id`	string	yes
`agent_id`	string	yes
`user_id`	string \| null	yes
`kind`	string	yes
`content`	string	yes
`confidence`	number	yes
`valid_from`	string	yes
`invalid_at`	string \| null	yes
`superseded_by`	string \| null	yes
`sources`	array	yes

`MemoryIn`¶

Field	Type	Required
`scope`	ref Scope
`kind`	ref MemoryKind
`content`	string	yes

`MemoryKind`¶

Field	Type	Required

`MemoryRef`¶

Field	Type	Required
`id`	string	yes
`kind`	string	yes
`content`	string	yes
`score`	number	yes
`valid_from`	string	yes

`Message`¶

Field	Type	Required
`role`	string	yes
`content`	string	yes

`Outcome`¶

Field	Type	Required

`PinIn`¶

Field	Type	Required
`pinned`	boolean

`RecallRequest`¶

Field	Type	Required
`scope`	ref Scope
`query`	string	yes
`session_id`	string \| null
`max_skills`	integer \| null
`max_memories`	integer \| null
`as_of`	string \| null
`include_profile`	boolean

`RecallResponse`¶

Field	Type	Required
`recall_id`	string	yes
`instructions`	string	yes
`skills`	array	yes
`skill_index`	array	yes
`memories`	array	yes
`profile`	string \| null
`holdout`	boolean

`ReplayIn`¶

Field	Type	Required
`limit`	integer

`ReviewIn`¶

Field	Type	Required
`approve`	boolean	yes
`comment`	string \| null
`skip_canary`	boolean

`RollbackIn`¶

Field	Type	Required
`version`	integer	yes

`Scope`¶

tenant_id always comes from the authenticated principal, never the body.

Field	Type	Required
`agent_id`	string
`user_id`	string \| null

`Skill`¶

Field	Type	Required
`id`	string	yes
`agent_id`	string	yes
`name`	string	yes
`description`	string	yes
`version`	integer	yes
`status`	string	yes
`pinned`	boolean
`tags`	array	yes
`uses`	integer	yes
`success_rate`	number \| null	yes
`bullets`	array	yes
`created_at`	string	yes
`updated_at`	string	yes

`SkillImport`¶

Import an existing SKILL.md (Anthropic / Hermes / agentskills.io format).

Field	Type	Required
`agent_id`	string
`markdown`	string	yes

`SkillIn`¶

Field	Type	Required
`agent_id`	string
`name`	string	yes
`description`	string	yes
`bullets`	array \| null
`body`	string \| null
`tags`	array

`SkillRef`¶

Field	Type	Required
`id`	string	yes
`name`	string	yes
`description`	string	yes
`version`	integer	yes
`score`	number	yes
`arm`	string \| null
`bullets`	array \| null

`ToolCall`¶

Field	Type	Required
`name`	string	yes
`arguments`	object \| string \| null
`result`	string \| null
`error`	string \| null

`Verification`¶

Ground-truth signal from tests, validators or business checks. The strongest learning signal there is.

Field	Type	Required
`passed`	boolean	yes
`details`	string \| null
`source`	string

REST API reference¶

Learning loop¶

Skills¶

Memory & profiles¶

Governance & insights¶

Administration¶

Schemas¶

AskIn¶

AskOut¶

Bullet¶

BulletIn¶

BulletRef¶

Changeset¶

EpisodeIn¶

EpisodeOut¶

FeedbackIn¶

KeyIn¶

Memory¶

MemoryIn¶

MemoryKind¶

MemoryRef¶

Message¶

Outcome¶

PinIn¶

RecallRequest¶

RecallResponse¶

ReplayIn¶

ReviewIn¶

RollbackIn¶

Scope¶

Skill¶

SkillImport¶

SkillIn¶

SkillRef¶

ToolCall¶

Verification¶