Skip to content
Alquimia Alquimia Alquimia

Registry API

All registry endpoints are under the /registry prefix. Authentication is required on all endpoints.

An agentspace is a named container for agents, secrets, and parameters. It maps to a TinyDB-backed local store and can be published to an OCI registry as a versioned artifact.

Agentspace endpoints

Section titled “Agentspace endpoints”

GET /registry/

Section titled “GET /registry/”

Retrieve a single agentspace by ID.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Agentspace identifier |

Response — 200 OK

Section titled “Response — 200 OK”
{
  "agentspace_id": "default",
  "name": "my-agents",
  "namespace": "local",
  "tag": "latest",
  "visibility": "private",
  "status": "enabled",
  "description": null,
  "user_id": null,
  "source_repo_id": null,
  "on_hold": []
}

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 404 | Agentspace not found |

POST /registry/

Section titled “POST /registry/”

Create a new agentspace.

Request body

Section titled “Request body”
{
  "name": "my-agents",
  "namespace": "local",
  "tag": "latest",
  "description": "Production agents",
  "visibility": "private",
  "status": "enabled",
  "user_id": null,
  "source_repo_id": null
}

| Field | Type | Required | Description | |---|---|---|---| | name | string | Yes | Agentspace name | | namespace | string | Yes | Namespace (e.g., local, prod) | | tag | string | No | Version tag (default: latest) | | description | string | No | Human-readable description | | visibility | "private" \| "public" | No | Visibility (default: private) | | status | "enabled" \| "disabled" | No | Status (default: enabled) |

Response — 201 Created

Section titled “Response — 201 Created”

The created RepositoryMetadata object.

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 400 | Agentspace with this name/namespace already exists |

Example

Section titled “Example”
Terminal window
curl -X POST http://localhost:8080/registry/ \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agents", "namespace": "local", "tag": "latest"}'

PUT /registry/

Section titled “PUT /registry/”

Update an existing agentspace.

Request body

Section titled “Request body”
{
  "agentspace_id": "default",
  "name": "my-agents-v2",
  "description": "Updated description"
}

agentspace_id is required. All other fields are optional — only provided fields are updated.

Response — 200 OK

Section titled “Response — 200 OK”

The updated RepositoryMetadata object.

DELETE /registry/

Section titled “DELETE /registry/”

Delete an agentspace and all its data (agents, secrets, parameters).

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Agentspace to delete |

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 404 | Agentspace not found |

POST /registry/query

Section titled “POST /registry/query”

Query agentspaces by filter.

Request body

Section titled “Request body”
{
  "name": "my-agents",
  "namespace": "local",
  "status": "enabled"
}

An empty body returns all agentspaces. Supports filtering by name, namespace, tag, user_id, source_repo_id, visibility, and status.

Response — 200 OK

Section titled “Response — 200 OK”

Array of RepositoryMetadata objects.

Agent endpoints

Section titled “Agent endpoints”

POST /registry/agent

Section titled “POST /registry/agent”

Create or update an agent configuration.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Request body

Section titled “Request body”

The full AssistantConfig JSON document. See Agent Configuration for the complete schema.

{
  "assistant_id": "my-agent",
  "nickname": "Helper",
  "description": "A helpful assistant.",
  "response": {
    "provider_id": "alquimia",
    "config": {
      "provider_id": "generative",
      "connector": {
        "provider_id": "openai",
        "model": "gpt-4o-mini",
        "api_key": { "$secretRef": "OPENAI_API_KEY" }
      }
    },
    "profile": {
      "system_prompt": "You are a helpful assistant.",
      "evaluation_strategy": { "evaluation_strategy_id": "one-shoot" }
    }
  }
}

Response — 200 OK

Section titled “Response — 200 OK”

The validated AssistantConfig object.

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 400 | Validation error in the agent spec | | 404 | Agentspace not found |

Example

Section titled “Example”
Terminal window
curl -X POST "http://localhost:8080/registry/agent?agentspace_id=default" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @my-agent.json

