{ "openapi": "3.1.0", "info": { "title": "Campaign Assistant API", "version": "v1", "summary": "Campaign drafting over a shared, runtime-validated contract.", "description": "Every endpoint below is described by the shared contract package: the request and response schemas served here are the ones the web app validates against at runtime.\n\nAuthentication is a bearer access token obtained from `auth.signIn`. Errors are always an RFC 9457 problem document. Chat replies can be streamed as server-sent events; see `chat.messages.stream`.", "license": { "name": "UNLICENSED", "identifier": "UNLICENSED" } }, "servers": [ { "url": "http://localhost:4000/api/v1", "description": "This deployment" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "Sign-in, token rotation and sign-out." }, { "name": "Customers", "description": "The customer base: records, aggregates and bulk import." }, { "name": "Segments", "description": "Saved audience definitions and live audience counts." }, { "name": "Campaigns", "description": "Model-assisted campaign drafting and its review workflow." }, { "name": "Chat", "description": "Assistant threads, including server-sent streaming of replies." } ], "paths": { "/v1/auth/sign-in": { "post": { "operationId": "auth.signIn", "summary": "Sign in with email and password", "description": "Verifies the credentials, then mints an access/refresh pair. Refresh tokens are single-use: `auth.refresh` rotates them, so a token can only be exchanged once.", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "minLength": 1 }, "refreshToken": { "type": "string", "minLength": 1 }, "expiresIn": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "user": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fullName": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "marketing_lead", "lifecycle_marketer", "admin" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "fullName", "email", "role", "isActive", "createdAt" ], "additionalProperties": false } }, "required": [ "accessToken", "refreshToken", "expiresIn", "user" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/auth/refresh": { "post": { "operationId": "auth.refresh", "summary": "Exchange a refresh token for a new session", "description": "Rotates the pair. The presented refresh token is revoked as part of the exchange, so replaying it is rejected as `session_expired`.", "tags": [ "Authentication" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1 } }, "required": [ "refreshToken" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accessToken": { "type": "string", "minLength": 1 }, "refreshToken": { "type": "string", "minLength": 1 }, "expiresIn": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "user": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fullName": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "marketing_lead", "lifecycle_marketer", "admin" ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "fullName", "email", "role", "isActive", "createdAt" ], "additionalProperties": false } }, "required": [ "accessToken", "refreshToken", "expiresIn", "user" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/auth/sign-out": { "post": { "operationId": "auth.signOut", "summary": "Revoke the current session", "description": "Revokes the refresh token presented in the body. Idempotent: signing out twice is not an error. The access token stays usable until it expires, which keeps sign-out instantaneous.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1 } }, "required": [ "refreshToken" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers": { "get": { "operationId": "customers.list", "summary": "List customers", "description": "Paginated and filterable. Filtering, sorting and pagination all happen server-side, so a page never depends on how large the table is.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "default": "", "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "default": "all", "anyOf": [ { "type": "string", "enum": [ "active", "inactive", "churned" ] }, { "type": "string", "const": "all" } ] } }, { "name": "country", "in": "query", "required": false, "schema": { "default": "", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "default": "lastActivityDate", "type": "string", "enum": [ "name", "totalAmountSpent", "totalTransactions", "lastActivityDate" ] } }, { "name": "direction", "in": "query", "required": false, "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "country": { "type": "string", "minLength": 2 }, "totalTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalAmountSpent": { "type": "number", "minimum": 0 }, "lastActivityDate": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "churned" ] } }, "required": [ "id", "name", "email", "country", "totalTransactions", "totalAmountSpent", "lastActivityDate", "status" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "items", "total", "page", "limit" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "customers.create", "summary": "Create a customer", "description": "Adds one customer. A duplicate email is rejected with `conflict` rather than merged, so the caller decides what to do with it.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "country": { "type": "string", "minLength": 2 }, "totalTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalAmountSpent": { "type": "number", "minimum": 0 }, "lastActivityDate": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "churned" ] } }, "required": [ "name", "email", "country", "totalTransactions", "totalAmountSpent", "lastActivityDate", "status" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "country": { "type": "string", "minLength": 2 }, "totalTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalAmountSpent": { "type": "number", "minimum": 0 }, "lastActivityDate": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "churned" ] } }, "required": [ "id", "name", "email", "country", "totalTransactions", "totalAmountSpent", "lastActivityDate", "status" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers/kpis": { "get": { "operationId": "customers.kpis", "summary": "Customer KPIs", "description": "Aggregate totals for the dashboard: headcount, active customers, lifetime value, average value and the per-status headcount split.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCustomers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeCustomers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalTransactionValue": { "type": "number", "minimum": 0 }, "averageCustomerValue": { "type": "number", "minimum": 0 }, "statusCounts": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "inactive": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "churned": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "active", "inactive", "churned" ], "additionalProperties": false } }, "required": [ "totalCustomers", "activeCustomers", "totalTransactionValue", "averageCustomerValue", "statusCounts" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers/trend": { "get": { "operationId": "customers.activityTrend", "summary": "Customer activity trend", "description": "Customers bucketed by the month of their last activity, trailing the requested number of months (default 6, max 24). Each point carries the lifetime value those customers represent, the customer count and the churned count, ascending by month.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "months", "in": "query", "required": false, "schema": { "default": 6, "type": "integer", "minimum": 3, "maximum": 24 } } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "value": { "type": "number", "minimum": 0 }, "customers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "churned": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "month", "value", "customers", "churned" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers/health": { "get": { "operationId": "customers.health", "summary": "Customer base health", "description": "A composite score from 0 to 100 with a `healthy` / `attention` / `critical` level, the active and churned shares, the inactive headcount and the number of still-`active` customers whose last activity is older than 60 days.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "string", "enum": [ "healthy", "attention", "critical" ] }, "activeShare": { "type": "number", "minimum": 0, "maximum": 100 }, "churnedShare": { "type": "number", "minimum": 0, "maximum": 100 }, "inactiveCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "staleActives": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "score", "level", "activeShare", "churnedShare", "inactiveCount", "staleActives" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers/top": { "get": { "operationId": "customers.top", "summary": "Top customers by lifetime value", "description": "The highest-value customers plus the lifetime value of the whole base, so a leaderboard can render each share without a second call.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "default": 5, "type": "integer", "minimum": 1, "maximum": 25 } } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "totalValue": { "type": "number", "minimum": 0 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2 }, "status": { "type": "string", "enum": [ "active", "inactive", "churned" ] }, "totalAmountSpent": { "type": "number", "minimum": 0 }, "totalTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "name", "country", "status", "totalAmountSpent", "totalTransactions" ], "additionalProperties": false } } }, "required": [ "totalValue", "items" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/customers/import": { "post": { "operationId": "customers.import", "summary": "Import customers in bulk", "description": "Partial import: valid rows are persisted and invalid ones are reported per row, so one bad line does not fail the whole file. `row` is the 1-based position within `customers`.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "country": { "type": "string", "minLength": 2 }, "totalTransactions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalAmountSpent": { "type": "number", "minimum": 0 }, "lastActivityDate": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "churned" ] } }, "required": [ "name", "email", "country", "totalTransactions", "totalAmountSpent", "lastActivityDate", "status" ] } } }, "required": [ "customers" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failures": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "row", "reason" ], "additionalProperties": false } } }, "required": [ "imported", "skipped", "failures" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/countries": { "get": { "operationId": "countries.list", "summary": "List known countries", "description": "Distinct countries present in the customer base, sorted alphabetically.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/countries/spend": { "get": { "operationId": "countries.spend", "summary": "Spend grouped by country", "description": "Total spend per country, ordered by amount so a dashboard can render a ranking without sorting client-side.", "tags": [ "Customers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2 }, "spend": { "type": "number", "minimum": 0 } }, "required": [ "country", "spend" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments": { "get": { "operationId": "segments.list", "summary": "List saved segments", "description": "Returns saved segments with their stored conditions and last known audience size.", "tags": [ "Segments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "conditions": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "totalAmountSpent", "totalTransactions", "lastActivityDays" ] }, "operator": { "type": "string", "enum": [ "gt", "lt", "eq" ] }, "value": { "type": "number" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "const": "country" }, "operator": { "type": "string", "const": "eq" }, "value": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value", "id" ], "additionalProperties": false } ] } }, "matchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "conditions", "matchCount", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "segments.create", "summary": "Save a segment", "description": "Conditions are combined with AND. Clauses keep the order they were written in so a saved segment stays readable.", "tags": [ "Segments" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "conditions": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "totalAmountSpent", "totalTransactions", "lastActivityDays" ] }, "operator": { "type": "string", "enum": [ "gt", "lt", "eq" ] }, "value": { "type": "number" } }, "required": [ "field", "operator", "value" ] }, { "type": "object", "properties": { "field": { "type": "string", "const": "country" }, "operator": { "type": "string", "const": "eq" }, "value": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value" ] } ] } } }, "required": [ "name", "conditions" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "conditions": { "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "totalAmountSpent", "totalTransactions", "lastActivityDays" ] }, "operator": { "type": "string", "enum": [ "gt", "lt", "eq" ] }, "value": { "type": "number" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "const": "country" }, "operator": { "type": "string", "const": "eq" }, "value": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value", "id" ], "additionalProperties": false } ] } }, "matchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "conditions", "matchCount", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments/{id}": { "delete": { "operationId": "segments.delete", "summary": "Delete a segment", "description": "Removes the segment. Campaigns generated from it keep their stored copy of the segment name, so history stays readable.", "tags": [ "Segments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the resource being addressed." } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments/preview": { "post": { "operationId": "segments.preview", "summary": "Preview a segment audience", "description": "Counts the customers matching unsaved conditions. Use it while building, before committing a segment.", "tags": [ "Segments" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conditions": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "totalAmountSpent", "totalTransactions", "lastActivityDays" ] }, "operator": { "type": "string", "enum": [ "gt", "lt", "eq" ] }, "value": { "type": "number" } }, "required": [ "field", "operator", "value" ] }, { "type": "object", "properties": { "field": { "type": "string", "const": "country" }, "operator": { "type": "string", "const": "eq" }, "value": { "type": "string", "minLength": 1 } }, "required": [ "field", "operator", "value" ] } ] } } }, "required": [ "conditions" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "matchCount" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/segments/summary": { "get": { "operationId": "segments.summary", "summary": "Saved segments summary", "description": "Aggregate figures for the dashboard: how many segments are saved and how much audience they cover in total and on average.", "tags": [ "Segments" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalAudience": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "averageAudience": { "type": "number", "minimum": 0 } }, "required": [ "count", "totalAudience", "averageAudience" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/campaigns": { "get": { "operationId": "campaigns.list", "summary": "List generated campaigns", "description": "Newest first.", "tags": [ "Campaigns" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "callToAction": { "type": "string", "minLength": 1 }, "segmentId": { "type": "string", "minLength": 1 }, "segmentName": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ] }, "tone": { "type": "string", "enum": [ "professional", "friendly", "urgent", "promotional" ] }, "status": { "type": "string", "enum": [ "draft", "ready", "sent" ] }, "objective": { "type": "string", "minLength": 1 }, "generatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "title", "message", "callToAction", "segmentId", "segmentName", "channel", "tone", "status", "objective", "generatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/campaigns/generate": { "post": { "operationId": "campaigns.generate", "summary": "Generate a campaign", "description": "Runs the configured language model over a saved segment and returns a drafted campaign. Generation is a server concern: the browser never talks to the model provider. Send an `Idempotency-Key` header to make the call safe to retry: the first response is recorded against the key, a repeat returns it with `Idempotency-Replayed: true` instead of generating a second campaign, and reusing a key for a different body is rejected with `conflict`.", "tags": [ "Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x21-\\x7e]+$" }, "description": "Makes this call safe to retry. The first response is recorded against the key; a repeat of the same request returns it with `Idempotency-Replayed: true` instead of repeating the side effect. Reusing a key for a different request body is rejected with `conflict`. Only a successful response is recorded, so a failed attempt stays retryable with the same key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "string", "minLength": 10, "maxLength": 600 }, "segmentId": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ] }, "tone": { "type": "string", "enum": [ "professional", "friendly", "urgent", "promotional" ] }, "language": { "default": "en", "type": "string", "enum": [ "en", "fr" ] }, "includeDiscount": { "default": false, "type": "boolean" } }, "required": [ "objective", "segmentId", "channel", "tone" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "callToAction": { "type": "string", "minLength": 1 }, "segmentId": { "type": "string", "minLength": 1 }, "segmentName": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ] }, "tone": { "type": "string", "enum": [ "professional", "friendly", "urgent", "promotional" ] }, "status": { "type": "string", "enum": [ "draft", "ready", "sent" ] }, "objective": { "type": "string", "minLength": 1 }, "generatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "title", "message", "callToAction", "segmentId", "segmentName", "channel", "tone", "status", "objective", "generatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/campaigns/{id}/status": { "patch": { "operationId": "campaigns.updateStatus", "summary": "Change a campaign status", "description": "Legal transitions are `draft` to `ready` to `sent`, plus `ready` back to `draft`. Anything else is rejected with `conflict`.", "tags": [ "Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the resource being addressed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "ready", "sent" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "callToAction": { "type": "string", "minLength": 1 }, "segmentId": { "type": "string", "minLength": 1 }, "segmentName": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "sms", "email", "push" ] }, "tone": { "type": "string", "enum": [ "professional", "friendly", "urgent", "promotional" ] }, "status": { "type": "string", "enum": [ "draft", "ready", "sent" ] }, "objective": { "type": "string", "minLength": 1 }, "generatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "title", "message", "callToAction", "segmentId", "segmentName", "channel", "tone", "status", "objective", "generatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/campaigns/{id}": { "delete": { "operationId": "campaigns.delete", "summary": "Delete a campaign", "description": "Removes the campaign.", "tags": [ "Campaigns" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the resource being addressed." } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/chat/threads": { "get": { "operationId": "chat.threads.list", "summary": "List chat threads", "description": "Newest first, with the message count of each thread.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "title", "createdAt", "updatedAt", "messageCount" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "chat.threads.create", "summary": "Start a chat thread", "description": "Creates an empty thread. The title is derived from the first message once one exists.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 } } } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "title", "createdAt", "updatedAt", "messageCount" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/chat/threads/{id}": { "delete": { "operationId": "chat.threads.delete", "summary": "Delete a chat thread", "description": "Removes the thread and its messages.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the resource being addressed." } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/chat/threads/{threadId}/messages": { "get": { "operationId": "chat.messages.list", "summary": "List thread messages", "description": "Oldest first, so a client can render the transcript in order.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the thread being addressed." } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "model": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "threadId", "role", "content", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "chat.messages.send", "summary": "Send a message and wait for the reply", "description": "Non-streaming counterpart of `chat.messages.stream`: one request, one complete assistant message.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the thread being addressed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 8000 }, "language": { "default": "en", "type": "string", "enum": [ "en", "fr" ] } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "userMessage": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "model": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "threadId", "role", "content", "createdAt" ], "additionalProperties": false }, "assistantMessage": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "model": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "threadId", "role", "content", "createdAt" ], "additionalProperties": false } }, "required": [ "userMessage", "assistantMessage" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/search": { "get": { "operationId": "search.global", "summary": "Search across customers, segments and campaigns", "description": "Relevance-ranked, fuzzy. A query may match a substring, a word prefix or (for three or more characters) a trigram-similar phrase; the signal is accent-insensitive, so typography cannot hide a match. Results mix all three record types sorted by score, which the palette mirrors as grouped sections. Every result answers with a `score`, the client-facing rank, never with an SQL value.", "tags": [ "Search" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 8, "type": "integer", "minimum": 1, "maximum": 24 } } ], "responses": { "200": { "description": "OK", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tookMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer", "segment", "campaign" ] }, "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meta": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "type": "number", "minimum": 0 } }, "required": [ "type", "id", "title", "subtitle", "meta", "score" ], "additionalProperties": false } } }, "required": [ "query", "total", "tookMs", "results" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/chat/threads/{threadId}/messages/stream": { "post": { "operationId": "chat.messages.stream", "summary": "Send a message and stream the reply", "description": "Server-sent events. Frames are `start`, then one `delta` per chunk, then a terminal `done` or `error`. The request stays open for the whole reply, so a proxy in front of the API must not buffer it.", "tags": [ "Chat" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Identifier of the thread being addressed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 8000 }, "language": { "default": "en", "type": "string", "enum": [ "en", "fr" ] } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "A stream of chat events.", "headers": { "x-api-version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "event: message\ndata: {\"type\":\"delta\",\"content\":\"Bonjour\"}" } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "Bad Gateway", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Service Unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Access token issued by `auth.signIn`. Expires; refresh it with `auth.refresh`." } }, "headers": { "ApiVersion": { "description": "The API version that answered this request.", "schema": { "type": "string", "const": "v1", "examples": [ "v1" ] } } }, "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "validation_failed", "invalid_credentials", "unauthenticated", "session_expired", "forbidden", "not_found", "conflict", "rate_limited", "llm_unavailable", "llm_error", "internal_error" ] }, "errors": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "traceId": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "code" ], "additionalProperties": false }, "ErrorCode": { "type": "string", "enum": [ "validation_failed", "invalid_credentials", "unauthenticated", "session_expired", "forbidden", "not_found", "conflict", "rate_limited", "llm_unavailable", "llm_error", "internal_error" ] } } } }