The Telemetry API manages the OpenTelemetry destinations shown under Telemetry (/app/telemetry) in the dashboard. Use it to export security events as OTLP logs to Datadog, Grafana Cloud, or your own collector without using the dashboard.

All requests require an organization API key sent as a bearer token in the Authorization header, as described in the REST API. Destinations are scoped to the API key's organization. Only OTLP destinations are visible through this API; signed webhook targets remain available through the dashboard and Webhooks.

Endpoints

export SUPERAGENT_API_KEY="sk_live_..."
export SUPERAGENT_API_URL="https://superagent.sh/api/v1"

Create a destination

POST /api/v1/telemetry creates an opt-in export destination. Export is paused when enabled is false.

curl -X POST "$SUPERAGENT_API_URL/telemetry" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Datadog production",
    "url":"https://http-intake.logs.datadoghq.com/api/v2/otlp/v1/logs",
    "protocol":"otlp_http_protobuf",
    "headers":{"dd-api-key":"replace-with-a-datadog-api-key"},
    "event_types":["finding.created","finding.triage_completed","report.finished"],
    "source_types":["repository","application","agent"]
  }'

Request fields

201 Created returns the destination under data with object: "telemetry_endpoint". The response includes has_headers instead of header values.

{
  "data": {
    "id": "3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b",
    "object": "telemetry_endpoint",
    "name": "Datadog production",
    "url": "https://http-intake.logs.datadoghq.com/api/v2/otlp/v1/logs",
    "protocol": "otlp_http_protobuf",
    "enabled": true,
    "event_types": ["finding.created", "finding.triage_completed", "report.finished"],
    "source_types": ["repository", "application", "agent"],
    "source_filters": { "repository": [], "application": [], "agent": [] },
    "has_headers": true,
    "created_at": "2026-10-02T07:00:00.000Z",
    "updated_at": "2026-10-02T07:00:00.000Z"
  }
}

List and retrieve destinations

GET /api/v1/telemetry returns all OTLP destinations, newest first, under data as an array. GET /api/v1/telemetry/{endpoint_id} returns one destination. Both use the same object shape as the create response. Header values are never returned; use has_headers to check whether credentials are configured.

curl "$SUPERAGENT_API_URL/telemetry" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

curl "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

Destinations with the signed webhook transport are not listed and return 404 not_found when requested by ID through this API.

Update a destination

PATCH /api/v1/telemetry/{endpoint_id} updates only the fields provided. Omitted fields preserve their saved values, including saved authentication headers.

curl -X PATCH "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "protocol": "otlp_http_json"
  }'

To replace authentication headers, send a new headers object. To clear saved headers, send "headers": null or "headers": {}. Omitting headers keeps the saved credentials. The protocol can switch between otlp_http_protobuf and otlp_http_json; switching between OTLP and signed webhooks is rejected — create a new destination instead.

A request with no supported fields returns 400 invalid_request.

Delete a destination

DELETE /api/v1/telemetry/{endpoint_id} permanently deletes the destination and stops exporting events to it.

curl -X DELETE "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

The response is 200 OK with { "data": { "deleted": true } }. This cannot be undone.

Test a destination

POST /api/v1/telemetry/{endpoint_id}/test sends a synthetic OTLP log event directly to the collector and returns whether it was accepted. It does not go through the queued event outbox.

curl -X POST "$SUPERAGENT_API_URL/telemetry/3f9c2b8e-0c2a-4b5e-9f1a-2c3d4e5f6a7b/test" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

{
  "data": {
    "ok": true,
    "status": 200,
    "event_type": "report.finished"
  }
}

ok: false means the collector rejected the event or returned an invalid OTLP export response. Check the endpoint URL, protocol, and credentials, then retry. To verify the queued event path instead, trigger a subscribed action — such as starting a report — and look for its event in your destination. See Telemetry for Datadog setup and delivery details.

Events and delivery

Telemetry exports the same event catalog and uses the same source matching rules as webhooks. Each event becomes an OTLP log record with service.name: superagent; the body contains the webhook event envelope. The export shares the event outbox, source matching, and asynchronous retry behavior used by webhooks. Header values are encrypted at rest and are never shown after saving.

MCP tools

The same operations are available through the Superagent MCP server:

MCP responses match the REST payloads for list, retrieve, create, update, and test, including has_headers instead of header values. The delete tool also returns endpoint_id alongside deleted.

Errors

Next steps

• Export events with Telemetry
• Subscribe to events with Webhooks
• Use Superagent MCP