POST /registry/agent/query

Section titled “POST /registry/agent/query”

Query agents by filter.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Request body

Section titled “Request body”
{
  "assistant_id": "my-agent",
  "nickname": "Helper"
}

An empty body returns all agents. Results are validated AssistantConfig objects.

Response — 200 OK

Section titled “Response — 200 OK”

Array of validated agent configuration objects.

DELETE /registry/agent

Section titled “DELETE /registry/agent”

Delete agents matching a filter.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Request body

Section titled “Request body”
{
  "assistant_id": "my-agent"
}

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 400 | Empty filter — a non-empty filter is required to prevent accidental bulk deletion | | 404 | Agentspace not found |

PUT /registry/agent/hold/{assistant_id}

Section titled “PUT /registry/agent/hold/{assistant_id}”

Place an agent on hold. Held agents are excluded from runtime inference — requests to a held agent return an error.

Path parameters

Section titled “Path parameters”

| Parameter | Type | Description | |---|---|---| | assistant_id | string | Agent to hold |

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Response — 200 OK

Section titled “Response — 200 OK”

The updated RepositoryMetadata object.

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 404 | Agent not found | | 409 | Agent is already on hold |

PUT /registry/agent/unhold/{assistant_id}

Section titled “PUT /registry/agent/unhold/{assistant_id}”

Remove an agent from hold, allowing it to serve inference requests again.

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 404 | Agent is not currently on hold |

Secret endpoints

Section titled “Secret endpoints”

Secrets are referenced in agent configurations with $secretRef markers and resolved at inference time from the configured backend (environment variables or HashiCorp Vault).

POST /registry/secret

Section titled “POST /registry/secret”

Add a secret to an agentspace.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace | | assistant_id | string | null | Scope the secret to a specific agent (optional) |

Request body

Section titled “Request body”
{
  "secret": {
    "key": "OPENAI_API_KEY",
    "scope": "global",
    "description": "OpenAI API key"
  },
  "value": "sk-..."
}

| Field | Type | Required | Description | |---|---|---|---| | secret.key | string | Yes | Secret key name | | secret.scope | "global" \| "shared" \| "local" | Yes | Secret scope | | secret.description | string | No | Human-readable description | | value | string | No | The actual secret value (stored in the configured backend) |

Response — 201 Created

Section titled “Response — 201 Created”

The registered Secret object (without the value).

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 400 | Agentspace has unvalidated agents — run POST /registry/validate first | | 404 | Agentspace not found |

GET /registry/secret

Section titled “GET /registry/secret”

List all secrets in an agentspace.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Response — 200 OK

Section titled “Response — 200 OK”
[
  { "key": "OPENAI_API_KEY", "scope": "global", "description": "OpenAI API key" }
]

Secret values are never returned — only metadata.

POST /registry/secret/query

Section titled “POST /registry/secret/query”

Query secrets by filter.

Request body

Section titled “Request body”
{
  "key": "OPENAI_API_KEY",
  "scope": "global"
}

An empty body returns all secrets.

POST /registry/secret/inspect/{assistant_id}

Section titled “POST /registry/secret/inspect/{assistant_id}”

Inspect secrets used by a specific agent and verify they can be resolved.

Path parameters

Section titled “Path parameters”

| Parameter | Type | Description | |---|---|---| | assistant_id | string | Agent to inspect |

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace | | check_resolution | bool | true | Try to resolve each secret against the configured backend |

Response — 200 OK

Section titled “Response — 200 OK”
{
  "secrets": [
    { "key": "OPENAI_API_KEY", "scope": "global" }
  ],
  "errors": []
}

errors contains secrets that failed to resolve when check_resolution is true. Use this to verify Vault connectivity and secret availability before publishing.

DELETE /registry/secret

Section titled “DELETE /registry/secret”

Delete secrets matching a filter.

Request body

Section titled “Request body”
{ "key": "OPENAI_API_KEY" }

