> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lasscyber.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference overview

> How to use the Agnes HTTP API directly. Endpoint pages are auto-generated from the OpenAPI document.

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`](https://github.com/lasscyber/agnes-docs/tree/main/policy-fixtures)
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.

<Snippet file="api-base.mdx" />

## Authentication

<Snippet file="auth-bearer.mdx" />

## 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](/errors/overview).
* **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:

```http theme={null}
Authorization: Bearer ak_live_…
Agnes-Version: 2026-04-16
Content-Type: application/json
```

See [Authentication](/get-started/authentication#pinning-the-api-contract-version)
and [Versioning](/sdks/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](/api-reference/idempotency). |

## Cross-cutting concerns

| Concern                   | Reference page                            |
| ------------------------- | ----------------------------------------- |
| Rate limiting             | [Rate limits](/api-reference/rate-limits) |
| Listing large collections | [Pagination](/api-reference/pagination)   |
| Safe retries on writes    | [Idempotency](/api-reference/idempotency) |
| Errors and retry policy   | [Errors](/errors/overview)                |

## 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

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`

```bash theme={null}
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`

```bash theme={null}
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](/sdks/python) and
[TypeScript SDK](/sdks/typescript).

## Next

* [Rate limits](/api-reference/rate-limits)
* [Pagination](/api-reference/pagination)
* [Idempotency](/api-reference/idempotency)
* [Errors](/errors/overview)