{ "openapi": "3.1.0", "info": { "title": "captur.events API Reference", "version": "1.0.0", "description": "# captur.events API\n\nAuthenticate with a project API key:\n\n```\nAuthorization: Bearer evt_test_\u2026 # or evt_live_\u2026\n```\n\n**Base URL:** `{APP_URL}\/v1`\n\n1. Register event types (`POST \/event-types`)\n2. Ingest events (`POST \/events`) \u2014 single object or JSON array (batch)\n3. List, retrieve, delete events \/ streams\n4. Webhooks, alerts, projections (plan-gated)\n5. Session reports (`GET \/reports\/sessions`)\n\n### Auth errors\n\n| Status | Code | When |\n|--------|------|------|\n| `401` | `missing_api_key` \/ `invalid_api_key` | Missing, wrong, or revoked Bearer token |\n| `403` | `api_access_denied` | Workspace IP or origin\/domain allowlist rejected the request (`parameter`: `ip` or `origin`) |\n| `403` | `feature_not_available` | Plan does not include the feature |\n| `429` | `rate_limit_exceeded` | Per-key request throttle |\n| `429` | `monthly_quota_exceeded` | Monthly ingest cap (`POST \/events`) |\n\nError bodies use `{ \"error\": { \"type\", \"code\", \"message\", \u2026 } }`.\n\nGuides: [\/docs\/authentication](\/docs\/authentication) \u00b7 [\/docs\/errors](\/docs\/errors) \u00b7 Developers: [\/developers](\/developers)", "x-scalar-sdk-installation": [ { "lang": "Shell", "description": "Use cURL with a project API key from **Developers** (`evt_test_\u2026` or `evt_live_\u2026`).\n\n```bash\ncurl https:\/\/captur.events\/v1\/events \\\n -H \"Authorization: Bearer evt_test_...\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\n \"type\": \"vehicle.entered\",\n \"stream\": \"vehicle:AB12XYZ\",\n \"data\": { \"car_park_id\": \"teeside-central\" }\n }'\n```" }, { "lang": "Node.js", "description": "Call the HTTP API with `fetch` (Node 18+). No official npm package yet.\n\n```js\nconst base = 'https:\/\/captur.events\/v1';\nconst key = process.env.CAPTUR_API_KEY; \/\/ evt_test_\u2026 or evt_live_\u2026\n\nconst res = await fetch(`${base}\/events`, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${key}`,\n 'Content-Type': 'application\/json',\n },\n body: JSON.stringify({\n type: 'vehicle.entered',\n stream: 'vehicle:AB12XYZ',\n data: { car_park_id: 'teeside-central' },\n }),\n});\n\nconst event = await res.json();\nconsole.log(res.status, event);\n```" }, { "lang": "PHP", "description": "Use Guzzle \/ Laravel HTTP, or the in-repo SDK stub (`sdk\/php`) when you publish it.\n\n```php\n$base = 'https:\/\/captur.events\/v1';\n$key = getenv('CAPTUR_API_KEY'); \/\/ evt_test_\u2026 or evt_live_\u2026\n\n$response = \\Illuminate\\Support\\Facades\\Http::withToken($key)\n ->acceptJson()\n ->post($base . '\/events', [\n 'type' => 'vehicle.entered',\n 'stream' => 'vehicle:AB12XYZ',\n 'data' => ['car_park_id' => 'teeside-central'],\n ]);\n\n$event = $response->json();\n```" }, { "lang": "Python", "description": "Use `requests` (or `httpx`) against the same HTTP API.\n\n```python\nimport os\nimport requests\n\nbase = \"https:\/\/captur.events\/v1\"\nkey = os.environ[\"CAPTUR_API_KEY\"] # evt_test_\u2026 or evt_live_\u2026\n\nr = requests.post(\n f\"{base}\/events\",\n headers={\"Authorization\": f\"Bearer {key}\"},\n json={\n \"type\": \"vehicle.entered\",\n \"stream\": \"vehicle:AB12XYZ\",\n \"data\": {\"car_park_id\": \"teeside-central\"},\n },\n)\nprint(r.status_code, r.json())\n```" }, { "lang": "Ruby", "description": "Use `net\/http` (or Faraday) with your project API key.\n\n```ruby\nrequire \"net\/http\"\nrequire \"json\"\nrequire \"uri\"\n\nbase = \"https:\/\/captur.events\/v1\"\nkey = ENV.fetch(\"CAPTUR_API_KEY\") # evt_test_\u2026 or evt_live_\u2026\n\nuri = URI(\"#{base}\/events\")\nhttp = Net::HTTP.new(uri.host, uri.port)\nhttp.use_ssl = uri.scheme == \"https\"\n\nreq = Net::HTTP::Post.new(uri)\nreq[\"Authorization\"] = \"Bearer #{key}\"\nreq[\"Content-Type\"] = \"application\/json\"\nreq.body = {\n type: \"vehicle.entered\",\n stream: \"vehicle:AB12XYZ\",\n data: { car_park_id: \"teeside-central\" },\n}.to_json\n\nres = http.request(req)\nputs res.code, res.body\n```" } ] }, "servers": [ { "url": "https:\/\/captur.events\/v1", "description": "Local" }, { "url": "https:\/\/api.captur.events\/v1", "description": "Production" } ], "tags": [ { "name": "Event types", "description": "Register and manage the event type allowlist for a project. Types must exist before ingest; optional JSON Schema validates `data`." }, { "name": "Events", "description": "Ingest, list, retrieve, and delete events. Supports filters, pagination, streams, and idempotent writes." }, { "name": "Streams", "description": "Read or delete an entity timeline (`stream` id) as an ordered history of events." }, { "name": "Webhooks", "description": "HTTPS endpoints that receive signed event deliveries, plus the email test inbox for local integration." }, { "name": "Reports", "description": "Derived reports over stored events \u2014 start\u2192end session pairing for dwell, runtime, SLA, and timesheets." }, { "name": "Alerts", "description": "Notify your team by email, Slack, or SMS when matching event types are ingested (Growth+)." }, { "name": "Projections", "description": "Event-sourced read models you create, update, delete, and replay from history (Growth+)." } ], "security": [ { "bearerAuth": [] } ], "paths": { "\/event-types": { "get": { "operationId": "listEventTypes", "description": "Return the allowlist of event types registered for this project, including optional JSON Schemas and indexed filter keys.", "summary": "List event types", "tags": [ "Event types" ], "responses": { "200": { "description": "Event type allowlist", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "data_schema": { "type": [ "array", "null" ], "items": {} }, "metadata_schema": { "type": [ "array", "null" ], "items": {} }, "indexed_data_keys": { "type": "array", "items": {} }, "indexed_metadata_keys": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "name", "description", "data_schema", "metadata_schema", "indexed_data_keys", "indexed_metadata_keys", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createEventType", "description": "Add a type to the project allowlist. Optionally attach JSON Schemas for `data` \/ `metadata`\nand declare top-level keys to index for filtering.\n\nNames use dotted lowercase segments (`resource.action`), e.g. `vehicle.entered`.", "summary": "Register an event type", "tags": [ "Event types" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "data_schema": { "type": [ "array", "null" ], "items": { "type": "string" } }, "metadata_schema": { "type": [ "array", "null" ], "items": { "type": "string" } }, "indexed_data_keys": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "maxItems": 20 }, "indexed_metadata_keys": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "maxItems": 20 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "data_schema": { "type": [ "array", "null" ], "items": {} }, "metadata_schema": { "type": [ "array", "null" ], "items": {} }, "indexed_data_keys": { "type": "array", "items": {} }, "indexed_metadata_keys": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "name", "description", "data_schema", "metadata_schema", "indexed_data_keys", "indexed_metadata_keys", "created_at", "updated_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/event-types\/{eventType}": { "get": { "operationId": "getEventType", "description": "Fetch a single registered event type by name.", "summary": "Retrieve an event type", "tags": [ "Event types" ], "parameters": [ { "name": "eventType", "in": "path", "required": true, "description": "Dotted event type name, e.g. `vehicle.entered`.", "schema": { "type": "string" }, "example": "vehicle.entered" } ], "responses": { "200": { "description": "Event type", "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "data_schema": { "type": [ "array", "null" ], "items": {} }, "metadata_schema": { "type": [ "array", "null" ], "items": {} }, "indexed_data_keys": { "type": "array", "items": {} }, "indexed_metadata_keys": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "name", "description", "data_schema", "metadata_schema", "indexed_data_keys", "indexed_metadata_keys", "created_at", "updated_at" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateEventType", "description": "Update description, JSON Schemas, or indexed filter keys. The type name cannot change.", "summary": "Update an event type", "tags": [ "Event types" ], "parameters": [ { "name": "eventType", "in": "path", "required": true, "description": "Dotted event type name.", "schema": { "type": "string" }, "example": "vehicle.entered" } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 255 }, "data_schema": { "type": [ "array", "null" ], "items": { "type": "string" } }, "metadata_schema": { "type": [ "array", "null" ], "items": { "type": "string" } }, "indexed_data_keys": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "maxItems": 20 }, "indexed_metadata_keys": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "maxItems": 20 } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "data_schema": { "type": [ "array", "null" ], "items": {} }, "metadata_schema": { "type": [ "array", "null" ], "items": {} }, "indexed_data_keys": { "type": "array", "items": {} }, "indexed_metadata_keys": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "name", "description", "data_schema", "metadata_schema", "indexed_data_keys", "indexed_metadata_keys", "created_at", "updated_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteEventType", "description": "Remove a type from the allowlist. Existing stored events are not deleted.", "summary": "Delete an event type", "tags": [ "Event types" ], "parameters": [ { "name": "eventType", "in": "path", "required": true, "description": "Dotted event type name.", "schema": { "type": "string" }, "example": "vehicle.entered" } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/events": { "post": { "operationId": "createEvent", "description": "Append a single event, or a JSON array of up to 500 events.\n\nReturns **202 Accepted** once the event is durably stored. Webhooks and indexing run asynchronously.\n\nThe `type` **must already be registered** via `POST \/event-types`. Unknown types return `422` with code\n`unknown_event_type`.", "summary": "Create an event", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Registered event type, e.g. `vehicle.entered`.", "examples": [ "vehicle.entered" ] }, "stream": { "type": "string", "description": "Stream id for entity history, e.g. `vehicle:AB12XYZ`. Alias: `stream_id`.", "examples": [ "vehicle:AB12XYZ" ] }, "stream_id": { "type": "string", "description": "Alias for `stream`.", "examples": [ "vehicle:AB12XYZ" ] }, "data": { "type": "object", "description": "Arbitrary JSON payload (max 256 KB).", "examples": [ { "car_park_id": "teeside-central", "entrance": "north" } ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "Optional business time as ISO-8601 with timezone (`Z` or \u00b1HH:MM). Naive local times are rejected. Omit to use receive time.", "examples": [ "2026-08-01T08:45:00Z" ] }, "subject_id": { "type": "string", "description": "Secondary lookup key." }, "idempotency_key": { "type": "string", "description": "Safe retries \u2014 same key returns the original event." }, "expected_version": { "type": "integer", "description": "Optimistic concurrency on the stream. Rejects with 409 if mismatched.", "examples": [ 14 ] }, "metadata": { "type": "object", "description": "Optional envelope (not indexed as event data)." } }, "required": [ "type" ] } } } }, "responses": { "202": { "description": "Accepted \u2014 event stored", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "id": "01J9X2K8M3N4P5Q6R7S8T9V0W1", "type": "vehicle.entered", "stream": "vehicle:AB12XYZ", "stream_id": "vehicle:AB12XYZ", "stream_version": 15, "subject_id": null, "occurred_at": "2026-08-01T08:45:00+00:00", "received_at": "2026-08-01T08:45:01+00:00", "data": { "car_park_id": "teeside-central", "entrance": "north" }, "metadata": null } ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "stream": { "type": [ "string", "null" ] }, "stream_id": { "type": [ "string", "null" ] }, "stream_version": { "type": [ "integer", "null" ] }, "subject_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "data": { "type": [ "object", "null" ] }, "metadata": { "type": [ "object", "null" ] } }, "required": [ "id", "type", "stream", "stream_id", "stream_version", "subject_id", "occurred_at", "received_at", "data", "metadata" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers. Also: Monthly event quota exceeded (`monthly_quota_exceeded`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "quota_error", "code": "monthly_quota_exceeded", "message": "Monthly event quota exceeded.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "409": { "description": "Expected version conflict", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "description": "Validation error (unknown or missing type, payload too large, etc.)", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "listEvents", "description": "Page through events with filters. Hot (recent) and cold (cached) history are merged automatically.\n\n**Pagination (pick one):**\n- **Offset:** `page` (1-based) + `limit` \u2014 `meta` includes `current_page`, `last_page`, `total`\n- **Cursor:** `cursor` (from `meta.next_cursor`) or `starting_after` (event id) + `limit` \u2014 `meta` includes\n`has_more`, `next_cursor`\n\nDo not combine `page` with `cursor` \/ `starting_after`. Newest-first.\n\n**Indexed payload filters:** `data[key]=value` and `metadata[key]=value` only work for keys declared on the event type\n(`indexed_data_keys` \/ `indexed_metadata_keys`).", "summary": "List events", "tags": [ "Events" ], "parameters": [ { "name": "type", "in": "query", "description": "Filter by event type.", "schema": { "type": "string" }, "example": "vehicle.entered" }, { "name": "stream", "in": "query", "description": "Filter by stream id.", "schema": { "type": "string" }, "example": "vehicle:AB12XYZ" }, { "name": "subject_id", "in": "query", "description": "Filter by subject id.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Inclusive lower bound (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound (ISO-8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "Page size \/ per page (1\u2013200, default 50).", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "description": "Offset pagination: 1-based page number. Do not combine with cursor.", "schema": { "type": "integer" }, "example": 1 }, { "name": "cursor", "in": "query", "description": "Cursor pagination: opaque token from meta.next_cursor.", "schema": { "type": "string" } }, { "name": "starting_after", "in": "query", "description": "Cursor pagination: continue after this event id (ULID).", "schema": { "type": "string" } }, { "name": "data", "in": "query", "description": "Indexed data filters as nested object, e.g. `data[car_park_id]=north`.", "schema": { "type": "object" }, "x-deepObject-style": "qs" }, { "name": "metadata", "in": "query", "description": "Indexed metadata filters as nested object, e.g. `metadata[source]=gate`.", "schema": { "type": "object" }, "x-deepObject-style": "qs" } ], "responses": { "200": { "description": "Event page", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "pagination": { "type": "string", "const": "page" }, "current_page": { "type": [ "object", "null" ] }, "last_page": { "type": [ "object", "null" ] }, "per_page": { "type": [ "object", "null" ] }, "total": { "type": "string" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "cache": { "type": "string", "enum": [ "mixed", "cold", "hot" ] }, "hot_count": { "type": "string" }, "cold_count": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "hot_returned": { "type": "integer" }, "cold_returned": { "type": "integer" } }, "required": [ "pagination", "current_page", "last_page", "per_page", "total", "has_more", "next_cursor", "cache", "hot_count", "cold_count", "hot_returned", "cold_returned" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "stream": { "type": [ "string", "null" ] }, "stream_id": { "type": [ "string", "null" ] }, "stream_version": { "type": [ "integer", "null" ] }, "subject_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "data": { "type": [ "array", "null" ], "items": {} }, "metadata": { "type": [ "array", "null" ], "items": {} } }, "required": [ "id", "type", "stream", "stream_id", "stream_version", "subject_id", "occurred_at", "received_at", "data", "metadata" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "string", "const": "cursor" }, "per_page": { "type": [ "object", "null" ] }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "cache": { "type": "string", "enum": [ "mixed", "cold", "hot" ] }, "hot_returned": { "type": "integer" }, "cold_returned": { "type": "integer" } }, "required": [ "pagination", "per_page", "has_more", "next_cursor", "cache", "hot_returned", "cold_returned" ] } }, "required": [ "data", "meta" ] } ] } } } }, "422": { "description": "Unindexed filter key or conflicting pagination", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/events\/delete": { "post": { "operationId": "deleteEvents", "description": "Permanently delete up to 500 events by id. Unknown ids are skipped. This cannot be undone.", "summary": "Delete events in bulk", "tags": [ "Events" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "description": "Event ULIDs to delete (1\u2013500).", "examples": [ [ "01J9X2K8M3N4P5Q6R7S8T9V0W1", "01J9X2K8M3N4P5Q6R7S8T9V0W2" ] ], "items": { "type": "string", "maxLength": 40 } } }, "required": [ "ids" ] } } } }, "responses": { "200": { "description": "Deletion summary", "content": { "application\/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" }, "requested": { "type": "integer" }, "not_found": { "type": "array", "items": {} } }, "required": [ "deleted", "requested", "not_found" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/events\/{event}": { "get": { "operationId": "getEvent", "description": "Fetch a single event by ULID. Older events may be served from cold storage cache.", "summary": "Retrieve an event", "tags": [ "Events" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "Event ULID.", "schema": { "type": "string" }, "example": "01J9X2K8M3N4P5Q6R7S8T9V0W1" } ], "responses": { "200": { "description": "Event payload", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "stream": { "type": [ "string", "null" ] }, "stream_id": { "type": [ "string", "null" ] }, "stream_version": { "type": [ "integer", "null" ] }, "subject_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "data": { "type": [ "array", "null" ], "items": {} }, "metadata": { "type": [ "array", "null" ], "items": {} } }, "required": [ "id", "type", "stream", "stream_id", "stream_version", "subject_id", "occurred_at", "received_at", "data", "metadata" ] }, { "type": "null" }, { "type": "object", "additionalProperties": {} } ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "not_found" }, "code": { "type": "string", "const": "event_not_found" }, "message": { "type": "string", "const": "Event not found." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteEvent", "description": "Permanently delete a single event by ULID. This cannot be undone. Stream tip versions are not rewritten \u2014 gaps in `stream_version` may remain.", "summary": "Delete an event", "tags": [ "Events" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "Event ULID.", "schema": { "type": "string" }, "example": "01J9X2K8M3N4P5Q6R7S8T9V0W1" } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/streams\/{stream}": { "get": { "operationId": "readStream", "description": "Return the ordered event history for a stream id (entity timeline), newest and oldest metadata included.", "summary": "Read a stream", "tags": [ "Streams" ], "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "Stream id, e.g. `vehicle:AB12XYZ`. URL-encode if needed.", "schema": { "type": "string" }, "example": "vehicle:AB12XYZ" } ], "responses": { "200": { "description": "Stream history", "content": { "application\/json": { "schema": { "type": "object", "properties": { "stream": { "type": "string" }, "version": { "type": "integer" }, "events": { "type": "array", "items": {} }, "cache": { "type": "object", "properties": { "cold": { "type": "boolean" }, "cold_count": { "type": "integer" }, "hot_count": { "type": "integer" } }, "required": [ "cold", "cold_count", "hot_count" ] } }, "required": [ "stream", "version", "events", "cache" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteStream", "description": "Permanently delete a stream and **all events** belonging to it. This cannot be undone. Webhook delivery rows for those events are removed via cascade.", "summary": "Delete a stream", "tags": [ "Streams" ], "parameters": [ { "name": "stream", "in": "path", "required": true, "description": "Stream id, e.g. `vehicle:AB12XYZ`. URL-encode if needed.", "schema": { "type": "string" }, "example": "vehicle:AB12XYZ" } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhooks": { "get": { "operationId": "listWebhooks", "description": "Return webhook endpoints for this project. Signing secrets are not included.", "summary": "List webhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook list", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_on_failure": { "type": "boolean" }, "notify_on_success": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "secret": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "event_types", "enabled", "notify_on_failure", "notify_on_success", "created_at", "updated_at", "secret" ] } } }, "required": [ "data" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createWebhook", "description": "Register an HTTPS endpoint. The signing `secret` is returned **once** in the create response.", "summary": "Create a webhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS endpoint URL.", "examples": [ "https:\/\/example.com\/hooks\/captur" ] }, "description": { "type": "string", "description": "Optional label." }, "event_types": { "type": "array", "description": "Filter to these types, or `[\"*\"]` for all. Defaults to all registered types when omitted.", "items": {} }, "enabled": { "type": "boolean", "description": "Whether deliveries are active (default true).", "examples": [ true ] }, "notify_on_failure": { "type": "boolean", "description": "Email on delivery failure (default true)." }, "notify_on_success": { "type": "boolean", "description": "Email on delivery success (default false)." } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_on_failure": { "type": "boolean" }, "notify_on_success": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "secret": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "event_types", "enabled", "notify_on_failure", "notify_on_success", "created_at", "updated_at", "secret" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhooks\/test-inbox": { "get": { "operationId": "getWebhookTestInbox", "description": "Return the project\u2019s email test inbox URL if configured.", "summary": "Retrieve email test inbox", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Test inbox", "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "url": { "type": "string" }, "webhook_endpoint_id": { "type": [ "integer", "null" ] }, "last_received_at": { "type": [ "string", "null" ] }, "emails_sent_today": { "type": "integer" }, "secret": { "type": [ "string", "null" ] } }, "required": [ "email", "url", "webhook_endpoint_id", "last_received_at", "emails_sent_today", "secret" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "upsertWebhookTestInbox", "description": "Mint a captur-hosted webhook URL that emails signed payloads to the given address. Also registers a webhook endpoint on the project pointing at that URL. The signing secret is returned.", "summary": "Create or rotate email test inbox", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Test inbox", "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "url": { "type": "string" }, "webhook_endpoint_id": { "type": [ "integer", "null" ] }, "last_received_at": { "type": [ "string", "null" ] }, "emails_sent_today": { "type": "integer" }, "secret": { "type": [ "string", "null" ] } }, "required": [ "email", "url", "webhook_endpoint_id", "last_received_at", "emails_sent_today", "secret" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteWebhookTestInbox", "description": "Remove the test inbox and its linked webhook endpoint.", "summary": "Delete email test inbox", "tags": [ "Webhooks" ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhooks\/test-inbox\/sample": { "post": { "operationId": "sendWebhookTestInboxSample", "description": "Send a sample signed payload to the configured test inbox email.", "summary": "Email a sample test webhook", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Sample queued", "content": { "application\/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "email": { "type": "string" } }, "required": [ "ok", "email" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/webhooks\/{webhook}": { "get": { "operationId": "getWebhook", "description": "Fetch a webhook endpoint by id. The signing secret is not returned.", "summary": "Retrieve a webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Webhook", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_on_failure": { "type": "boolean" }, "notify_on_success": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "secret": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "event_types", "enabled", "notify_on_failure", "notify_on_success", "created_at", "updated_at", "secret" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateWebhook", "description": "Update URL, filters, enabled flag, or notification preferences.", "summary": "Update a webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "enabled": { "type": "boolean" }, "notify_on_failure": { "type": "boolean" }, "notify_on_success": { "type": "boolean" }, "event_types": { "type": [ "array", "null" ], "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_on_failure": { "type": "boolean" }, "notify_on_success": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "secret": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "event_types", "enabled", "notify_on_failure", "notify_on_success", "created_at", "updated_at", "secret" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteWebhook", "description": "Remove a webhook endpoint. Delivery history for that endpoint is removed via cascade.", "summary": "Delete a webhook", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include webhooks.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/reports\/sessions": { "get": { "operationId": "sessionReport", "description": "Pair **start** and **end** event types per entity over a time window and return intervals + totals.\n\nUse this for timesheets (`employee.logged_in` \u2192 `employee.logged_out`), parking dwell, machine runtime, ticket SLA,\netc. \u2014 the API is domain-agnostic; you only supply the two type names.\n\n**Required:** `start_type`, `end_type`, `from`, `to` (max 31 days).\n\n**Grouping:** `group_by=stream` (default) or `subject_id`.\n\n**Open sessions:** `open=exclude` (default), `include`, or `only`.\n\nPaginate **groups** with `page` + `limit` (default 50, max 200).", "summary": "Session report", "tags": [ "Reports" ], "parameters": [ { "name": "start_type", "in": "query", "required": true, "description": "Entry \/ clock-in event type.", "schema": { "type": "string" }, "example": "employee.logged_in" }, { "name": "end_type", "in": "query", "required": true, "description": "Exit \/ clock-out event type.", "schema": { "type": "string" }, "example": "employee.logged_out" }, { "name": "from", "in": "query", "required": true, "description": "Window start (ISO-8601, `occurred_at`).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "description": "Window end (ISO-8601, `occurred_at`). Max 31 days after `from`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "group_by", "in": "query", "description": "`stream` (default) or `subject_id`.", "schema": { "type": "string" }, "example": "stream" }, { "name": "stream", "in": "query", "description": "Optional single stream filter.", "schema": { "type": "string" }, "example": "employee:4821" }, { "name": "subject_id", "in": "query", "description": "Optional single subject filter.", "schema": { "type": "string" } }, { "name": "open", "in": "query", "description": "`exclude` (default), `include`, or `only` unmatched starts.", "schema": { "type": "string" }, "example": "exclude" }, { "name": "limit", "in": "query", "description": "Groups per page (1\u2013200, default 50).", "schema": { "type": "integer" }, "example": 50 }, { "name": "page", "in": "query", "description": "1-based page of groups.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Session report page", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "start_type": { "type": "string" }, "end_type": { "type": "string" }, "group_by": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "open": { "type": "string" }, "events_scanned": { "type": "integer", "minimum": 0 }, "orphan_ends": { "type": "integer" }, "current_page": { "type": [ "object", "null" ] }, "last_page": { "type": [ "object", "null" ] }, "per_page": { "type": [ "object", "null" ] }, "total_groups": { "type": "integer" } }, "required": [ "start_type", "end_type", "group_by", "from", "to", "open", "events_scanned", "orphan_ends", "current_page", "last_page", "per_page", "total_groups" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Validation error (missing params, window too large, unknown type, scan limit)", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Feature-gated endpoints may also return `feature_not_available`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/alerts": { "get": { "operationId": "listAlerts", "description": "Return alert rules for this project (email, Slack, SMS). Available on Growth+.", "summary": "List alerts", "tags": [ "Alerts" ], "responses": { "200": { "description": "Alert list", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "notify_slack": { "type": "boolean" }, "notify_sms": { "type": "boolean" }, "email_recipients": { "type": "array", "items": {} }, "sms_recipients": { "type": "array", "items": {} }, "email_subject": { "type": [ "string", "null" ] }, "email_body": { "type": [ "string", "null" ] }, "slack_webhook_url": { "type": [ "string", "null" ] }, "slack_message": { "type": [ "string", "null" ] }, "sms_message": { "type": [ "string", "null" ] }, "throttle_seconds": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "event_types", "enabled", "notify_email", "notify_slack", "notify_sms", "email_recipients", "sms_recipients", "email_subject", "email_body", "slack_webhook_url", "slack_message", "sms_message", "throttle_seconds", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include alerts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createAlert", "description": "Create an alert rule. Enable at least one channel (email, Slack, or SMS).", "summary": "Create an alert", "tags": [ "Alerts" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Alert name.", "examples": [ "Gate opened" ] }, "event_types": { "type": "array", "description": "Matching event types, or `[\"*\"]`.", "items": {} }, "enabled": { "type": "boolean", "description": "Whether the alert is active (default true)." }, "notify_email": { "type": "boolean", "description": "Send email notifications.", "examples": [ true ] }, "notify_slack": { "type": "boolean", "description": "Send Slack notifications.", "examples": [ false ] }, "notify_sms": { "type": "boolean", "description": "Send SMS notifications.", "examples": [ false ] }, "email_recipients": { "type": "array", "description": "Email addresses (required when email is enabled if you override defaults).", "items": {} }, "email_subject": { "type": "string", "description": "Optional email subject template." }, "email_body": { "type": "string", "description": "Optional email body template." }, "slack_webhook_url": { "type": "string", "description": "Incoming Slack webhook URL (required when Slack is enabled)." }, "slack_message": { "type": "string", "description": "Optional Slack message template." }, "sms_recipients": { "type": "array", "description": "E.164 phone numbers (required when SMS is enabled).", "items": {} }, "sms_message": { "type": "string", "description": "Optional SMS body template." }, "throttle_seconds": { "type": "integer", "description": "Minimum seconds between firings (0\u201386400).", "examples": [ 300 ] } }, "required": [ "name", "notify_email", "notify_slack", "notify_sms" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "notify_slack": { "type": "boolean" }, "notify_sms": { "type": "boolean" }, "email_recipients": { "type": "array", "items": {} }, "sms_recipients": { "type": "array", "items": {} }, "email_subject": { "type": [ "string", "null" ] }, "email_body": { "type": [ "string", "null" ] }, "slack_webhook_url": { "type": [ "string", "null" ] }, "slack_message": { "type": [ "string", "null" ] }, "sms_message": { "type": [ "string", "null" ] }, "throttle_seconds": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "event_types", "enabled", "notify_email", "notify_slack", "notify_sms", "email_recipients", "sms_recipients", "email_subject", "email_body", "slack_webhook_url", "slack_message", "sms_message", "throttle_seconds", "created_at", "updated_at" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include alerts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/alerts\/{alert}": { "get": { "operationId": "getAlert", "description": "Fetch a single alert rule by id.", "summary": "Retrieve an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Alert", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "notify_slack": { "type": "boolean" }, "notify_sms": { "type": "boolean" }, "email_recipients": { "type": "array", "items": {} }, "sms_recipients": { "type": "array", "items": {} }, "email_subject": { "type": [ "string", "null" ] }, "email_body": { "type": [ "string", "null" ] }, "slack_webhook_url": { "type": [ "string", "null" ] }, "slack_message": { "type": [ "string", "null" ] }, "sms_message": { "type": [ "string", "null" ] }, "throttle_seconds": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "event_types", "enabled", "notify_email", "notify_slack", "notify_sms", "email_recipients", "sms_recipients", "email_subject", "email_body", "slack_webhook_url", "slack_message", "sms_message", "throttle_seconds", "created_at", "updated_at" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include alerts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "put": { "operationId": "updateAlert", "description": "Replace an alert rule. Send the full configuration body.", "summary": "Update an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert id.", "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Alert name." }, "event_types": { "type": "array", "description": "Matching event types, or `[\"*\"]`.", "items": {} }, "enabled": { "type": "boolean", "description": "Whether the alert is active." }, "notify_email": { "type": "boolean", "description": "Send email notifications." }, "notify_slack": { "type": "boolean", "description": "Send Slack notifications." }, "notify_sms": { "type": "boolean", "description": "Send SMS notifications." }, "email_recipients": { "type": "array", "description": "Email addresses.", "items": {} }, "email_subject": { "type": "string", "description": "Optional email subject template." }, "email_body": { "type": "string", "description": "Optional email body template." }, "slack_webhook_url": { "type": "string", "description": "Incoming Slack webhook URL when Slack is enabled." }, "slack_message": { "type": "string", "description": "Optional Slack message template." }, "sms_recipients": { "type": "array", "description": "E.164 phone numbers when SMS is enabled.", "items": {} }, "sms_message": { "type": "string", "description": "Optional SMS body template." }, "throttle_seconds": { "type": "integer", "description": "Minimum seconds between firings (0\u201386400)." } }, "required": [ "name", "notify_email", "notify_slack", "notify_sms" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "event_types": { "type": "array", "items": {} }, "enabled": { "type": "boolean" }, "notify_email": { "type": "boolean" }, "notify_slack": { "type": "boolean" }, "notify_sms": { "type": "boolean" }, "email_recipients": { "type": "array", "items": {} }, "sms_recipients": { "type": "array", "items": {} }, "email_subject": { "type": [ "string", "null" ] }, "email_body": { "type": [ "string", "null" ] }, "slack_webhook_url": { "type": [ "string", "null" ] }, "slack_message": { "type": [ "string", "null" ] }, "sms_message": { "type": [ "string", "null" ] }, "throttle_seconds": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "event_types", "enabled", "notify_email", "notify_slack", "notify_sms", "email_recipients", "sms_recipients", "email_subject", "email_body", "slack_webhook_url", "slack_message", "sms_message", "throttle_seconds", "created_at", "updated_at" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include alerts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteAlert", "description": "Remove an alert rule.", "summary": "Delete an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include alerts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/projections": { "get": { "operationId": "listProjections", "description": "Return derived read models for this project. Available on Growth+.", "summary": "List projections", "tags": [ "Projections" ], "responses": { "200": { "description": "Projection list", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "checkpoint": { "type": "integer" }, "state": { "type": [ "array", "null" ], "items": {} }, "last_error": { "type": [ "string", "null" ] }, "replayed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "checkpoint", "state", "last_error", "replayed_at", "created_at", "updated_at" ] } } }, "required": [ "data" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createProjection", "description": "Create a projection definition. Replay after create to populate state from history.", "summary": "Create a projection", "tags": [ "Projections" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "slug": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "checkpoint": { "type": "integer" }, "state": { "type": [ "array", "null" ], "items": {} }, "last_error": { "type": [ "string", "null" ] }, "replayed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "checkpoint", "state", "last_error", "replayed_at", "created_at", "updated_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/projections\/{projection}": { "get": { "operationId": "getProjection", "description": "Fetch a projection by id, including current state and checkpoint.", "summary": "Retrieve a projection", "tags": [ "Projections" ], "parameters": [ { "name": "projection", "in": "path", "required": true, "description": "Projection id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Projection", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "checkpoint": { "type": "integer" }, "state": { "type": [ "array", "null" ], "items": {} }, "last_error": { "type": [ "string", "null" ] }, "replayed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "checkpoint", "state", "last_error", "replayed_at", "created_at", "updated_at" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateProjection", "description": "Rename a projection. The slug cannot change after create.", "summary": "Update a projection", "tags": [ "Projections" ], "parameters": [ { "name": "projection", "in": "path", "required": true, "description": "Projection id.", "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "checkpoint": { "type": "integer" }, "state": { "type": [ "array", "null" ], "items": {} }, "last_error": { "type": [ "string", "null" ] }, "replayed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "checkpoint", "state", "last_error", "replayed_at", "created_at", "updated_at" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteProjection", "description": "Remove a projection definition and its derived state.", "summary": "Delete a projection", "tags": [ "Projections" ], "parameters": [ { "name": "projection", "in": "path", "required": true, "description": "Projection id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "204": { "description": "Deleted", "content": { "application\/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "\/projections\/{projection}\/replay": { "post": { "operationId": "replayProjection", "description": "Rebuild projection state from the full event history. Requires Growth+ with replay.", "summary": "Replay a projection", "tags": [ "Projections" ], "parameters": [ { "name": "projection", "in": "path", "required": true, "description": "Projection id.", "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Replayed projection", "content": { "application\/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "checkpoint": { "type": "integer" }, "state": { "type": [ "array", "null" ], "items": {} }, "last_error": { "type": [ "string", "null" ] }, "replayed_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "checkpoint", "state", "last_error", "replayed_at", "created_at", "updated_at" ] } } } }, "403": { "description": "Forbidden \u2014 workspace IP\/origin allowlist denied the request (`api_access_denied`). Origin\/domain rules apply only when `Origin` or `Referer` is present. Also: Plan does not include projections or replay.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "forbidden", "code": "api_access_denied", "message": "Request IP is not on this workspace API allowlist.", "parameter": "ip", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized \u2014 missing, invalid, or revoked project API key (`missing_api_key` \/ `invalid_api_key`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key.", "documentation_url": "https:\/\/captur.events\/docs\/authentication" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests \u2014 per-key request throttle (`rate_limit_exceeded`) with `Retry-After` \/ `X-RateLimit-*` headers.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "examples": [ { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down or upgrade your plan for a higher API rate limit.", "documentation_url": "https:\/\/captur.events\/docs\/rate-limits" } ], "properties": { "type": { "type": "string", "description": "Error category, e.g. `authentication_error`." }, "code": { "type": "string", "description": "Machine-readable code, e.g. `invalid_api_key`." }, "message": { "type": "string", "description": "Human-readable explanation." }, "parameter": { "type": [ "string", "null" ], "description": "Optional field or constraint that failed (`ip`, `origin`, \u2026)." }, "documentation_url": { "type": [ "string", "null" ], "description": "Optional docs link." } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Project API key: `evt_test_\u2026` or `evt_live_\u2026`", "scheme": "bearer", "bearerFormat": "API key" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }