API reference

Linked Services

Linked Services are workspace-owned, independently named provider connections. Several services can use the same curated provider type.

Linked service calls

service_id is immutable. name, enabled, and config are mutable. provider_type must be one of the curated provider identifiers. config.api_key is write-only; responses return base_url, key_trimmed, configured, and static available_models derived from active logical catalog models. Available models are never stored in the linked-services table.

List linked services

GET /api/v1/linked-services returns every linked service in the selected workspace as a JSON array.

GET /api/v1/linked-services
X-Workspace-ID: workspace-acme

Example response (200 OK):

[
  {
    "id": "linked-service-openai-primary",
    "name": "primary_openai",
    "provider_type": "openai",
    "enabled": true,
    "config": {
      "base_url": "https://api.openai.com/v1",
      "key_trimmed": "sk-...abcd",
      "configured": true,
      "available_models": ["gpt-5"]
    },
    "version": 1,
    "created_at": "2026-08-13T10:00:00Z",
    "updated_at": "2026-08-13T10:00:00Z"
  }
]

Create a linked service

POST /api/v1/linked-services creates a named service and tests its candidate configuration before it is stored. enabled defaults to true. A provider that requires credentials must receive a usable config.api_key before it can be enabled.

POST /api/v1/linked-services
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "name": "primary_openai",
  "provider_type": "openai",
  "enabled": true,
  "config": {
    "api_key": "provider-api-key",
    "base_url": "https://api.openai.com/v1"
  }
}

Example response (201 Created):

{
  "id": "linked-service-openai-primary",
  "name": "primary_openai",
  "provider_type": "openai",
  "enabled": true,
  "config": {
    "base_url": "https://api.openai.com/v1",
    "key_trimmed": "sk-...abcd",
    "configured": true,
    "available_models": ["gpt-5"]
  },
  "version": 1,
  "created_at": "2026-08-13T10:00:00Z",
  "updated_at": "2026-08-13T10:00:00Z"
}

Describe a linked service

GET /api/v1/linked-services/{service_id} returns one service in the selected workspace. The response has the same shape as a list item and never includes the full API key.

GET /api/v1/linked-services/linked-service-openai-primary
X-Workspace-ID: workspace-acme

The endpoint returns 404 linked_service_not_found when the selected workspace does not own service_id.

Update a linked service

PATCH /api/v1/linked-services/{service_id} accepts one or more of name, enabled, or config. Supplying config.api_key: null clears the stored key; supplying config.base_url: null restores the provider default. enabled must be a boolean when supplied. Configuration changes and enabling a disabled service validate and test the candidate connection before storage.

PATCH /api/v1/linked-services/linked-service-openai-primary
X-Workspace-ID: workspace-acme
Content-Type: application/json

{
  "enabled": false
}

The endpoint returns the updated linked-service response (200 OK). An empty request returns 422.

Delete a linked service

DELETE /api/v1/linked-services/{service_id} removes a service that is not referenced by another workspace resource.

DELETE /api/v1/linked-services/linked-service-openai-primary
X-Workspace-ID: workspace-acme

Example response (200 OK):

{
  "deleted": true
}

The endpoint returns 409 resource_in_use while a Persona or another resource still references the service, and 404 linked_service_not_found when the service does not exist in the selected workspace.