{ "openapi": "3.1.0", "info": { "title": "Orishare API", "version": "v1", "description": "Loyalty, incentives, promotions and engagement infrastructure. Customers integrate once, send events, and versioned rules award points, move tiers, issue rewards, progress challenges and emit webhooks. Conventions: JSON snake_case; RFC 3339 UTC timestamps; cursor pagination (`limit`, `cursor`, `next_cursor`, `has_more`); one error shape with stable `code` values (see `x-error-codes`); `Idempotency-Key` required on creating POSTs; `ETag` / `If-Match` for safe edits; management tokens (`opat_`) name an environment with `X-Orishare-Environment`; secret keys (`osk_`) are bound to one environment; publishable keys (`opk_`) may only send allowed client events.", "contact": { "name": "Orishare", "url": "https://docs.orishare.com" } }, "servers": [ { "url": "https://api.orishare.com/v1" } ], "tags": [ { "name": "account", "description": "Signup, tokens, invitations, memberships and ownership for people and agents." }, { "name": "management", "description": "Organizations, projects, environments, API keys and usage." }, { "name": "events", "description": "Ingestion (202 async, 200 sync), event definitions, retries." }, { "name": "customers", "description": "Customers, aliases, attributes and the aggregated state view." }, { "name": "ledger", "description": "Currencies, manual adjustments, entries and balances." }, { "name": "rules", "description": "Rules, immutable versions, publish, pause, simulate." }, { "name": "campaigns", "description": "Schedules, priorities, stacking groups, budgets, audiences." }, { "name": "tiers", "description": "Tier programs, levels and per-customer tiers." }, { "name": "rewards", "description": "Rewards, issuances, redemption and cancellation." }, { "name": "challenges", "description": "Challenges, enrollment and progress." }, { "name": "segments", "description": "Static membership and live dynamic segments." }, { "name": "counters", "description": "Historical counter definitions and backfills." }, { "name": "webhooks", "description": "Endpoints, signed deliveries, replay." }, { "name": "audit", "description": "Audit trail." }, { "name": "context", "description": "Project context for AI drafting and the UI." }, { "name": "config", "description": "Whole-environment export and atomic apply." }, { "name": "ai", "description": "AI drafting: plain-English requests become validated rule documents for review; never published by the model." }, { "name": "support", "description": "Audited staff access." } ], "x-error-codes": { "validation_failed": { "status": 400, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#validation_failed" }, "invalid_cursor": { "status": 400, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#invalid_cursor" }, "invalid_json": { "status": 400, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#invalid_json" }, "body_too_large": { "status": 413, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#body_too_large" }, "event_too_large": { "status": 413, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#event_too_large" }, "batch_too_large": { "status": 400, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#batch_too_large" }, "occurred_at_in_future": { "status": 400, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#occurred_at_in_future" }, "unsupported_media_type": { "status": 415, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#unsupported_media_type" }, "authentication_required": { "status": 401, "type": "authentication", "doc_url": "https://docs.orishare.com/errors#authentication_required" }, "invalid_credentials": { "status": 401, "type": "authentication", "doc_url": "https://docs.orishare.com/errors#invalid_credentials" }, "credentials_revoked": { "status": 401, "type": "authentication", "doc_url": "https://docs.orishare.com/errors#credentials_revoked" }, "environment_required": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#environment_required" }, "insufficient_scope": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#insufficient_scope" }, "event_requires_secret_key": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#event_requires_secret_key" }, "origin_not_allowed": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#origin_not_allowed" }, "audit_reason_required": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#audit_reason_required" }, "forbidden": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#forbidden" }, "route_not_found": { "status": 404, "type": "not_found", "doc_url": "https://docs.orishare.com/errors#route_not_found" }, "resource_not_found": { "status": 404, "type": "not_found", "doc_url": "https://docs.orishare.com/errors#resource_not_found" }, "stale_write": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#stale_write" }, "resource_in_use": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#resource_in_use" }, "already_exists": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#already_exists" }, "event_id_conflict": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#event_id_conflict" }, "alias_conflict": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#alias_conflict" }, "invalid_state": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#invalid_state" }, "insufficient_balance": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#insufficient_balance" }, "reward_unavailable": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#reward_unavailable" }, "last_owner": { "status": 409, "type": "conflict", "doc_url": "https://docs.orishare.com/errors#last_owner" }, "rule_invalid": { "status": 422, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#rule_invalid" }, "idempotency_key_required": { "status": 400, "type": "idempotency", "doc_url": "https://docs.orishare.com/errors#idempotency_key_required" }, "idempotency_key_reused": { "status": 422, "type": "idempotency", "doc_url": "https://docs.orishare.com/errors#idempotency_key_reused" }, "idempotency_in_progress": { "status": 409, "type": "idempotency", "doc_url": "https://docs.orishare.com/errors#idempotency_in_progress" }, "rate_limited": { "status": 429, "type": "rate_limited", "doc_url": "https://docs.orishare.com/errors#rate_limited" }, "quota_exceeded": { "status": 429, "type": "rate_limited", "doc_url": "https://docs.orishare.com/errors#quota_exceeded" }, "ai_drafting_disabled": { "status": 403, "type": "permission", "doc_url": "https://docs.orishare.com/errors#ai_drafting_disabled" }, "ai_draft_rejected": { "status": 422, "type": "invalid_request", "doc_url": "https://docs.orishare.com/errors#ai_draft_rejected" }, "ai_unavailable": { "status": 503, "type": "api_error", "doc_url": "https://docs.orishare.com/errors#ai_unavailable" }, "evaluation_failed": { "status": 502, "type": "api_error", "doc_url": "https://docs.orishare.com/errors#evaluation_failed" }, "internal_error": { "status": 500, "type": "api_error", "doc_url": "https://docs.orishare.com/errors#internal_error" } }, "paths": { "/auth/signup": { "post": { "summary": "Create a user, an organization with a default project and two environments, and a first token", "tags": [ "account" ], "operationId": "post_auth_signup", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "email": "dev@example.com", "organization_name": "Acme Audiobooks", "timezone": "America/New_York" }, "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "organization_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timezone": { "default": "UTC", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "email", "organization_name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "email", "name", "created_at" ], "additionalProperties": false }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string" } }, "required": [ "id", "name", "runtime_class" ], "additionalProperties": false } }, "token": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "token", "scopes" ], "additionalProperties": false } }, "required": [ "user", "organization", "project", "environments", "token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/sessions": { "post": { "summary": "Exchange a verified Identity Platform ID token for a 30-day session; the user is created on first sign-in, organizations come from POST /organizations or an invitation", "tags": [ "account" ], "operationId": "post_auth_sessions", "requestBody": { "content": { "application/json": { "example": { "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ij…" }, "schema": { "type": "object", "properties": { "id_token": { "type": "string", "minLength": 20, "maxLength": 8192 } }, "required": [ "id_token" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "email", "name", "created_at" ], "additionalProperties": false }, "created": { "type": "boolean" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false } }, "token": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string" } }, "required": [ "id", "token", "scopes", "expires_at" ], "additionalProperties": false } }, "required": [ "user", "created", "memberships", "token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations": { "post": { "summary": "Create another organization owned by the caller, with a default project and two environments", "tags": [ "account" ], "operationId": "post_organizations", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Acme Audiobooks", "timezone": "Europe/Amsterdam" }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timezone": { "default": "UTC", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string" } }, "required": [ "id", "name", "runtime_class" ], "additionalProperties": false } } }, "required": [ "organization", "project", "environments" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Organizations the caller belongs to", "tags": [ "management" ], "operationId": "get_organizations", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" } }, "required": [ "id", "version" ], "additionalProperties": false }, "billing_mode": { "type": "string", "enum": [ "card", "invoice", "none" ] }, "ai_drafting_disabled": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "slug", "plan", "billing_mode", "ai_drafting_disabled", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/users/me": { "get": { "summary": "The caller and their memberships", "tags": [ "account" ], "operationId": "get_users_me", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "email", "name", "created_at", "memberships" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/tokens": { "post": { "summary": "Issue a personal access token with scopes", "tags": [ "account" ], "operationId": "post_auth_tokens", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopes": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[a-z_]+:[a-z_*]+$|^\\*$" } }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "name", "scopes" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "name", "prefix", "scopes", "expires_at", "last_used_at", "created_at", "token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List the caller's tokens", "tags": [ "account" ], "operationId": "get_auth_tokens", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "scopes", "expires_at", "last_used_at", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/tokens/{id}": { "delete": { "summary": "Revoke a token (the current one included)", "tags": [ "account" ], "operationId": "delete_auth_tokens_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/invitations": { "post": { "summary": "Invite a user by email with a role", "tags": [ "account" ], "operationId": "post_organizations_id_invitations", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] } }, "required": [ "email", "role" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "expires_at": { "type": "string" }, "accepted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "organization_id", "email", "role", "expires_at", "accepted_at", "created_at", "token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/invitations/{id}/accept": { "post": { "summary": "Accept an invitation with its token; creates the user when needed and returns a first token (existing users sign in instead)", "tags": [ "account" ], "operationId": "post_invitations_id_accept", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "email", "name", "created_at" ], "additionalProperties": false }, "membership": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false }, "token": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "token", "scopes" ], "additionalProperties": false }, { "type": "null" } ], "description": "A first token when the user was just created; null for an existing user" } }, "required": [ "user", "membership", "token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/memberships": { "get": { "summary": "List members", "tags": [ "account" ], "operationId": "get_organizations_id_memberships", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/memberships/{user_id}": { "patch": { "summary": "Change a member's role", "tags": [ "account" ], "operationId": "patch_organizations_id_memberships_user_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "user_id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a member (never the last owner)", "tags": [ "account" ], "operationId": "delete_organizations_id_memberships_user_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "user_id", "schema": { "type": "string" }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/transfer_ownership": { "post": { "summary": "Transfer ownership to another member; the caller becomes admin", "tags": [ "account" ], "operationId": "post_organizations_id_transfer_ownership", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1 } }, "required": [ "user_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false }, "previous_owner": { "type": "object", "properties": { "organization_id": { "type": "string" }, "user_id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string" } }, "required": [ "organization_id", "user_id", "email", "role", "created_at" ], "additionalProperties": false } }, "required": [ "owner", "previous_owner" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}": { "get": { "summary": "One organization", "tags": [ "management" ], "operationId": "get_organizations_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" } }, "required": [ "id", "version" ], "additionalProperties": false }, "billing_mode": { "type": "string", "enum": [ "card", "invoice", "none" ] }, "ai_drafting_disabled": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "slug", "plan", "billing_mode", "ai_drafting_disabled", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename an organization or flip the AI drafting kill switch (If-Match for safe edits)", "tags": [ "management" ], "operationId": "patch_organizations_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "ai_drafting_disabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" } }, "required": [ "id", "version" ], "additionalProperties": false }, "billing_mode": { "type": "string", "enum": [ "card", "invoice", "none" ] }, "ai_drafting_disabled": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "slug", "plan", "billing_mode", "ai_drafting_disabled", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "summary": "Projects of an organization", "tags": [ "management" ], "operationId": "get_projects", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "organization_id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "slug", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a project with a sandbox and a production environment", "tags": [ "management" ], "operationId": "post_projects", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "timezone": { "default": "UTC", "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "organization_id", "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "slug", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}": { "get": { "summary": "One project", "tags": [ "management" ], "operationId": "get_projects_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "slug", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename a project", "tags": [ "management" ], "operationId": "patch_projects_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "ai_drafting_disabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "organization_id", "name", "slug", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/environments": { "get": { "summary": "Environments of a project", "tags": [ "management" ], "operationId": "get_projects_id_environments", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string", "enum": [ "sandbox", "production" ] }, "timezone": { "type": "string" }, "rules_paused": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "runtime_class", "timezone", "rules_paused", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}": { "get": { "summary": "One environment", "tags": [ "management" ], "operationId": "get_environments_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string", "enum": [ "sandbox", "production" ] }, "timezone": { "type": "string" }, "rules_paused": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "runtime_class", "timezone", "rules_paused", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update name, timezone, or the rules kill switch", "tags": [ "management" ], "operationId": "patch_environments_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "rules_paused": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string", "enum": [ "sandbox", "production" ] }, "timezone": { "type": "string" }, "rules_paused": { "type": "boolean" }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "runtime_class", "timezone", "rules_paused", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/api_keys": { "post": { "summary": "Create a secret or publishable key; the token is returned once", "tags": [ "management" ], "operationId": "post_environments_id_api_keys", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "secret", "publishable" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopes": { "maxItems": 50, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "publishable" ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "token": { "type": "string" }, "organization_id": { "type": "string" } }, "required": [ "id", "environment_id", "kind", "name", "prefix", "scopes", "last_used_at", "revoked_at", "created_at", "token", "organization_id" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List keys (hashes never returned)", "tags": [ "management" ], "operationId": "get_environments_id_api_keys", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "secret", "publishable" ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "environment_id", "kind", "name", "prefix", "scopes", "last_used_at", "revoked_at", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api_keys/{id}": { "delete": { "summary": "Revoke a key", "tags": [ "management" ], "operationId": "delete_api_keys_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/environments/{id}/usage": { "get": { "summary": "Metered usage per calendar month", "tags": [ "management" ], "operationId": "get_environments_id_usage", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "period", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "environment_id": { "type": "string" }, "period": { "type": "string" }, "accepted_events": { "type": "number" }, "active_customers": { "type": "number" }, "webhook_deliveries": { "type": "number" }, "ai_drafts": { "type": "number" }, "sync_evaluations": { "type": "number" } }, "required": [ "environment_id", "period", "accepted_events", "active_customers", "webhook_deliveries", "ai_drafts", "sync_evaluations" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "post": { "summary": "Send one event or a batch; async by default, `mode: sync` evaluates inline (secret keys)", "tags": [ "events" ], "operationId": "post_events", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "example": { "name": "content.purchased", "customer_id": "cust_123", "mode": "sync", "properties": { "content_id": "book_42", "price_cents": 1499 } }, "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "occurred_at": { "type": "string", "maxLength": 40 }, "customer_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "anonymous_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "customer_token": { "type": "string", "maxLength": 200 }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "mode": { "default": "async", "type": "string", "enum": [ "async", "sync" ] } }, "required": [ "name" ] }, { "type": "object", "properties": { "events": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "occurred_at": { "type": "string", "maxLength": 40 }, "customer_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "anonymous_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "customer_token": { "type": "string", "maxLength": 200 }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "name" ] } }, "mode": { "default": "async", "type": "string", "enum": [ "async", "sync" ] } }, "required": [ "events" ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "index", "status" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "index", "status" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } ] } } } }, "207": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "status": { "type": "string", "enum": [ "accepted", "evaluated", "duplicate", "rejected" ] }, "id": { "type": "string" }, "customer_id": { "type": "string" }, "late": { "type": "boolean" }, "fallback": { "type": "boolean" }, "execution_id": { "type": [ "string", "null" ] }, "effects": { "type": "array", "items": {} }, "trace": {}, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "index", "status" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List events (newest first)", "tags": [ "events" ], "operationId": "get_events", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "in": "query", "name": "name", "schema": { "type": "string" } }, { "in": "query", "name": "since", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "client_event_id": { "type": "string" }, "name": { "type": "string" }, "customer_id": { "type": "string" }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "mode": { "type": "string", "enum": [ "async", "sync" ] }, "late": { "type": "boolean" }, "status": { "type": "string", "enum": [ "accepted", "evaluated", "failed", "poison", "redacted" ] }, "execution_id": { "type": [ "string", "null" ] } }, "required": [ "id", "client_event_id", "name", "customer_id", "occurred_at", "received_at", "properties", "mode", "late", "status", "execution_id" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/{id}": { "get": { "summary": "One event with its evaluation status", "tags": [ "events" ], "operationId": "get_events_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_event_id": { "type": "string" }, "name": { "type": "string" }, "customer_id": { "type": "string" }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "mode": { "type": "string", "enum": [ "async", "sync" ] }, "late": { "type": "boolean" }, "status": { "type": "string", "enum": [ "accepted", "evaluated", "failed", "poison", "redacted" ] }, "execution_id": { "type": [ "string", "null" ] } }, "required": [ "id", "client_event_id", "name", "customer_id", "occurred_at", "received_at", "properties", "mode", "late", "status", "execution_id" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/{id}/execution": { "get": { "summary": "Plan and trace of an evaluated event", "tags": [ "events" ], "operationId": "get_events_id_execution", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "customer_id": { "type": "string" }, "version_set": { "type": "string" }, "matched_rules": { "type": "number" }, "plan": { "type": "array", "items": {} }, "trace": {}, "created_at": { "type": "string" } }, "required": [ "id", "event_id", "customer_id", "version_set", "matched_rules", "plan", "trace", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/event_definitions": { "get": { "summary": "Observed event names with property types and samples", "tags": [ "events" ], "operationId": "get_event_definitions", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "observed_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "confirmed_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "samples": { "type": "array", "items": {} }, "event_count": { "type": "number" }, "client_allowed": { "type": "boolean" }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "observed_schema", "confirmed_schema", "description", "samples", "event_count", "client_allowed", "first_seen_at", "last_seen_at", "version", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/event_definitions/{id}": { "patch": { "summary": "Describe an event, confirm its schema, or allow it from publishable keys", "tags": [ "events" ], "operationId": "patch_event_definitions_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "client_allowed": { "type": "boolean" }, "confirmed_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "observed_schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "confirmed_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "samples": { "type": "array", "items": {} }, "event_count": { "type": "number" }, "client_allowed": { "type": "boolean" }, "first_seen_at": { "type": [ "string", "null" ] }, "last_seen_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "observed_schema", "confirmed_schema", "description", "samples", "event_count", "client_allowed", "first_seen_at", "last_seen_at", "version", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers": { "post": { "summary": "Create or update a customer by external id (201 created, 200 updated)", "tags": [ "customers" ], "operationId": "post_customers", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "external_id": "cust_123", "attributes": { "plan": "premium", "country": "US" } }, "schema": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "anonymous_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "external_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List customers (newest first)", "tags": [ "customers" ], "operationId": "get_customers", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "external_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}": { "get": { "summary": "One customer by id or external id", "tags": [ "customers" ], "operationId": "get_customers_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Merge-patch attributes (null removes a key)", "tags": [ "customers" ], "operationId": "patch_customers_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "attributes" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete: redact attributes and events, remove aliases, keep ledger history", "tags": [ "customers" ], "operationId": "delete_customers_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/export": { "get": { "summary": "Data export: profile, aliases, events in the hot window, ledger entries, issuances, tiers and challenge progress as one document", "tags": [ "customers" ], "operationId": "get_customers_id_export", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "exported_at": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "alias", "created_at" ], "additionalProperties": false } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "occurred_at": { "type": "string" }, "received_at": { "type": "string" }, "properties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "id", "name", "occurred_at", "received_at", "properties" ], "additionalProperties": false } }, "events_since": { "type": "string" }, "ledger_entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "remaining": { "type": "number" }, "expires_at": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "currency", "type", "status", "amount", "remaining", "expires_at", "reason", "source_type", "created_at" ], "additionalProperties": false } }, "reward_issuances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reward": { "type": "string" }, "status": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "reward", "status", "expires_at", "redeemed_at", "cancelled_at", "created_at" ], "additionalProperties": false } }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "program": { "type": "string" }, "level": { "type": "string" }, "since": { "type": "string" } }, "required": [ "program", "level", "since" ], "additionalProperties": false } }, "challenge_progress": { "type": "array", "items": { "type": "object", "properties": { "challenge": { "type": "string" }, "period_key": { "type": "string" }, "count": { "type": "number" }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "challenge", "period_key", "count", "completed_at" ], "additionalProperties": false } } }, "required": [ "exported_at", "customer", "aliases", "events", "events_since", "ledger_entries", "reward_issuances", "tiers", "challenge_progress" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/state": { "get": { "summary": "Balances, tiers, segments, counters, challenge progress, issuances and aliases", "tags": [ "customers" ], "operationId": "get_customers_id_state", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "deleted_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "external_id", "attributes", "version", "deleted_at", "created_at", "updated_at" ], "additionalProperties": false }, "balances": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "available": { "type": "number" }, "pending": { "type": "number" }, "lifetime_earned": { "type": "number" } }, "required": [ "currency", "available", "pending", "lifetime_earned" ], "additionalProperties": false } }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "program_id": { "type": "string" }, "level": { "type": "string" }, "since": { "type": "string" } }, "required": [ "program_id", "level", "since" ], "additionalProperties": false } }, "segments": { "type": "array", "items": { "type": "string" } }, "counters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "challenges": { "type": "array", "items": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "period_key": { "type": "string" }, "count": { "type": "number" }, "status": { "type": "string" } }, "required": [ "challenge_id", "period_key", "count", "status" ], "additionalProperties": false } }, "issuances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "status": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "reward_id", "status", "expires_at" ], "additionalProperties": false } }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string" }, "kind": { "type": "string", "enum": [ "anonymous", "external" ] }, "customer_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "alias", "kind", "customer_id", "created_at" ], "additionalProperties": false } } }, "required": [ "customer", "balances", "tiers", "segments", "counters", "challenges", "issuances", "aliases" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/aliases": { "post": { "summary": "Identify: link an anonymous id to this customer", "tags": [ "customers" ], "operationId": "post_customers_id_aliases", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "alias": "anon_9f3a" }, "schema": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "alias" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "alias": { "type": "object", "properties": { "alias": { "type": "string" }, "kind": { "type": "string", "enum": [ "anonymous", "external" ] }, "customer_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "alias", "kind", "customer_id", "created_at" ], "additionalProperties": false }, "merged_from": { "type": [ "string", "null" ] } }, "required": [ "alias", "merged_from" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/client_token": { "post": { "summary": "Mint the token a browser must present to send events as this customer", "tags": [ "customers" ], "operationId": "post_customers_id_client_token", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "external_id": { "type": "string" }, "customer_token": { "type": "string" } }, "required": [ "customer_id", "external_id", "customer_token" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/attribute_definitions": { "get": { "summary": "Declared customer attributes with types and PII flags", "tags": [ "customers" ], "operationId": "get_attribute_definitions", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ] }, "description": { "type": [ "string", "null" ] }, "pii": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "type", "description", "pii", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Declare or update an attribute definition by key", "tags": [ "customers" ], "operationId": "post_attribute_definitions", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "pii": { "type": "boolean" } }, "required": [ "key", "type" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ] }, "description": { "type": [ "string", "null" ] }, "pii": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "type", "description", "pii", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/currencies": { "get": { "summary": "List currencies", "tags": [ "ledger" ], "operationId": "get_currencies", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "precision": { "type": "number" }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "precision", "expiration_policy", "negative_balance", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a currency", "tags": [ "ledger" ], "operationId": "post_currencies", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "precision": { "type": "integer", "minimum": 0, "maximum": 6 }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ] }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] } }, "required": [ "code", "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "precision": { "type": "number" }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "precision", "expiration_policy", "negative_balance", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/currencies/{id}": { "get": { "summary": "One currency by id or code", "tags": [ "ledger" ], "operationId": "get_currencies_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "precision": { "type": "number" }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "precision", "expiration_policy", "negative_balance", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename, change expiration policy or negative-balance policy", "tags": [ "ledger" ], "operationId": "patch_currencies_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ] }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "precision": { "type": "number" }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "code", "name", "precision", "expiration_policy", "negative_balance", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an unused currency (409 when referenced)", "tags": [ "ledger" ], "operationId": "delete_currencies_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ledger_entries": { "post": { "summary": "Manual adjustment (positive credits a lot, negative spends FIFO)", "tags": [ "ledger" ], "operationId": "post_ledger_entries", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "customer_id": "cust_123", "currency": "points", "amount": 500, "reason": "goodwill credit" }, "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expires_after_days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "customer_id", "currency", "amount", "reason" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "earn", "spend", "expire", "reverse", "adjust" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "voided" ] }, "amount": { "type": "number" }, "remaining": { "type": "number" }, "confirm_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "reversal_of": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "customer_id", "currency", "type", "status", "amount", "remaining", "confirm_at", "expires_at", "reversal_of", "source_type", "source_id", "idempotency_key", "reason", "created_at" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "earn", "spend", "expire", "reverse", "adjust" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "voided" ] }, "amount": { "type": "number" }, "remaining": { "type": "number" }, "confirm_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "reversal_of": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "customer_id", "currency", "type", "status", "amount", "remaining", "confirm_at", "expires_at", "reversal_of", "source_type", "source_id", "idempotency_key", "reason", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List entries (newest first)", "tags": [ "ledger" ], "operationId": "get_ledger_entries", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "in": "query", "name": "currency", "schema": { "type": "string" } }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "earn", "spend", "expire", "reverse", "adjust" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "earn", "spend", "expire", "reverse", "adjust" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "voided" ] }, "amount": { "type": "number" }, "remaining": { "type": "number" }, "confirm_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "reversal_of": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "customer_id", "currency", "type", "status", "amount", "remaining", "confirm_at", "expires_at", "reversal_of", "source_type", "source_id", "idempotency_key", "reason", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ledger_entries/{id}": { "get": { "summary": "One entry", "tags": [ "ledger" ], "operationId": "get_ledger_entries_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "earn", "spend", "expire", "reverse", "adjust" ] }, "status": { "type": "string", "enum": [ "pending", "confirmed", "voided" ] }, "amount": { "type": "number" }, "remaining": { "type": "number" }, "confirm_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "reversal_of": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": [ "string", "null" ] }, "idempotency_key": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "customer_id", "currency", "type", "status", "amount", "remaining", "confirm_at", "expires_at", "reversal_of", "source_type", "source_id", "idempotency_key", "reason", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/balances": { "get": { "summary": "Balances per currency", "tags": [ "ledger" ], "operationId": "get_customers_id_balances", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "customer_id": { "type": "string" }, "currency": { "type": "string" }, "available": { "type": "number" }, "pending": { "type": "number" }, "lifetime_earned": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "customer_id", "currency", "available", "pending", "lifetime_earned", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules": { "get": { "summary": "List rules", "tags": [ "rules" ], "operationId": "get_rules", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] } }, { "in": "query", "name": "campaign_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a draft rule (validated, not yet published)", "tags": [ "rules" ], "operationId": "post_rules", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Purchase earns points", "definition": { "schema": "orishare.rule/v1", "trigger": { "event": "content.purchased" }, "limits": [ { "id": "per_content", "scope": [ "customer", "event.properties.content_id" ], "max": 1 } ], "actions": [ { "type": "points.award", "currency": "points", "amount": 100 } ] } }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "campaign_id": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ai_generation_id": { "type": "string" } }, "required": [ "name", "definition" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}": { "get": { "summary": "One rule with its active version and draft", "tags": [ "rules" ], "operationId": "get_rules_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit the draft, name, priority or campaign", "tags": [ "rules" ], "operationId": "patch_rules_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "campaign_id": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/publish": { "post": { "summary": "Publish the draft as a new immutable version", "tags": [ "rules" ], "operationId": "post_rules_id_publish", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/pause": { "post": { "summary": "Pause a published rule", "tags": [ "rules" ], "operationId": "post_rules_id_pause", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/resume": { "post": { "summary": "Resume a paused rule", "tags": [ "rules" ], "operationId": "post_rules_id_resume", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/archive": { "post": { "summary": "Archive a rule (history stays readable)", "tags": [ "rules" ], "operationId": "post_rules_id_archive", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/versions": { "get": { "summary": "Immutable versions, newest first", "tags": [ "rules" ], "operationId": "get_rules_id_versions", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rule_id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "rule_id", "number", "definition", "created_by", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/rollback": { "post": { "summary": "Publish an older version's definition as a new version", "tags": [ "rules" ], "operationId": "post_rules_id_rollback", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "priority": { "type": "number" }, "active_version": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "number" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "created_at": { "type": "string" } }, "required": [ "id", "number", "definition", "created_at" ], "additionalProperties": false }, { "type": "null" } ] }, "draft_definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "campaign_id", "status", "priority", "active_version", "draft_definition", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rules/{id}/simulate": { "post": { "summary": "Evaluate this rule against a synthetic event without committing", "tags": [ "rules" ], "operationId": "post_rules_id_simulate", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "example": { "event": { "name": "content.purchased", "properties": { "content_id": "book_42" } }, "customer_id": "cust_123" }, "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "name" ] }, "customer_id": { "type": "string" }, "use": { "type": "string", "enum": [ "draft", "active" ] } }, "required": [ "event" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "simulated": { "type": "boolean", "const": true }, "plan": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "trace": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "simulated", "plan", "trace" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns": { "get": { "summary": "List campaigns", "tags": [ "campaigns" ], "operationId": "get_campaigns", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "number" }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "window": { "type": [ "string", "null" ] }, "used": { "type": "number" } }, "required": [ "amount", "currency", "window", "used" ], "additionalProperties": false }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ], "additionalProperties": false }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a campaign", "tags": [ "campaigns" ], "operationId": "post_campaigns", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Launch week", "status": "active", "priority": 10, "budget": { "amount": 100000, "currency": "points", "window": "none" } }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stacking_group": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] } }, "required": [ "amount", "currency" ] }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "segments" ] }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "number" }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "window": { "type": [ "string", "null" ] }, "used": { "type": "number" } }, "required": [ "amount", "currency", "window", "used" ], "additionalProperties": false }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ], "additionalProperties": false }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{id}": { "get": { "summary": "One campaign with budget usage", "tags": [ "campaigns" ], "operationId": "get_campaigns_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "number" }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "window": { "type": [ "string", "null" ] }, "used": { "type": "number" } }, "required": [ "amount", "currency", "window", "used" ], "additionalProperties": false }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ], "additionalProperties": false }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update schedule, priority, stacking, budget, audience or status", "tags": [ "campaigns" ], "operationId": "patch_campaigns_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stacking_group": { "anyOf": [ { "type": "string", "maxLength": 60 }, { "type": "null" } ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] } }, "required": [ "amount", "currency" ] }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "segments" ] }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "number" }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "window": { "type": [ "string", "null" ] }, "used": { "type": "number" } }, "required": [ "amount", "currency", "window", "used" ], "additionalProperties": false }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ], "additionalProperties": false }, { "type": "null" } ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a draft or ended campaign with no rules", "tags": [ "campaigns" ], "operationId": "delete_campaigns_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tier_programs": { "get": { "summary": "List tier programs with levels", "tags": [ "tiers" ], "operationId": "get_tier_programs", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ], "additionalProperties": false } ], "type": "object" }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "number" }, "rank": { "type": "number" } }, "required": [ "id", "name", "threshold", "rank" ], "additionalProperties": false } }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a tier program (first level threshold 0, increasing thresholds)", "tags": [ "tiers" ], "operationId": "post_tier_programs", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Listener status", "currency": "points", "basis": { "type": "lifetime_earned" }, "is_default": true, "levels": [ { "name": "bronze", "threshold": 0 }, { "name": "silver", "threshold": 500 }, { "name": "gold", "threshold": 2000 } ] }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "currency": { "type": "string", "minLength": 1 }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ] } ], "type": "object" }, "levels": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "threshold": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "threshold" ] } }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" } }, "required": [ "name", "currency", "basis", "levels" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ], "additionalProperties": false } ], "type": "object" }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "number" }, "rank": { "type": "number" } }, "required": [ "id", "name", "threshold", "rank" ], "additionalProperties": false } }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tier_programs/{id}": { "get": { "summary": "One tier program", "tags": [ "tiers" ], "operationId": "get_tier_programs_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ], "additionalProperties": false } ], "type": "object" }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "number" }, "rank": { "type": "number" } }, "required": [ "id", "name", "threshold", "rank" ], "additionalProperties": false } }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a program; removing a held level needs reassign_to, changing basis needs reevaluate", "tags": [ "tiers" ], "operationId": "patch_tier_programs_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ] } ], "type": "object" }, "levels": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "threshold": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "threshold" ] } }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "reassign_to": { "type": "string" }, "reevaluate": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "basis": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime_earned" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "earned_rolling_days" }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "balance" } }, "required": [ "type" ], "additionalProperties": false } ], "type": "object" }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "threshold": { "type": "number" }, "rank": { "type": "number" } }, "required": [ "id", "name", "threshold", "rank" ], "additionalProperties": false } }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an unreferenced program", "tags": [ "tiers" ], "operationId": "delete_tier_programs_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tier_programs/{id}/evaluate": { "post": { "summary": "Run the upgrade-only tier evaluation for one customer now", "tags": [ "tiers" ], "operationId": "post_tier_programs_id_evaluate", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1 } }, "required": [ "customer_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effects": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "tier": { "anyOf": [ { "type": "object", "properties": { "customer_id": { "type": "string" }, "program_id": { "type": "string" }, "level": { "type": "string" }, "since": { "type": "string" }, "last_evaluated_at": { "type": "string" }, "source": { "type": "string", "enum": [ "evaluate", "job", "manual" ] } }, "required": [ "customer_id", "program_id", "level", "since", "last_evaluated_at", "source" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "effects", "tier" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/tiers": { "get": { "summary": "Current tier per program", "tags": [ "tiers" ], "operationId": "get_customers_id_tiers", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "customer_id": { "type": "string" }, "program_id": { "type": "string" }, "level": { "type": "string" }, "since": { "type": "string" }, "last_evaluated_at": { "type": "string" }, "source": { "type": "string", "enum": [ "evaluate", "job", "manual" ] } }, "required": [ "customer_id", "program_id", "level", "since", "last_evaluated_at", "source" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Operator tier set (either direction, audited, source manual)", "tags": [ "tiers" ], "operationId": "post_customers_id_tiers", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "program_id": { "type": "string", "minLength": 1 }, "level": { "type": "string", "minLength": 1 } }, "required": [ "program_id", "level" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "program_id": { "type": "string" }, "level": { "type": "string" }, "since": { "type": "string" }, "last_evaluated_at": { "type": "string" }, "source": { "type": "string", "enum": [ "evaluate", "job", "manual" ] } }, "required": [ "customer_id", "program_id", "level", "since", "last_evaluated_at", "source" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rewards": { "get": { "summary": "List rewards with issued counts", "tags": [ "rewards" ], "operationId": "get_rewards", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "archived" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cost": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "availability": { "type": [ "number", "null" ] }, "issued": { "type": "number" }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "cost", "currency", "availability", "issued", "expiry_after", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a reward", "tags": [ "rewards" ], "operationId": "post_rewards", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Free audiobook", "cost": 500, "currency": "points", "availability": 100, "expiry_after": "30d" }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cost": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "availability": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiry_after": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhdw]$" }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cost": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "availability": { "type": [ "number", "null" ] }, "issued": { "type": "number" }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "cost", "currency", "availability", "issued", "expiry_after", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rewards/{id}": { "get": { "summary": "One reward", "tags": [ "rewards" ], "operationId": "get_rewards_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cost": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "availability": { "type": [ "number", "null" ] }, "issued": { "type": "number" }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "cost", "currency", "availability", "issued", "expiry_after", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit or archive a reward (availability cannot drop below issued)", "tags": [ "rewards" ], "operationId": "patch_rewards_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cost": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "availability": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiry_after": { "anyOf": [ { "type": "string", "pattern": "^\\d+[smhdw]$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cost": { "type": "number" }, "currency": { "type": [ "string", "null" ] }, "availability": { "type": [ "number", "null" ] }, "issued": { "type": "number" }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "cost", "currency", "availability", "issued", "expiry_after", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a never-issued, unreferenced reward", "tags": [ "rewards" ], "operationId": "delete_rewards_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reward_issuances": { "get": { "summary": "List issuances", "tags": [ "rewards" ], "operationId": "get_reward_issuances", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "in": "query", "name": "reward_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] }, "source_type": { "type": "string", "enum": [ "rule_execution", "challenge", "manual" ] }, "source_id": { "type": [ "string", "null" ] }, "cost_entry_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "reward_id", "customer_id", "status", "source_type", "source_id", "cost_entry_id", "expires_at", "redeemed_at", "cancelled_at", "version", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Issue a reward to a customer manually (counts against availability)", "tags": [ "rewards" ], "operationId": "post_reward_issuances", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "reward_id": "rw_123", "customer_id": "cust_123" }, "schema": { "type": "object", "properties": { "reward_id": { "type": "string", "minLength": 1 }, "customer_id": { "type": "string", "minLength": 1 } }, "required": [ "reward_id", "customer_id" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] }, "source_type": { "type": "string", "enum": [ "rule_execution", "challenge", "manual" ] }, "source_id": { "type": [ "string", "null" ] }, "cost_entry_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "reward_id", "customer_id", "status", "source_type", "source_id", "cost_entry_id", "expires_at", "redeemed_at", "cancelled_at", "version", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reward_issuances/{id}": { "get": { "summary": "One issuance", "tags": [ "rewards" ], "operationId": "get_reward_issuances_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] }, "source_type": { "type": "string", "enum": [ "rule_execution", "challenge", "manual" ] }, "source_id": { "type": [ "string", "null" ] }, "cost_entry_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "reward_id", "customer_id", "status", "source_type", "source_id", "cost_entry_id", "expires_at", "redeemed_at", "cancelled_at", "version", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reward_issuances/{id}/redeem": { "post": { "summary": "Redeem: issued → redeemed, spending the reward cost in the same transaction", "tags": [ "rewards" ], "operationId": "post_reward_issuances_id_redeem", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] }, "source_type": { "type": "string", "enum": [ "rule_execution", "challenge", "manual" ] }, "source_id": { "type": [ "string", "null" ] }, "cost_entry_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "reward_id", "customer_id", "status", "source_type", "source_id", "cost_entry_id", "expires_at", "redeemed_at", "cancelled_at", "version", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reward_issuances/{id}/cancel": { "post": { "summary": "Cancel: refunds a spent cost by reversal and releases availability", "tags": [ "rewards" ], "operationId": "post_reward_issuances_id_cancel", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "reward_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "issued", "redeemed", "cancelled", "expired" ] }, "source_type": { "type": "string", "enum": [ "rule_execution", "challenge", "manual" ] }, "source_id": { "type": [ "string", "null" ] }, "cost_entry_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "redeemed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" } }, "required": [ "id", "reward_id", "customer_id", "status", "source_type", "source_id", "cost_entry_id", "expires_at", "redeemed_at", "cancelled_at", "version", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges": { "get": { "summary": "List challenges", "tags": [ "challenges" ], "operationId": "get_challenges", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifying": { "type": "object", "properties": { "event": { "type": "string" }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ], "additionalProperties": false }, "target": { "type": "number" }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign_id", "starts_at", "ends_at", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a challenge (validated qualifying conditions and completion actions)", "tags": [ "challenges" ], "operationId": "post_challenges", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "Finish three books", "qualifying": { "event": "content.completed" }, "target": 3, "contribution_key": "event.properties.content_id", "status": "active", "completion_actions": [ { "type": "points.award", "currency": "points", "amount": 300 } ] }, "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "qualifying": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1 }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ] }, "target": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "maxItems": 10, "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } }, "required": [ "name", "qualifying", "target" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifying": { "type": "object", "properties": { "event": { "type": "string" }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ], "additionalProperties": false }, "target": { "type": "number" }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign_id", "starts_at", "ends_at", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}": { "get": { "summary": "One challenge", "tags": [ "challenges" ], "operationId": "get_challenges_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifying": { "type": "object", "properties": { "event": { "type": "string" }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ], "additionalProperties": false }, "target": { "type": "number" }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign_id", "starts_at", "ends_at", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a challenge; changes apply to the next evaluation", "tags": [ "challenges" ], "operationId": "patch_challenges_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "qualifying": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1 }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ] }, "target": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "maxItems": 10, "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "ends_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "qualifying": { "type": "object", "properties": { "event": { "type": "string" }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ], "additionalProperties": false }, "target": { "type": "number" }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign_id": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign_id", "starts_at", "ends_at", "status", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a draft or ended challenge", "tags": [ "challenges" ], "operationId": "delete_challenges_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}/enrollments": { "get": { "summary": "Explicit enrollments", "tags": [ "challenges" ], "operationId": "get_challenges_id_enrollments", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "customer_id": { "type": "string" }, "enrolled_at": { "type": "string" } }, "required": [ "challenge_id", "customer_id", "enrolled_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Enroll a customer (idempotent)", "tags": [ "challenges" ], "operationId": "post_challenges_id_enrollments", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1 } }, "required": [ "customer_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "customer_id": { "type": "string" }, "enrolled_at": { "type": "string" } }, "required": [ "challenge_id", "customer_id", "enrolled_at" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "customer_id": { "type": "string" }, "enrolled_at": { "type": "string" } }, "required": [ "challenge_id", "customer_id", "enrolled_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}/enrollments/{customer_id}": { "delete": { "summary": "Remove an enrollment (progress rows stay)", "tags": [ "challenges" ], "operationId": "delete_challenges_id_enrollments_customer_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "path", "name": "customer_id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}/progress": { "get": { "summary": "Progress rows, optionally for one customer", "tags": [ "challenges" ], "operationId": "get_challenges_id_progress", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "customer_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "customer_id": { "type": "string" }, "period_key": { "type": "string" }, "count": { "type": "number" }, "target": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "completed" ] }, "contributions": { "type": "array", "items": { "type": "string" } }, "completed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "challenge_id", "customer_id", "period_key", "count", "target", "status", "contributions", "completed_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}/progress/revoke": { "post": { "summary": "Operator revoke of one contribution; the row is recomputed from its set", "tags": [ "challenges" ], "operationId": "post_challenges_id_progress_revoke", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1 }, "period_key": { "type": "string" }, "contribution": { "type": "string", "minLength": 1 } }, "required": [ "customer_id", "contribution" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string" }, "customer_id": { "type": "string" }, "period_key": { "type": "string" }, "count": { "type": "number" }, "status": { "type": "string", "enum": [ "active", "completed" ] }, "contributions": { "type": "array", "items": { "type": "string" } }, "completed_at": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "challenge_id", "customer_id", "period_key", "count", "status", "contributions", "completed_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/challenges/{id}/reevaluate": { "post": { "summary": "Complete active rows already at the target now (after lowering it or before ends_at)", "tags": [ "challenges" ], "operationId": "post_challenges_id_reevaluate", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "completed": { "type": "number" }, "effects": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "completed", "effects" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments": { "get": { "summary": "List segments", "tags": [ "segments" ], "operationId": "get_segments", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "members": { "type": [ "number", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "kind", "definition", "members", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a static or dynamic (customer.attributes.*) segment", "tags": [ "segments" ], "operationId": "post_segments", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "vip", "kind": "static" }, "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,59}$" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "name", "kind" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "members": { "type": [ "number", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "kind", "definition", "members", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments/{id}": { "get": { "summary": "One segment by id or name", "tags": [ "segments" ], "operationId": "get_segments_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "members": { "type": [ "number", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "kind", "definition", "members", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Rename (when unreferenced) or change a dynamic definition", "tags": [ "segments" ], "operationId": "patch_segments_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,59}$" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "members": { "type": [ "number", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "kind", "definition", "members", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an unreferenced segment", "tags": [ "segments" ], "operationId": "delete_segments_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments/{id}/members": { "get": { "summary": "Static members", "tags": [ "segments" ], "operationId": "get_segments_id_members", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "segment_id": { "type": "string" }, "customer_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "segment_id", "customer_id", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add static members (idempotent, up to 500 per call)", "tags": [ "segments" ], "operationId": "post_segments_id_members", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_ids": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "customer_ids" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "number" }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "segment_id": { "type": "string" }, "customer_id": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "segment_id", "customer_id", "created_at" ], "additionalProperties": false } } }, "required": [ "added", "memberships" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments/{id}/members/{customer_id}": { "delete": { "summary": "Remove a static member", "tags": [ "segments" ], "operationId": "delete_segments_id_members_customer_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "path", "name": "customer_id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/segments/{id}/eligibility/{customer_id}": { "get": { "summary": "Is this customer in the segment right now (dynamic ones evaluate live)", "tags": [ "segments" ], "operationId": "get_segments_id_eligibility_customer_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "path", "name": "customer_id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "segment": { "type": "string" }, "customer_id": { "type": "string" }, "eligible": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "operands": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "segment", "customer_id", "eligible", "kind" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/counter_definitions": { "get": { "summary": "List counter definitions with readiness", "tags": [ "counters" ], "operationId": "get_counter_definitions", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "event": { "type": "string" }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "backfilling", "ready" ] }, "backfill": { "type": "object", "properties": { "cutoff": { "type": "string" }, "pending_events": { "type": "number" } }, "required": [ "cutoff", "pending_events" ], "additionalProperties": false }, "created_at": { "type": "string" } }, "required": [ "id", "name", "event", "window", "filter", "status", "backfill", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register a historical counter; backfilling until history is counted", "tags": [ "counters" ], "operationId": "post_counter_definitions", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "name": "purchased_content", "event": "content.purchased", "window": "none" }, "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,59}$" }, "event": { "type": "string", "minLength": 1 }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "name", "event" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "event": { "type": "string" }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "backfilling", "ready" ] }, "backfill": { "type": "object", "properties": { "cutoff": { "type": "string" }, "pending_events": { "type": "number" } }, "required": [ "cutoff", "pending_events" ], "additionalProperties": false }, "created_at": { "type": "string" } }, "required": [ "id", "name", "event", "window", "filter", "status", "backfill", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/counter_definitions/{id}": { "get": { "summary": "One definition with backfill status", "tags": [ "counters" ], "operationId": "get_counter_definitions_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "event": { "type": "string" }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "backfilling", "ready" ] }, "backfill": { "type": "object", "properties": { "cutoff": { "type": "string" }, "pending_events": { "type": "number" } }, "required": [ "cutoff", "pending_events" ], "additionalProperties": false }, "created_at": { "type": "string" } }, "required": [ "id", "name", "event", "window", "filter", "status", "backfill", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a definition and its counts (refused while rules read it)", "tags": [ "counters" ], "operationId": "delete_counter_definitions_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/counter_definitions/{id}/backfill": { "post": { "summary": "Count history: inline for small histories, queued for the job otherwise", "tags": [ "counters" ], "operationId": "post_counter_definitions_id_backfill", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "backfilling" ] }, "mode": { "type": "string", "enum": [ "inline", "queued", "noop" ] }, "result": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "status", "mode" ], "additionalProperties": false } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "backfilling" ] }, "mode": { "type": "string", "enum": [ "inline", "queued", "noop" ] }, "result": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "status", "mode" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/counter_definitions/{id}/customers/{customer_id}": { "get": { "summary": "Counts per window for one customer", "tags": [ "counters" ], "operationId": "get_counter_definitions_id_customers_customer_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "path", "name": "customer_id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "counter": { "type": "string" }, "customer_id": { "type": "string" }, "windows": { "type": "array", "items": { "type": "object", "properties": { "window_key": { "type": "string" }, "count": { "type": "number" } }, "required": [ "window_key", "count" ], "additionalProperties": false } } }, "required": [ "counter", "customer_id", "windows" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints": { "get": { "summary": "List endpoints (secrets never shown)", "tags": [ "webhooks" ], "operationId": "get_webhook_endpoints", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "subscribed_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "url", "subscribed_types", "status", "disabled_reason", "failing_since", "secret_rotated_at", "version", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an endpoint; the signing secret is returned once", "tags": [ "webhooks" ], "operationId": "post_webhook_endpoints", "security": [ { "bearer": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it." } ], "requestBody": { "content": { "application/json": { "example": { "url": "https://example.com/hooks/orishare", "subscribed_types": [ "points.awarded", "reward.issued" ] }, "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "subscribed_types": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "url", "subscribed_types" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "subscribed_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "signing_secret": { "type": "string" } }, "required": [ "id", "url", "subscribed_types", "status", "disabled_reason", "failing_since", "secret_rotated_at", "version", "created_at", "updated_at", "signing_secret" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{id}": { "get": { "summary": "One endpoint", "tags": [ "webhooks" ], "operationId": "get_webhook_endpoints_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "subscribed_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "url", "subscribed_types", "status", "disabled_reason", "failing_since", "secret_rotated_at", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Change url, subscriptions, or re-enable a disabled endpoint", "tags": [ "webhooks" ], "operationId": "patch_webhook_endpoints_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2000 }, "subscribed_types": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "subscribed_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "url", "subscribed_types", "status", "disabled_reason", "failing_since", "secret_rotated_at", "version", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an endpoint and its delivery history", "tags": [ "webhooks" ], "operationId": "delete_webhook_endpoints_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{id}/secrets": { "post": { "summary": "Rotate the signing secret (returned once; the previous one verifies for 24 h)", "tags": [ "webhooks" ], "operationId": "post_webhook_endpoints_id_secrets", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "subscribed_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ] }, "version": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "signing_secret": { "type": "string" } }, "required": [ "id", "url", "subscribed_types", "status", "disabled_reason", "failing_since", "secret_rotated_at", "version", "created_at", "updated_at", "signing_secret" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_deliveries": { "get": { "summary": "List deliveries (newest first)", "tags": [ "webhooks" ], "operationId": "get_webhook_deliveries", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "endpoint_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending", "delivered", "dead", "disabled" ] } }, { "in": "query", "name": "event_type", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_type": { "type": "string" }, "event_id": { "type": "string" }, "payload": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead", "disabled" ] }, "attempts": { "type": "number" }, "next_attempt_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "replay_of": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "event_id", "payload", "status", "attempts", "next_attempt_at", "last_status", "last_error", "delivered_at", "replay_of", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Send a webhook.test ping to one endpoint now", "tags": [ "webhooks" ], "operationId": "post_webhook_deliveries", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint_id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "webhook.test" } }, "required": [ "endpoint_id" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_type": { "type": "string" }, "event_id": { "type": "string" }, "payload": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead", "disabled" ] }, "attempts": { "type": "number" }, "next_attempt_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "replay_of": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "event_id", "payload", "status", "attempts", "next_attempt_at", "last_status", "last_error", "delivered_at", "replay_of", "created_at" ], "additionalProperties": false }, "attempt": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "status": { "type": "string", "enum": [ "delivered", "pending", "dead", "disabled" ] }, "attempts": { "type": "number" }, "http_status": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] } }, "required": [ "delivery_id", "status", "attempts", "http_status", "error", "next_attempt_at" ], "additionalProperties": false } }, "required": [ "delivery", "attempt" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_deliveries/{id}": { "get": { "summary": "One delivery with its envelope and attempt history", "tags": [ "webhooks" ], "operationId": "get_webhook_deliveries_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_type": { "type": "string" }, "event_id": { "type": "string" }, "payload": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead", "disabled" ] }, "attempts": { "type": "number" }, "next_attempt_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "replay_of": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "event_id", "payload", "status", "attempts", "next_attempt_at", "last_status", "last_error", "delivered_at", "replay_of", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_deliveries/{id}/replay": { "post": { "summary": "Replay: a new delivery of the same envelope, attempted now", "tags": [ "webhooks" ], "operationId": "post_webhook_deliveries_id_replay", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint_id": { "type": "string" }, "event_type": { "type": "string" }, "event_id": { "type": "string" }, "payload": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "status": { "type": "string", "enum": [ "pending", "delivered", "dead", "disabled" ] }, "attempts": { "type": "number" }, "next_attempt_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "number", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "replay_of": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "endpoint_id", "event_type", "event_id", "payload", "status", "attempts", "next_attempt_at", "last_status", "last_error", "delivered_at", "replay_of", "created_at" ], "additionalProperties": false }, "attempt": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "status": { "type": "string", "enum": [ "delivered", "pending", "dead", "disabled" ] }, "attempts": { "type": "number" }, "http_status": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] } }, "required": [ "delivery_id", "status", "attempts", "http_status", "error", "next_attempt_at" ], "additionalProperties": false } }, "required": [ "delivery", "attempt" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_deliveries/fan_out": { "post": { "summary": "Materialize deliveries for one outbox payload (relay hook; local and tests)", "tags": [ "webhooks" ], "operationId": "post_webhook_deliveries_fan_out", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outbox_id": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "outbox_id", "payload" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "delivery_ids" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/organizations/{id}/audit_logs": { "get": { "summary": "Audit trail for an organization (filters by environment, action prefix, resource, actor, time)", "tags": [ "audit" ], "operationId": "get_organizations_id_audit_logs", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "maxLength": 2048 } }, { "in": "query", "name": "environment_id", "schema": { "type": "string" } }, { "in": "query", "name": "action", "schema": { "type": "string", "maxLength": 80 } }, { "in": "query", "name": "resource_type", "schema": { "type": "string", "maxLength": 60 } }, { "in": "query", "name": "resource_id", "schema": { "type": "string", "maxLength": 120 } }, { "in": "query", "name": "actor_id", "schema": { "type": "string", "maxLength": 120 } }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": "string" }, "environment_id": { "type": [ "string", "null" ] }, "actor": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "action": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": [ "string", "null" ] }, "before": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "after": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "organization_id", "environment_id", "actor", "action", "resource_type", "resource_id", "before", "after", "reason", "request_id", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/context": { "get": { "summary": "Project context for the AI and the UI: business description, vocabulary, glossary", "tags": [ "context" ], "operationId": "get_context", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment_id": { "type": "string" }, "business_description": { "type": [ "string", "null" ] }, "vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "glossary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "environment_id", "business_description", "vocabulary", "glossary", "version", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Merge-patch the context (null removes a vocabulary or glossary key)", "tags": [ "context" ], "operationId": "patch_context", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "business_description": { "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "glossary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment_id": { "type": "string" }, "business_description": { "type": [ "string", "null" ] }, "vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "glossary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "version": { "type": "number" }, "updated_at": { "type": "string" } }, "required": [ "environment_id", "business_description", "vocabulary", "glossary", "version", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/{id}/retry": { "post": { "summary": "Re-run an accepted, failed or poison event with its original identity", "tags": [ "events" ], "operationId": "post_events_id_retry", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "enum": [ "evaluated", "already_evaluated", "paused" ] }, "plan": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "trace": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "effects": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "execution_id", "status", "plan", "trace", "effects" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/poison_events": { "get": { "summary": "Events parked after repeated evaluator failures", "tags": [ "events" ], "operationId": "get_poison_events", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "include_resolved", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "event_name": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "attempts": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ] }, "resolution": { "anyOf": [ { "type": "string", "enum": [ "retried", "discarded" ] }, { "type": "null" } ] } }, "required": [ "event_id", "event_name", "customer_id", "attempts", "last_error", "last_error_at", "resolved_at", "resolution" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/poison_events/{id}/discard": { "post": { "summary": "Give up on a parked event (audited); it stays failed and never re-runs", "tags": [ "events" ], "operationId": "post_poison_events_id_discard", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/support/organizations": { "get": { "summary": "Find organizations by name, slug, id or member email (staff)", "tags": [ "support" ], "operationId": "get_support_organizations", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "q", "schema": { "type": "string", "minLength": 2, "maxLength": 120 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "is_internal": { "type": "boolean" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" } }, "required": [ "id", "version" ], "additionalProperties": false }, "ai_drafting_disabled": { "type": "boolean" }, "members": { "type": "number" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string" }, "rules_paused": { "type": "boolean" } }, "required": [ "id", "name", "runtime_class", "rules_paused" ], "additionalProperties": false } } }, "required": [ "id", "name", "environments" ], "additionalProperties": false } }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "is_internal", "plan", "ai_drafting_disabled", "members", "projects", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/support/organizations/{id}": { "get": { "summary": "Organization overview with projects and environments (staff)", "tags": [ "support" ], "operationId": "get_support_organizations_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "is_internal": { "type": "boolean" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" } }, "required": [ "id", "version" ], "additionalProperties": false }, "ai_drafting_disabled": { "type": "boolean" }, "members": { "type": "number" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "runtime_class": { "type": "string" }, "rules_paused": { "type": "boolean" } }, "required": [ "id", "name", "runtime_class", "rules_paused" ], "additionalProperties": false } } }, "required": [ "id", "name", "environments" ], "additionalProperties": false } }, "created_at": { "type": "string" } }, "required": [ "id", "name", "slug", "is_internal", "plan", "ai_drafting_disabled", "members", "projects", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/config/export": { "get": { "summary": "Whole environment configuration as one JSON document (names as references, no secrets)", "tags": [ "config" ], "operationId": "get_config_export", "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "type": "string", "const": "orishare.config/v1" }, "exported_at": { "type": "string" }, "source": { "type": "object", "properties": { "environment_id": { "type": "string" }, "runtime_class": { "type": "string" } }, "required": [ "environment_id", "runtime_class" ], "additionalProperties": false }, "currencies": { "default": [], "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "precision": { "type": "integer", "minimum": 0, "maximum": 6 }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ], "additionalProperties": false }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] } }, "required": [ "code", "name", "precision", "expiration_policy", "negative_balance" ], "additionalProperties": false } }, "attribute_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ] }, "description": { "type": [ "string", "null" ] }, "pii": { "type": "boolean" } }, "required": [ "key", "type", "description", "pii" ], "additionalProperties": false } }, "event_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "client_allowed": { "type": "boolean" }, "confirmed_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, { "type": "null" } ] } }, "required": [ "name", "description", "client_allowed", "confirmed_schema" ], "additionalProperties": false } }, "segments": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] } }, "required": [ "name", "kind", "definition" ], "additionalProperties": false } }, "counter_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "event": { "type": "string", "minLength": 1 }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] } }, "required": [ "name", "event", "window", "filter" ], "additionalProperties": false } }, "tier_programs": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "currency": { "type": "string" }, "basis": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "threshold": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "threshold" ], "additionalProperties": false } } }, "required": [ "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels" ], "additionalProperties": false } }, "rewards": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cost": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": [ "string", "null" ] }, "availability": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "name", "cost", "currency", "availability", "expiry_after", "status" ], "additionalProperties": false } }, "campaigns": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "window": { "anyOf": [ { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, { "type": "null" } ] } }, "required": [ "amount", "currency", "window" ], "additionalProperties": false }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience" ], "additionalProperties": false } }, "rules": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "campaign": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "name", "campaign", "priority", "status", "definition" ], "additionalProperties": false } }, "challenges": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "qualifying": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1 }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ], "additionalProperties": false }, "target": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } }, "required": [ "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign", "starts_at", "ends_at", "status" ], "additionalProperties": false } }, "webhook_endpoints": { "default": [], "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "subscribed_types": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "url", "subscribed_types", "status" ], "additionalProperties": false } }, "context": { "default": null, "anyOf": [ { "type": "object", "properties": { "business_description": { "type": [ "string", "null" ] }, "vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "glossary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "business_description", "vocabulary", "glossary" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schema", "currencies", "attribute_definitions", "event_definitions", "segments", "counter_definitions", "tier_programs", "rewards", "campaigns", "rules", "challenges", "webhook_endpoints", "context" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/config/apply": { "post": { "summary": "Preview or apply a configuration document to this environment atomically", "tags": [ "config" ], "operationId": "post_config_apply", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "example": { "mode": "preview", "publish": true, "document": { "schema": "orishare.config/v1", "currencies": [ { "code": "points", "name": "Points", "precision": 0, "expiration_policy": { "type": "never" }, "negative_balance": "forbid" } ] } }, "schema": { "type": "object", "properties": { "document": { "type": "object", "properties": { "schema": { "type": "string", "const": "orishare.config/v1" }, "exported_at": { "type": "string" }, "source": { "type": "object", "properties": { "environment_id": { "type": "string" }, "runtime_class": { "type": "string" } }, "required": [ "environment_id", "runtime_class" ] }, "currencies": { "default": [], "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "precision": { "type": "integer", "minimum": 0, "maximum": 6 }, "expiration_policy": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "never", "days" ] }, "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type" ] }, "negative_balance": { "type": "string", "enum": [ "forbid", "allow" ] } }, "required": [ "code", "name", "precision", "expiration_policy", "negative_balance" ] } }, "attribute_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "timestamp" ] }, "description": { "type": [ "string", "null" ] }, "pii": { "type": "boolean" } }, "required": [ "key", "type", "description", "pii" ] } }, "event_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "client_allowed": { "type": "boolean" }, "confirmed_schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, { "type": "null" } ] } }, "required": [ "name", "description", "client_allowed", "confirmed_schema" ] } }, "segments": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "static", "dynamic" ] }, "definition": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] } }, "required": [ "name", "kind", "definition" ] } }, "counter_definitions": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "event": { "type": "string", "minLength": 1 }, "window": { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, "filter": { "anyOf": [ { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, { "type": "null" } ] } }, "required": [ "name", "event", "window", "filter" ] } }, "tier_programs": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "currency": { "type": "string" }, "basis": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "downgrade_check": { "type": "string", "enum": [ "daily", "monthly", "never" ] }, "is_default": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "levels": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "threshold": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "threshold" ] } } }, "required": [ "name", "currency", "basis", "downgrade_check", "is_default", "status", "levels" ] } }, "rewards": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "cost": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": [ "string", "null" ] }, "availability": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiry_after": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] } }, "required": [ "name", "cost", "currency", "availability", "expiry_after", "status" ] } }, "campaigns": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stacking_group": { "type": [ "string", "null" ] }, "exclusive": { "type": "boolean" }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "window": { "anyOf": [ { "type": "string", "enum": [ "none", "day", "week", "month", "year" ] }, { "type": "null" } ] } }, "required": [ "amount", "currency", "window" ] }, { "type": "null" } ] }, "audience": { "anyOf": [ { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segments" ] }, { "type": "null" } ] } }, "required": [ "name", "status", "starts_at", "ends_at", "priority", "stacking_group", "exclusive", "budget", "audience" ] } }, "rules": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "campaign": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "name", "campaign", "priority", "status", "definition" ] } }, "challenges": { "default": [], "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "qualifying": { "type": "object", "properties": { "event": { "type": "string", "minLength": 1 }, "conditions": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "required": [ "event" ] }, "target": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "period": { "type": "string", "enum": [ "none", "day", "week", "month" ] }, "contribution_key": { "type": [ "string", "null" ] }, "enrollment": { "type": "string", "enum": [ "automatic", "explicit" ] }, "repeatable": { "type": "boolean" }, "completion_actions": { "type": "array", "items": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "campaign": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "ended" ] } }, "required": [ "name", "qualifying", "target", "period", "contribution_key", "enrollment", "repeatable", "completion_actions", "campaign", "starts_at", "ends_at", "status" ] } }, "webhook_endpoints": { "default": [], "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "subscribed_types": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "url", "subscribed_types", "status" ] } }, "context": { "default": null, "anyOf": [ { "type": "object", "properties": { "business_description": { "type": [ "string", "null" ] }, "vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } }, "glossary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." } } }, "required": [ "business_description", "vocabulary", "glossary" ] }, { "type": "null" } ] } }, "required": [ "schema" ] }, "mode": { "default": "preview", "type": "string", "enum": [ "preview", "apply" ] }, "publish": { "default": true, "type": "boolean" } }, "required": [ "document" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "preview", "apply" ] }, "applied": { "type": "boolean" }, "diff": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "create": { "type": "array", "items": { "type": "string" } }, "update": { "type": "array", "items": { "type": "string" } }, "unchanged": { "type": "array", "items": { "type": "string" } } }, "required": [ "create", "update", "unchanged" ], "additionalProperties": false } }, "changes": { "type": "number" }, "published_rules": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "applied", "diff", "changes", "published_rules", "notes" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ai/rule_drafts": { "post": { "summary": "Draft rules from a plain-English request: validated against the environment, stored, never published", "tags": [ "ai" ], "operationId": "post_ai_rule_drafts", "security": [ { "bearer": [] } ], "requestBody": { "content": { "application/json": { "example": { "request": "When a customer buys an audiobook give them 100 points, 50 more when they get halfway through it, and 200 when they finish it. Each of those only once per title.", "max_rules": 5 }, "schema": { "type": "object", "properties": { "request": { "type": "string", "minLength": 3, "maxLength": 4000 }, "max_rules": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "request" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "rejected", "failed" ] }, "request": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "explanation": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "path", "message" ], "additionalProperties": false } } }, "required": [ "name", "definition", "explanation", "warnings" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "questions": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": [ "number", "null" ] }, "code": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "required": [ "rule", "code", "path", "message" ], "additionalProperties": false } }, "model": { "type": "string" }, "prompt_hash": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": [ "number", "null" ] }, "output_tokens": { "type": [ "number", "null" ] } }, "required": [ "input_tokens", "output_tokens" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "chars": { "type": "number" }, "truncated": { "type": "array", "items": { "type": "string" } } }, "required": [ "chars", "truncated" ], "additionalProperties": false }, "rule_id": { "type": [ "string", "null" ] }, "rule_version_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "status", "request", "rules", "assumptions", "questions", "errors", "model", "prompt_hash", "usage", "context", "rule_id", "rule_version_id", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Recent drafts in this environment (newest first)", "tags": [ "ai" ], "operationId": "get_ai_rule_drafts", "security": [ { "bearer": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "rejected", "failed" ] }, "request": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "explanation": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "path", "message" ], "additionalProperties": false } } }, "required": [ "name", "definition", "explanation", "warnings" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "questions": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": [ "number", "null" ] }, "code": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "required": [ "rule", "code", "path", "message" ], "additionalProperties": false } }, "model": { "type": "string" }, "prompt_hash": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": [ "number", "null" ] }, "output_tokens": { "type": [ "number", "null" ] } }, "required": [ "input_tokens", "output_tokens" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "chars": { "type": "number" }, "truncated": { "type": "array", "items": { "type": "string" } } }, "required": [ "chars", "truncated" ], "additionalProperties": false }, "rule_id": { "type": [ "string", "null" ] }, "rule_version_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "status", "request", "rules", "assumptions", "questions", "errors", "model", "prompt_hash", "usage", "context", "rule_id", "rule_version_id", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ai/rule_drafts/{id}": { "get": { "summary": "One draft with its rules, assumptions, errors and the rule it became", "tags": [ "ai" ], "operationId": "get_ai_rule_drafts_id", "security": [ { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1 }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "rejected", "failed" ] }, "request": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "definition": { "description": "Any JSON value (object, array, string, number, boolean or null). Kept non-recursive in the OpenAPI document." }, "explanation": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "path", "message" ], "additionalProperties": false } } }, "required": [ "name", "definition", "explanation", "warnings" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "questions": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": [ "number", "null" ] }, "code": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "message": { "type": "string" } }, "required": [ "rule", "code", "path", "message" ], "additionalProperties": false } }, "model": { "type": "string" }, "prompt_hash": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": [ "number", "null" ] }, "output_tokens": { "type": [ "number", "null" ] } }, "required": [ "input_tokens", "output_tokens" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "chars": { "type": "number" }, "truncated": { "type": "array", "items": { "type": "string" } } }, "required": [ "chars", "truncated" ], "additionalProperties": false }, "rule_id": { "type": [ "string", "null" ] }, "rule_version_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "status", "request", "rules", "assumptions", "questions", "errors", "model", "prompt_hash", "usage", "context", "rule_id", "rule_version_id", "created_at" ], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request", "authentication", "permission", "not_found", "conflict", "rate_limited", "idempotency", "api_error" ] }, "code": { "type": "string", "enum": [ "validation_failed", "invalid_cursor", "invalid_json", "body_too_large", "event_too_large", "batch_too_large", "occurred_at_in_future", "unsupported_media_type", "authentication_required", "invalid_credentials", "credentials_revoked", "environment_required", "insufficient_scope", "event_requires_secret_key", "origin_not_allowed", "audit_reason_required", "forbidden", "route_not_found", "resource_not_found", "stale_write", "resource_in_use", "already_exists", "event_id_conflict", "alias_conflict", "invalid_state", "insufficient_balance", "reward_unavailable", "last_owner", "rule_invalid", "idempotency_key_required", "idempotency_key_reused", "idempotency_in_progress", "rate_limited", "quota_exceeded", "ai_drafting_disabled", "ai_draft_rejected", "ai_unavailable", "evaluation_failed", "internal_error" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "doc_url": { "type": "string" }, "request_id": { "type": "string" }, "details": {} }, "required": [ "type", "code", "message", "param", "doc_url", "request_id" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…)." } } } }