Skip to main content
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

HeaderDirectionMeaning
X-Request-IDResponseAlways present. Quote in support tickets.
Retry-AfterResponse (4xx/5xx)Seconds to wait before retrying (429, 503).
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetResponseCurrent rate-limit window state.
X-Billing-Status, X-Subscription-Status, X-Grace-Days-RemainingResponseSubscription health for the calling tenant.
X-Agnes-Test-ModeResponsetrue for sandbox responses.
Idempotency-KeyRequestSet on write endpoints to make retries safe. See Idempotency.

​
Cross-cutting concerns

ConcernReference page
Rate limitingRate limits
Listing large collectionsPagination
Safe retries on writesIdempotency
Errors and retry policyErrors

​
Tags

The OpenAPI document organizes operations into tags. The most customer-relevant tags:
TagWhat’s there
Analyzer ServiceThe hero POST /api/v1/analyze/ call.
Analyzer CatalogGET /api/v1/analyzers/catalog — schema-driven catalog of analyzers, parameters, and metrics.
Policy ManagementCRUD for combined / Agnes policies.
yara-rules / yara-policiesYARA rules and YARA policies.
sensitive-data-protectionSDP policies, info types, transformations.
safety-policiesCustom safety policies for ShieldGemma.
analyzer-logsAnalysis log search and rollups.
tenantsTenant CRUD and team management.
api-keysAPI key CRUD.
billingSubscription, plans, usage, invoices, customer portal.
supportSupport ticket submission.
webhooksStripe 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

  1. Add a new request to your collection.
  2. Auth tab → Bearer Token → paste an ak_test_… (sandbox) or ak_live_… (production) key.
  3. Headers → add Agnes-Version: 2026-04-16.
  4. 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.

​
Next