---
title: API reference
canonical: https://seminalysisgoesagentic.swarmlabs.eu/api.md
---
# API reference

Full machine-readable spec: [`/openapi.json`](/openapi.json) (OpenAPI 3.1).

## Endpoints

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/articles` | List articles (paginated) |
| GET | `/api/v1/articles/:slug` | Read an article (paid -> 402 without key) |
| GET | `/api/v1/pricing` | Pricing tiers |
| POST | `/api/v1/agent/subscribe` | Mock subscribe -> demo key |
| GET/POST | `/ask` | NLWeb search (SSE with `Accept: text/event-stream`) |
| POST | `/mcp` | Product MCP (JSON-RPC 2.0) |
| POST | `/mcp/docs` | Docs MCP (JSON-RPC 2.0) |

## Conventions

- Errors: `{ "error": { "code", "message", "docs_url" } }`
- Pagination: `?page` / `?per_page`, plus `Link` header and body `next`/`prev`
- Idempotency: send `Idempotency-Key` on `POST /agent/subscribe`
- Sandbox: mirror at `/api/sandbox/v1/*` (nothing billed)