Observability

Manage observability integrations — connections that export agent telemetry to an external tracing backend such as Grafana Cloud, LangSmith, or any OTLP-compatible collector. An integration applies to all agents by default, or can be scoped to specific agents.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

Every observability endpoint is admin only.

The integration object

PublicObservabilityIntegration is returned by most endpoints here.

Field	Type	Description
id	string	Integration ID (UUID).
kind	string	Integration type.
settings	object	Provider settings, including credentials (see below).
resolved_url	string	Provider URL with supported environment placeholders resolved, when available (nullable).
description	string	Optional description (nullable).
version	string	Version of the integration configuration (nullable).
is_system	boolean	Whether the integration is managed by the deployment instead of user configuration.
debug	boolean	Whether the integration also receives application and infrastructure traces.
created_at / updated_at	string	Timestamps.

Provider settings

The settings.provider field selects the shape:

grafana — url (full OTLP traces endpoint), api_token, grafana_instance_id; optional additional_headers (extra HTTP headers sent when exporting) and stack_name (Grafana Cloud stack name used when building trace links).
langsmith — url (LangSmith OTLP endpoint), project_name, api_key.
otlp_basic_auth — url (OTLP endpoint), username, password; optional trace_view_url (trace UI base URL used when building trace links) and trace_ui_type (grafana, jaeger, or unknown).
otlp_custom_headers — url (OTLP endpoint); optional headers (map of custom HTTP headers sent when exporting), trace_view_url, and trace_ui_type.

Every shape also carries is_enabled (boolean, default true) — whether telemetry export is enabled for the integration.

List integrations

GET /observability/integrations

Returns an array of integrations.

Query parameters

Parameter	Type	Description
provider	string	Filter by provider — `grafana`, `langsmith`, `otlp_basic_auth`, or `otlp_custom_headers`.
agent_id	string	When provided, returns global integrations plus integrations assigned to that agent.

Create integration

POST /observability/integrations

Creates an integration. New integrations apply globally by default (see Scopes).

Body

Field	Type	Required	Description
settings	object	Yes	Provider settings (see the shapes above).
version	string	Yes	Version of the integration configuration.
description	string	No	Optional description.
is_system	boolean	No	Whether the integration is managed by the deployment instead of user configuration. Default `false`.
debug	boolean	No	Whether the integration also receives application and infrastructure traces. Default `false`.

curl -X POST 'https://{your-deployment-host}/api/v2/observability/integrations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "provider": "langsmith",
      "url": "https://api.smith.langchain.com/otel/v1/traces",
      "project_name": "production-agents",
      "api_key": "lsv2_..."
    },
    "version": "1"
  }'

Returns 201 Created with the new PublicObservabilityIntegration.

Get integration

GET /observability/integrations/{integration_id}

Returns a single PublicObservabilityIntegration.

Update integration

PUT /observability/integrations/{integration_id}

Updates an integration. Omitted fields are left unchanged.

Body

Field	Type	Required	Description
settings	object	No	New provider settings (see the shapes above).
version	string	No	New configuration version.
description	string	No	New description.
debug	boolean	No	Whether the integration also receives application and infrastructure traces.

Returns the updated PublicObservabilityIntegration.

Enable, disable, or toggle debug

PATCH /observability/integrations/{integration_id}

Updates the enabled state or application-trace forwarding without touching the rest of the configuration.

Body

Field	Type	Required	Description
is_enabled	boolean	No	Whether telemetry export is enabled.
debug	boolean	No	Whether the integration also receives application and infrastructure traces.

curl -X PATCH 'https://{your-deployment-host}/api/v2/observability/integrations/{integration_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "is_enabled": false }'

Returns the updated PublicObservabilityIntegration.

Delete integration

DELETE /observability/integrations/{integration_id}

Deletes the integration. Returns 204 No Content.

Scopes

A scope controls where an integration applies: global (all agents) or agent (one specific agent). New integrations are global by default.

The scope object:

Field	Type	Description
integration_id	string	ID of the integration.
scope	string	`global` or `agent`.
agent_id	string	Agent ID for agent-specific scope; `null` for global.
created_at	string	When the scope was created.

List scopes

GET /observability/integrations/{integration_id}/scopes

Returns an array of the integration's scope assignments.

Set scope

POST /observability/integrations/{integration_id}/scopes

Body

Field	Type	Required	Description
scope	string	Yes	`global` or `agent`.
agent_id	string	No	Agent ID. Required when `scope` is `agent`.

curl -X POST 'https://{your-deployment-host}/api/v2/observability/integrations/{integration_id}/scopes' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "scope": "agent", "agent_id": "{agent_id}" }'

Returns 201 Created with the new scope object.

Delete scope

DELETE /observability/integrations/{integration_id}/scopes

Removes a scope assignment. Pass the scope to remove as query parameters: scope (required, global or agent) and agent_id (for agent scopes). Returns 204 No Content.

curl -X DELETE 'https://{your-deployment-host}/api/v2/observability/integrations/{integration_id}/scopes?scope=agent&agent_id={agent_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Audit log Document Intelligence