A non-empty filter is required.

Parameter endpoints

Section titled “Parameter endpoints”

Parameters are typed configuration values that can be injected into agent prompts at runtime.

POST /registry/parameters

Section titled “POST /registry/parameters”

Add parameter definitions to an agentspace.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace |

Response — 201 Created

Section titled “Response — 201 Created”

The registered ParameterDef object.

POST /registry/parameters/query

Section titled “POST /registry/parameters/query”

Query parameters by filter.

Request body

Section titled “Request body”
{
  "assistant_id": "my-agent",
  "key": "language"
}

An empty body returns all parameters.

DELETE /registry/parameters

Section titled “DELETE /registry/parameters”

Delete parameters matching a filter. A non-empty filter is required.

OCI distribution endpoints

Section titled “OCI distribution endpoints”

Agent configurations are distributed as OCI artifacts (application/vnd.alquimia.registry.v1). This enables version-controlled, portable agent packages that can be published, pulled, and validated independently of the runtime.

POST /registry/validate

Section titled “POST /registry/validate”

Validate and auto-migrate all agent specs in an agentspace. Runs schema validation on every agent, applies known migration fixes, and removes unused secrets.

Run this before publishing to ensure the agentspace is in a consistent state.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace | | dry_run | bool | false | Preview changes without applying them — no agents are modified, no secrets deleted |

Response — 200 OK

Section titled “Response — 200 OK”
{
  "validated": 3,
  "errors": [],
  "deleted_secrets": []
}

| Field | Type | Description | |---|---|---| | validated | int | Number of agents successfully validated | | errors | GenericError[] | Agents that failed validation with error details | | deleted_secrets | Secret[] | Secrets removed as unused (empty when dry_run=true) |

Example

Section titled “Example”
Terminal window
# Preview what would change
curl -X POST "http://localhost:8080/registry/validate?agentspace_id=default&dry_run=true" \
  -H "Authorization: Bearer $API_TOKEN"


# Apply validation and cleanup
curl -X POST "http://localhost:8080/registry/validate?agentspace_id=default" \
  -H "Authorization: Bearer $API_TOKEN"

PUT /registry/publish

Section titled “PUT /registry/publish”

Publish an agentspace to the OCI registry.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Agentspace to publish | | tag | string | null | OCI tag (e.g., v1.0.0) |

Request body

Section titled “Request body”
{
  "description": "Production agents v1.0.0"
}

Response — 200 OK

Section titled “Response — 200 OK”

OCI push result with manifest digest.

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 400 | Unvalidated agents detected | | 400 | Unused secrets detected | | 404 | Agentspace not found |

Example

Section titled “Example”
Terminal window
curl -X PUT "http://localhost:8080/registry/publish?agentspace_id=default&tag=v1.0.0" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Production release"}'

PUT /registry/pull

Section titled “PUT /registry/pull”

Pull an agentspace from the OCI registry.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace | | target | string | null | Source OCI repository ID (e.g., ghcr.io/myorg/my-agents:v1.0.0) |

PUT /registry/unpublish

Section titled “PUT /registry/unpublish”

Remove a published manifest from the OCI registry.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | agentspace_id | string | "default" | Target agentspace | | tag | string | null | Tag to remove |

GET /registry/explore/repos

Section titled “GET /registry/explore/repos”

List repositories available in the configured OCI registry.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Default | Description | |---|---|---|---| | registry | string | null | OCI registry URL (defaults to ALQUIMIA_OCI_REGISTRY_DEFAULT) |

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 502 | OCI registry unreachable |

GET /registry/explore/tags

Section titled “GET /registry/explore/tags”

List tags for a specific OCI repository.

Query parameters

Section titled “Query parameters”

| Parameter | Type | Required | Description | |---|---|---|---| | repo_id | string | Yes | Repository identifier |

Error responses

Section titled “Error responses”

| Status | Condition | |---|---| | 502 | OCI registry unreachable |

Section titled “Related pages”