Registry API reference

The registry API is part of the Agent Runtime. All requests need the headers described in Request basics, and the calling user needs the service operator role.

The complete, interactive API reference of the Agent Runtime is available at ${RUNTIME_BASE_URL}/docs.

Endpoints

Resource	Path	Operations
Components	/v1/components/{type}/{id}	POST /v1/components/{type}, GET (list or single), HEAD, PUT, DELETE
Environments	/v1/environments/{name}	POST /v1/environments, GET, HEAD, PUT, DELETE
Deployments	/v1/deployments/{id}	POST /v1/deployments, GET, HEAD, PUT, DELETE
Guardrails	/v1/guardrails/{id}	POST /v1/guardrails, GET, HEAD, PUT, DELETE
Secrets	/v1/secrets/{name}	POST /v1/secrets, GET, HEAD, DELETE
Policies	/v1/policy/{name}	POST /v1/policy, GET, HEAD, PUT, DELETE
Policy violations	/v1/violations	GET

Notes:

• PUT replaces the whole resource. Send all fields.
• HEAD returns 200 if the resource exists and 404 otherwise.
• GET /v1/components/{type}/{id}?expand=true returns the component with all references replaced by the referenced components.
• DELETE returns 204 on success.

Naming rules

What	Allowed characters	Example
Component, environment and deployment IDs	Lowercase letters, digits, dashes, underscores	support_bot_v2, gpt-model
Guardrail IDs	Letters, digits, dashes, underscores	shopfloor-safety
Environment variable keys	Uppercase letters, digits, underscores. Must start with an uppercase letter.	TICKET_API_URL
Secret names	Letters, digits, dashes. Up to 127 characters.	TICKET-API-KEY
Display names (name)	Any characters	Customer Support Agent

Use descriptive IDs such as customer-support-agent instead of agent1. If you version components, put the version in the ID, for example support-agent-v2.

Errors

Status	Meaning	What to do
400	Invalid data or reference	Check the reference format and naming rules
401	Not authenticated	Request a new token
403	Missing role or wrong tenant	Check that you have the service operator role and the right X-Tenant-ID
404	Not found	Check that the resource exists
409	Conflict	The resource already exists, or another resource still references it
422	Validation failed	Check required fields and types

The response body explains the cause:

{ "detail": "Missing component references needs to be created beforehand: tool/calculator" }

Typical causes:

• Missing reference: create the referenced components first.
• Still referenced: a component, environment or guardrail is still used elsewhere. Remove the reference first.
• Circular reference: a component refers back to itself through other components.