Skip to main content
API docs by Redocly

Cortega Analytics API (1.0.0)

Download OpenAPI specification:Download

Read an application's governed-traffic usage and the Cortega Agents' verdicts back out. This is the control-plane read side; to send governed traffic, see the Gateway API.

A tenant admin issues an API key under System → API Access; the key is a bearer token prefixed crt_ and is shown once at creation. (Distinct from the gateway's ck_ virtual key.)

Authorization: Bearer crt_...

Every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset; a 429 includes Retry-After (seconds).

A key carries one or more scopes and, optionally, a restriction to specific applications. The key's tenant, scopes, and app restriction are resolved from the key itself — never from a request parameter, so a key can only ever read its own tenant's data.

Scope Grants
analytics:read the /analytics/* endpoints
observability:read the Observability MCP endpoint

Applications

An Application is a named thing an admin registers, with the request header that identifies it. Cortega groups all of that app's governed LLM and MCP traffic by the value the app puts in that header (an "instance" — e.g. a session id or conversation id) and reports usage per instance.

List applications this key can see

Returns the enabled applications the key is allowed to see (a key may be restricted to specific app slugs). Requires analytics:read.

Authorizations:
cortegaApiKey

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/apps"

Response samples

Content type
application/json
{
  • "apps": [
    ]
}

Traffic for one application, aggregated across every instance in a window

Authorizations:
cortegaApiKey
path Parameters
slug
required
string

The application's URL-safe slug.

query Parameters
from
string <date-time>

Window start (RFC3339). Default is 24h before to.

to
string <date-time>

Window end (RFC3339). Default now. The span is capped at 90 days.

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/apps/vcontest?from=2026-09-01T00:00:00Z"

Response samples

Content type
application/json
{
  • "app": {
    },
  • "window": {
    },
  • "traffic": {
    }
}

List an application's instances (distinct ID-header values) in a window

Instances overlapping the window, newest last-seen first. Page with limit and the next_cursor from the previous response.

Authorizations:
cortegaApiKey
path Parameters
slug
required
string

The application's URL-safe slug.

query Parameters
from
string <date-time>

Window start (RFC3339). Default is 24h before to.

to
string <date-time>

Window end (RFC3339). Default now. The span is capped at 90 days.

limit
integer <= 500
Default: 100
cursor
string

Opaque cursor from a previous response's next_cursor.

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/apps/vcontest/instances?limit=50"

Response samples

Content type
application/json
{
  • "app": {
    },
  • "window": {
    },
  • "instances": [
    ],
  • "next_cursor": "string"
}

Full traffic breakdown for one instance (one ID-header value)

One ID value's LLM usage (per model / provider) and MCP usage (per server / tool). The window is the instance's own first-seen … last-seen span; this endpoint takes no from/to.

Authorizations:
cortegaApiKey
path Parameters
slug
required
string

The application's URL-safe slug.

instanceId
required
string

The value the application sent in its ID header (e.g. a vCon UUID).

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/apps/vcontest/instances/0191ae8b-7412-7000-8800-aad4f5bf0bd5"

Response samples

Content type
application/json
{
  • "app": {
    },
  • "instance_id": "0191ae8b-7412-7000-8800-aad4f5bf0bd5",
  • "traffic": {
    },
  • "computed_at": "2026-09-07T18:25:00Z"
}

Cortega Agents

Background agents (Scorer, Risk & Fraud Detection, Sentiment, and others) that analyse a whole session. Their verdicts are readable per application instance.

Cortega Agents' verdicts for one instance (one ID-header value)

Every session agent's latest result for one ID-header value. Only agents the tenant has enabled and licensed, and whose configuration names this application, appear. An unknown or not-yet-analysed instance returns agents: [] with 200.

A session is scored once it has been quiet for the agent's quiet period and finalised after a period of silence; until then a row comes back with status: "accumulating" and no score. score can change across run_count re-runs as the conversation grows.

Authorizations:
cortegaApiKey
path Parameters
slug
required
string

The application's URL-safe slug.

instanceId
required
string

The value the application sent in its ID header (e.g. a vCon UUID).

query Parameters
agent
string

Narrow to one agent domain, e.g. scorer or risk.

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/apps/vcontest/instances/0191ae8b-7412-7000-8800-aad4f5bf0bd5/agents?agent=risk"

Response samples

Content type
application/json
{
  • "app": {
    },
  • "instance_id": "0191ae8b-7412-7000-8800-aad4f5bf0bd5",
  • "agents": [
    ]
}

Observability

A Model Context Protocol server over the tenant's governed-traffic telemetry.

Observability MCP endpoint (Streamable HTTP / JSON-RPC)

A Model Context Protocol server (Streamable HTTP, stateless JSON responses) exposing the tenant's governed-traffic telemetry as MCP tools: traffic_summary, recent_failures, model_performance, spend_breakdown, guardrail_activity, mcp_tool_activity. Requires observability:read. Every query is scoped to the key's tenant. The request and response bodies are MCP JSON-RPC and are not modelled here — point an MCP client at this URL with the crt_ key as a bearer token.

Authorizations:
cortegaApiKey
Request Body schema: application/json
required
object

An MCP JSON-RPC request.

Responses

Request samples

Content type
application/json
{ }