API reference overview

The Agnes API is a REST API over HTTPS. Every endpoint is documented in the API reference section of this site, auto-rendered from sdk/openapi/openapi.json with an interactive playground for every operation. This page gives you the orientation: base URL, auth, content negotiation, and the four cross-cutting concerns that have their own pages: rate limiting, pagination, idempotency, and errors.

Authentication

Content negotiation

Request bodies are JSON. Set Content-Type: application/json.
Responses are JSON. The Content-Type is application/json; charset=utf-8.
Errors use the canonical envelope; see Errors.
Empty bodies (e.g. 204 No Content for a delete) carry no payload.

URL path conventions

All product endpoints live under /api/v1/.
Resource collections use plural nouns (/api/v1/policies/, /api/v1/yara-rules/, /api/v1/api-keys/).
Resource items live under their collection (/api/v1/policies/{policy_id}).
The hero call is POST /api/v1/analyze/. Note the trailing slash.

Versioning

The API is versioned by date, currently 2026-04-16. Pin with the Agnes-Version HTTP header to immunize against future minor changes:

Authorization: Bearer ak_live_…
Agnes-Version: 2026-04-16
Content-Type: application/json

See Authentication and Versioning for the policy.

Cross-cutting headers

Header	Direction	Meaning
`X-Request-ID`	Response	Always present. Quote in support tickets.
`Retry-After`	Response (4xx/5xx)	Seconds to wait before retrying (429, 503).
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Response	Current rate-limit window state.
`X-Billing-Status`, `X-Subscription-Status`, `X-Grace-Days-Remaining`	Response	Subscription health for the calling tenant.
`X-Agnes-Test-Mode`	Response	`true` for sandbox responses.
`Idempotency-Key`	Request	Set on write endpoints to make retries safe. See Idempotency.

Cross-cutting concerns

Concern	Reference page
Rate limiting	Rate limits
Listing large collections	Pagination
Safe retries on writes	Idempotency
Errors and retry policy	Errors

Tags

The OpenAPI document organizes operations into tags. The most customer-relevant tags:

Tag	What’s there
`Analyzer Service`	The hero `POST /api/v1/analyze/` call.
`Analyzer Catalog`	`GET /api/v1/analyzers/catalog` — schema-driven catalog of analyzers, parameters, and metrics.
`Policy Management`	CRUD for combined / Agnes policies.
`yara-rules` / `yara-policies`	YARA rules and YARA policies.
`sensitive-data-protection`	SDP policies, info types, transformations.
`safety-policies`	Custom safety policies for ShieldGemma.
`analyzer-logs`	Analysis log search and rollups.
`tenants`	Tenant CRUD and team management.
`api-keys`	API key CRUD.
`billing`	Subscription, plans, usage, invoices, customer portal.
`support`	Support ticket submission.
`webhooks`	Stripe billing webhook (server-to-server only).

The auto-generated reference is grouped by tag in the left navigation; each operation has an interactive playground that uses your bearer token.

Authentication recipes

Postman / Insomnia

Add a new request to your collection.
Auth tab → Bearer Token → paste an ak_test_… (sandbox) or ak_live_… (production) key.
Headers → add Agnes-Version: 2026-04-16.
Send.

`curl`

export AGNES_API_KEY="ak_test_…"

curl -X POST https://api.lasscyber.com/api/v1/analyze/ \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Agnes-Version: 2026-04-16" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "hello world",
    "policy_slug": "default-inbound"
  }'

`httpie`

http POST https://api.lasscyber.com/api/v1/analyze/ \
  Authorization:"Bearer $AGNES_API_KEY" \
  Agnes-Version:2026-04-16 \
  prompt="hello world" \
  policy_slug="default-inbound"

Where SDKs help

Most teams should reach for the SDKs rather than HTTP-by-hand:

They translate canonical analyzer names ↔ server keys.
They parse the error envelope into typed exceptions.
They retry 5xx / 429 / analyzer_unavailable automatically.
They iterate paginated endpoints transparently.
They surface request_id on every response and exception.

See Python SDK and TypeScript SDK.

​Authentication

​Content negotiation

​URL path conventions

​Versioning

​Cross-cutting headers

​Cross-cutting concerns

​Tags

​Authentication recipes

​Postman / Insomnia

​curl

​httpie

​Where SDKs help

​Next