{ "openapi": "3.1.0", "info": { "title": "Samplence Public API", "version": "1.0.0", "description": "REST API for managing Samplence case files, billing, research runs, and machine-accessible workspace automation." }, "servers": [ { "url": "https://api.samplence.com", "description": "Production API origin" } ], "externalDocs": { "description": "Samplence API reference", "url": "https://docs.samplence.com/reference" }, "tags": [ { "name": "System" }, { "name": "Billing" }, { "name": "API Keys" }, { "name": "Chat" } ], "components": { "securitySchemes": { "bearerApiKey": { "bearerFormat": "API key", "description": "Send the Samplence API key as `Authorization: Bearer `.", "scheme": "bearer", "type": "http" } }, "schemas": { "BillingTopUpRequest": { "additionalProperties": false, "properties": { "cancelUrl": { "format": "uri", "type": "string" }, "successUrl": { "format": "uri", "type": "string" }, "usdQuantity": { "minimum": 1, "type": "integer" } }, "required": [ "cancelUrl", "successUrl", "usdQuantity" ], "type": "object" }, "ChatMessageRequest": { "additionalProperties": false, "properties": { "message": { "minLength": 1, "type": "string" } }, "required": [ "message" ], "type": "object" }, "ResearchRunRequest": { "additionalProperties": false, "properties": { "force": { "type": "boolean" } }, "type": "object" }, "ApiKeyCreateRequest": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "name": { "minLength": 1, "type": "string" }, "scopes": { "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "minItems": 1, "type": "array" } }, "required": [ "name", "scopes" ], "type": "object" }, "ApiKeyScope": { "enum": [ "threads_read", "threads_write", "research_write", "billing_read", "billing_write", "api_keys_admin" ], "type": "string" }, "AgentConversationMessage": { "additionalProperties": false, "properties": { "content": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "role": { "enum": [ "assistant", "user" ], "type": "string" }, "status": { "enum": [ "complete", "failed", "pending" ], "type": "string" } }, "required": [ "content", "createdAt", "id", "role", "status" ], "type": "object" }, "AgentResearchReportSummary": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "runId": { "type": "string" }, "summaryText": { "nullable": true, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "createdAt", "id", "runId", "summaryText", "updatedAt" ], "type": "object" }, "AgentResearchRunSummary": { "additionalProperties": false, "properties": { "finishedAt": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "queuedAt": { "format": "date-time", "type": "string" }, "reportId": { "nullable": true, "type": "string" }, "startedAt": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "type": "string" }, "statusMessage": { "nullable": true, "type": "string" }, "triggerMode": { "enum": [ "forced", "ready" ], "type": "string" } }, "required": [ "finishedAt", "id", "queuedAt", "reportId", "startedAt", "status", "statusMessage", "triggerMode" ], "type": "object" }, "AgentThreadSummary": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "lastMessageAt": { "format": "date-time", "nullable": true, "type": "string" }, "latestCompletedReportId": { "nullable": true, "type": "string" }, "messageCount": { "type": "integer" }, "preview": { "nullable": true, "type": "string" }, "title": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "createdAt", "id", "lastMessageAt", "latestCompletedReportId", "messageCount", "preview", "title", "updatedAt" ], "type": "object" }, "AgentThreadDetail": { "additionalProperties": false, "allOf": [ { "$ref": "#/components/schemas/AgentThreadSummary" }, { "properties": { "anamnesis": { "additionalProperties": true, "type": "object" }, "gapAssessment": { "additionalProperties": true, "type": "object" }, "messages": { "items": { "$ref": "#/components/schemas/AgentConversationMessage" }, "type": "array" }, "reportStaleness": { "additionalProperties": true, "type": "object" }, "reports": { "items": { "$ref": "#/components/schemas/AgentResearchReportSummary" }, "type": "array" }, "researchRuns": { "items": { "$ref": "#/components/schemas/AgentResearchRunSummary" }, "type": "array" }, "summaryAvailable": { "type": "boolean" }, "summaryMessageCount": { "type": "integer" }, "summaryText": { "nullable": true, "type": "string" } }, "required": [ "anamnesis", "gapAssessment", "messages", "reportStaleness", "reports", "researchRuns", "summaryAvailable", "summaryMessageCount", "summaryText" ], "type": "object" } ] }, "GenericResponse": { "additionalProperties": true, "type": "object" }, "HealthStatus": { "additionalProperties": false, "properties": { "service": { "type": "string" }, "status": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" } }, "required": [ "service", "status", "timestamp" ], "type": "object" }, "PingResponse": { "additionalProperties": false, "properties": { "grantedScopes": { "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "type": "array" }, "ok": { "type": "boolean" }, "supportedRouteGroups": { "items": { "type": "string" }, "type": "array" } }, "required": [ "grantedScopes", "ok", "supportedRouteGroups" ], "type": "object" }, "BillingResponse": { "additionalProperties": false, "properties": { "chatTurnBillingMode": { "const": "fixed", "type": "string" }, "chatTurnMaxReserveCredits": { "type": "number" }, "creditBalance": { "type": "number" }, "currency": { "const": "usd", "type": "string" }, "pricePer100CreditsUsd": { "type": "number" }, "researchRunBillingMode": { "const": "fixed", "type": "string" }, "researchRunPriceCredits": { "type": "number" }, "topUpEndpoint": { "type": "string" }, "topUpOptions": { "items": { "additionalProperties": false, "properties": { "creditQuantity": { "type": "number" }, "usdQuantity": { "type": "number" } }, "required": [ "creditQuantity", "usdQuantity" ], "type": "object" }, "type": "array" }, "topUpScope": { "const": "billing_write", "type": "string" } }, "required": [ "chatTurnBillingMode", "chatTurnMaxReserveCredits", "creditBalance", "currency", "pricePer100CreditsUsd", "researchRunBillingMode", "researchRunPriceCredits", "topUpEndpoint", "topUpOptions", "topUpScope" ], "type": "object" }, "VersionSummary": { "additionalProperties": false, "properties": { "auth": { "type": "string" }, "defaultRoute": { "type": "string" }, "executionModel": { "type": "string" }, "name": { "type": "string" }, "routes": { "items": { "type": "string" }, "type": "array" }, "useCase": { "type": "string" }, "version": { "type": "string" } }, "required": [ "auth", "defaultRoute", "executionModel", "name", "routes", "useCase", "version" ], "type": "object" } } }, "security": [ { "bearerApiKey": [] } ], "paths": { "/health": { "get": { "operationId": "getHealthStatus", "security": [], "summary": "Read service health", "tags": [ "System" ], "responses": { "200": { "description": "Health response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } } } } }, "/v1": { "get": { "operationId": "getVersionSummary", "security": [], "summary": "Read the public API summary", "tags": [ "System" ], "responses": { "200": { "description": "Public route inventory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionSummary" } } } } } } }, "/v1/ping": { "get": { "operationId": "getAuthCheck", "summary": "Validate an API key and read granted capability groups", "tags": [ "System" ], "responses": { "200": { "description": "Authenticated ping result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/billing": { "get": { "operationId": "getBillingState", "summary": "Read current credit balance and billing settings", "tags": [ "Billing" ], "responses": { "200": { "description": "Billing summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "billing_read scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/billing/top-ups": { "post": { "operationId": "createBillingTopUp", "summary": "Create a Stripe-hosted billing top-up session", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingTopUpRequest" } } } }, "responses": { "201": { "description": "Hosted checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid billing request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "billing_write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "503": { "description": "Billing is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys for the authenticated workspace", "tags": [ "API Keys" ], "responses": { "200": { "description": "API key list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "api_keys_admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create a new API key", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "Created API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid API key payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "api_keys_admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/api-keys/{apiKeyId}/rotate": { "post": { "operationId": "rotateApiKey", "summary": "Rotate an existing API key", "tags": [ "API Keys" ], "parameters": [ { "in": "path", "name": "apiKeyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "api_keys_admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/api-keys/{apiKeyId}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke an existing API key", "tags": [ "API Keys" ], "parameters": [ { "in": "path", "name": "apiKeyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "api_keys_admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "404": { "description": "API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/chat/threads": { "get": { "operationId": "listChatThreads", "summary": "List safe chat thread summaries for the authenticated workspace", "tags": [ "Chat" ], "responses": { "200": { "description": "Thread list", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AgentThreadSummary" }, "type": "array" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "threads_read scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } }, "post": { "operationId": "createChatThread", "summary": "Create a new case file by sending the first message", "tags": [ "Chat" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageRequest" } } } }, "responses": { "202": { "description": "Accepted thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "threads_write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "502": { "description": "Chat turn failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/chat/threads/{threadId}": { "get": { "operationId": "getChatThread", "summary": "Read one safe case snapshot", "tags": [ "Chat" ], "parameters": [ { "in": "path", "name": "threadId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentThreadDetail" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "threads_read scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/chat/threads/{threadId}/messages": { "post": { "operationId": "appendChatMessage", "summary": "Append a user message to an existing case file", "tags": [ "Chat" ], "parameters": [ { "in": "path", "name": "threadId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessageRequest" } } } }, "responses": { "202": { "description": "Accepted message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "threads_write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "502": { "description": "Chat turn failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } }, "/v1/chat/threads/{threadId}/research-runs": { "post": { "operationId": "startResearchRun", "summary": "Start an explicit research run for a ready case file", "tags": [ "Chat" ], "parameters": [ { "in": "path", "name": "threadId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRunRequest" } } } }, "responses": { "200": { "description": "Reused matching research result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "202": { "description": "Accepted research run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "403": { "description": "research_write scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "404": { "description": "Thread not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } }, "502": { "description": "Research run failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" } } } } } } } } }