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. The same crt_ key also invokes Cortega Agents at POST /agents/run when it has scope agents:run.

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
agents:run POST /agents/run (invoke a Cortega Agent; Legal Agent first)

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"
}

An application's live threat level and countdown

For an application with a threat-level policy: the current level (0 when none is raised), the violations counted, and the seconds until the level resets. A key scoped to specific applications can read only those. Returns 503 when the level store cannot be read, so a caller never mistakes an outage for level 0.

Authorizations:
cortegaApiKey
path Parameters
application
required
string

The X-Cortega-Application value.

Responses

Request samples 

curl -H "Authorization: Bearer $CORTEGA_API_KEY" \
  "https://$CORTEGA_HOST/api/v1/analytics/threat/apps/policy-out-of-scope-demo"

Response samples

Content type
application/json
{
  • "application": "string",
  • "countdown_seconds": 0,
  • "refresh_on": "hit",
  • "max_level": 0,
  • "level": 0,
  • "hits": 0,
  • "expires_in_seconds": 0,
  • "expires_at": "2019-08-24T14:15:22Z"
}

Cortega Agents

Background agents (Scorer, Risk & Fraud Detection, Sentiment, and others) that analyse a whole session. Their verdicts are readable per application instance. POST /agents/run invokes an agent immediately (Legal Agent first).

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": [
    ]
}

Invoke a Cortega Agent

Runs a Cortega Agent against caller-supplied text and returns the result immediately. First agent is Legal (Legal Agent): CourtListener lookup plus the claim-support/relevancy judge. Same pipeline as the in-product console, without writing findings and without the inline correction loop. Requires agents:run. agent accepts legal, ai_verifier, and legal_citation (empty defaults to legal).

Authorizations:
cortegaApiKey
Request Body schema: application/json
required
agent
string
response_text
required
string
request_text
string

Responses

Request samples

Content type
application/json
{
  • "agent": "string",
  • "response_text": "string",
  • "request_text": "string"
}

Response samples

Content type
application/json
{
  • "domain": "string",
  • "truth": "true",
  • "rationale": "string",
  • "citations": [
    ]
}

Coding tools

Per-developer usage of Claude Code and Codex, from the telemetry those tools send to the client telemetry collector. Separate from governed gateway traffic.

Per-developer Claude Code and Codex usage in a window

One entry per developer email seen in the window, busiest first (Claude Code cost, then tokens). Counts are window totals. Claude Code reports its own API-equivalent cost estimate. Codex reports no cost, so Cortega computes one from its token counts and the lowest list price for the model in its rate catalog (cached input at the cache-read price). Neither is a charge on a subscription. A model with no catalog price has cost_known: false and is named in unpriced_models, and its cost is not counted. by_model splits both tools by model. matched is true when the email belongs to a Cortega user. Prompt and response text is never stored. The window is capped at 90 days. A tenant key sees the rows its devices labelled with that tenant. A platform (Tenant 0) key sees every row, including rows from hand-configured clients that carry no tenant label. The label is supplied by the device with the shared collector token, so it separates tenants in the report but is not a security boundary. Returns 502 when the client telemetry store is not available, for example before the client telemetry tables are migrated.

Authorizations:
cortegaApiKey
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/coding-tools/usage?from=2026-10-01T00:00:00Z"

Response samples

Content type
application/json
{
  • "window": {
    },
  • "developers": [
    ],
  • "by_model": [
    ],
  • "totals": {
    }
}

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
{ }