{ "openapi": "3.0.3", "info": { "title": "Starnus Public API", "version": "1.0.0", "description": "The Starnus Public API lets you integrate Starnus AI agents into your own stack. Authenticate with an API key from the Dev Tools page in the dashboard.\n\n**WebSocket URL:** `wss://0vxd7s295f.execute-api.eu-central-1.amazonaws.com/prod`", "contact": { "email": "support@starnustech.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.starnus.com/v1", "description": "Production" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key (sk_live_...)", "description": "API key obtained from the Dev Tools \u2192 API Keys page in your dashboard." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Project not found" }, "status": { "type": "integer", "example": 404 } } } } }, "Profile": { "type": "object", "properties": { "email": { "type": "string", "example": "john.doe@acmecorp.com" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company": { "type": "string", "example": "ACME Corp" }, "credits_remained": { "type": "number", "example": 450.5 }, "tier": { "type": "string", "example": "pro" }, "created_at": { "type": "string", "format": "date-time" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "example": "proj_abc123" }, "name": { "type": "string", "example": "ACME Lead Gen" }, "description": { "type": "string", "example": "Lead generation project for ACME Corp" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Task": { "type": "object", "properties": { "id": { "type": "string", "example": "task_xyz789" }, "project_id": { "type": "string", "example": "proj_abc123" }, "request_id": { "type": "string", "example": "req_a1b2c3d4", "description": "Auto-generated correlation ID for tracking execution" }, "prompt": { "type": "string", "example": "Find 10 CFOs of fintech companies in Germany" }, "mode": { "type": "string", "enum": [ "full", "quick" ], "example": "full" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "example": "completed" }, "file_ids": { "type": "array", "items": { "type": "string" }, "example": [] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Artifact": { "type": "object", "properties": { "id": { "type": "string", "example": "art_1d749beff51f" }, "project_id": { "type": "string", "example": "proj_abc123" }, "name": { "type": "string", "example": "Germany CFO Leads" }, "type": { "type": "string", "enum": [ "database", "document", "image" ], "example": "database" }, "description": { "type": "string", "example": "Verified CFO contacts sourced from LinkedIn" }, "size_bytes": { "type": "integer", "example": 24576 }, "row_count": { "type": "integer", "example": 42 }, "column_count": { "type": "integer", "example": 8 }, "version": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Thread": { "type": "object", "properties": { "id": { "type": "string", "example": "req_a1b2c3d4e5f6" }, "project_id": { "type": "string", "example": "proj_abc123" }, "prompt": { "type": "string", "example": "Find 10 CFOs of fintech companies in Germany" }, "response": { "type": "string", "nullable": true, "example": "I found 10 CFOs matching your criteria and saved them to the artifact." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "awaiting_input" ], "example": "completed" }, "credits_consumed": { "type": "number", "example": 12.5 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "File": { "type": "object", "properties": { "id": { "type": "string", "example": "file_a1b2c3d4" }, "filename": { "type": "string", "example": "Q4_report.pdf" }, "size_bytes": { "type": "integer", "example": 204800 }, "content_type": { "type": "string", "example": "application/pdf" }, "status": { "type": "string", "enum": [ "pending", "ready", "error" ], "example": "ready" }, "created_at": { "type": "string", "format": "date-time" } } }, "Integration": { "type": "object", "properties": { "name": { "type": "string", "example": "linkedin" }, "app_type": { "type": "string", "example": "oauth2" }, "connected": { "type": "boolean", "example": true }, "connected_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Plan": { "type": "object", "properties": { "name": { "type": "string", "example": "Pro" }, "slug": { "type": "string", "example": "pro" }, "price": { "type": "number", "example": 49.0 }, "interval": { "type": "string", "example": "monthly" }, "currency": { "type": "string", "example": "eur" }, "features": { "type": "array", "items": { "type": "string" } } } }, "Balance": { "type": "object", "properties": { "credits_remaining": { "type": "number", "example": 450.5 }, "credits_limit": { "type": "number", "example": 500.0 }, "tier": { "type": "string", "example": "pro" }, "subscription_status": { "type": "string", "example": "active" } } }, "ApiKey": { "type": "object", "properties": { "key_id": { "type": "string", "example": "key_abc123" }, "key_prefix": { "type": "string", "example": "sk_live_qV-z" }, "label": { "type": "string", "example": "Production key" }, "status": { "type": "string", "enum": [ "active", "revoked" ], "example": "active" }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "usage_count": { "type": "integer", "example": 142 } } }, "Trigger": { "type": "object", "properties": { "id": { "type": "string", "example": "trig_abc123" }, "description": { "type": "string", "example": "Run lead gen every Monday at 9am" }, "type": { "type": "string", "enum": [ "schedule", "webhook" ], "example": "schedule" }, "schedule": { "type": "string", "nullable": true, "example": "every Monday at 9am" }, "active": { "type": "boolean", "example": true }, "last_run": { "type": "string", "format": "date-time", "nullable": true }, "next_run": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/me": { "get": { "summary": "Get profile", "description": "Returns the profile for the authenticated API key owner.", "tags": [ "Profile" ], "responses": { "200": { "description": "Profile object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update profile", "description": "Update editable profile fields (first_name, last_name, company).", "tags": [ "Profile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company": { "type": "string", "example": "ACME Corp" } } } } } }, "responses": { "200": { "description": "Updated profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "description": "Unauthorized" } } } }, "/projects": { "get": { "summary": "List projects", "description": "Returns all projects belonging to the authenticated user.", "tags": [ "Projects" ], "responses": { "200": { "description": "Array of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } } } }, "post": { "summary": "Create project", "description": "Create a new project. Projects are containers for tasks, files, and artifacts.", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "ACME Lead Gen", "description": "Project name (required)" }, "description": { "type": "string", "example": "Lead generation for ACME Corp Q2 campaign" } } } } } }, "responses": { "201": { "description": "Created project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Invalid input" } } } }, "/projects/{project_id}": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "proj_abc123" } ], "get": { "summary": "Get project", "tags": [ "Projects" ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "404": { "description": "Not found" } } }, "patch": { "summary": "Update project", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "ACME Lead Gen v2" }, "description": { "type": "string", "example": "Updated description" } } } } } }, "responses": { "200": { "description": "Updated project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } } } }, "delete": { "summary": "Delete project", "description": "Permanently deletes a project and all its associated data.", "tags": [ "Projects" ], "responses": { "204": { "description": "Deleted" } } } }, "/projects/{project_id}/tasks": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "proj_abc123" } ], "get": { "summary": "List tasks", "description": "List execution tasks (jobs sent to the AI supervisor) for a project, most recent first.", "tags": [ "Tasks" ], "responses": { "200": { "description": "Array of tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } } } } } }, "post": { "summary": "Create task (send to supervisor)", "description": "Creates a new agentic task and dispatches it to the Starnus AI supervisor. The supervisor autonomously plans and executes using available agents. A `request_id` is auto-generated and returned \u2014 use it to correlate WebSocket streaming events. Pass `file_ids` to attach previously uploaded files.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "example": "Find 10 CEOs of software companies in the Netherlands and export as a database artifact.", "description": "Natural-language instruction for the AI supervisor (required)." }, "mode": { "type": "string", "enum": [ "full", "quick" ], "default": "full", "description": "'full' = deep multi-agent execution (default); 'quick' = fast single-pass." }, "file_ids": { "type": "array", "items": { "type": "string" }, "example": [ "file_a1b2c3d4" ], "description": "IDs of previously uploaded files to attach (from POST /files/confirm)." }, "integration_names": { "type": "array", "items": { "type": "string" }, "example": [ "linkedin", "gmail" ], "description": "Connected integration names to make available to the supervisor." } } } } } }, "responses": { "201": { "description": "Task created and dispatched to supervisor", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" }, "message": { "type": "string", "example": "Task created successfully" } } } } } }, "400": { "description": "Invalid input" } } } }, "/projects/{project_id}/tasks/{task_id}": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "patch": { "summary": "Update task", "description": "Update task metadata such as description or status.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "Updated prompt text" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] } } } } } }, "responses": { "200": { "description": "Updated task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } } } }, "delete": { "summary": "Delete task", "tags": [ "Tasks" ], "responses": { "204": { "description": "Deleted" } } } }, "/artifacts": { "get": { "summary": "List artifacts", "description": "Returns all artifacts owned by the authenticated user.", "tags": [ "Artifacts" ], "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by project (optional)" } ], "responses": { "200": { "description": "Array of artifacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artifact" } } } } } } } } }, "post": { "summary": "Create artifact", "description": "Create a new artifact manually. Artifacts are also created automatically by the AI supervisor.", "tags": [ "Artifacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "project_id" ], "properties": { "name": { "type": "string", "example": "Q2 Lead Database", "description": "Artifact name (required)" }, "project_id": { "type": "string", "example": "proj_abc123", "description": "Owning project ID (required)" }, "type": { "type": "string", "enum": [ "database", "document", "image" ], "default": "database" }, "description": { "type": "string", "example": "Lead contacts from Q2 campaign" }, "columns": { "type": "array", "items": { "type": "string" }, "example": [ "name", "email", "company", "title" ], "description": "Column names for 'database' type artifacts" } } } } } }, "responses": { "201": { "description": "Created artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } } } } }, "/artifacts/{artifact_id}": { "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "art_1d749beff51f" } ], "get": { "summary": "Get artifact", "description": "Retrieve artifact metadata. Pass `?include_content=true` to also return the rows/content.", "tags": [ "Artifacts" ], "parameters": [ { "name": "include_content", "in": "query", "schema": { "type": "boolean" }, "description": "Include rows/content in response" } ], "responses": { "200": { "description": "Artifact with optional content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } }, "404": { "description": "Not found" } } }, "patch": { "summary": "Update artifact metadata", "description": "Update artifact name, description, or append/replace rows.", "tags": [ "Artifacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Q2 Lead Database (Updated)" }, "description": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Rows to append or replace", "example": [ { "name": "Jane Smith", "email": "jane@acme.com", "company": "ACME Corp", "title": "CEO" } ] } } } } } }, "responses": { "200": { "description": "Updated artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Artifact" } } } } } }, "delete": { "summary": "Delete artifact", "tags": [ "Artifacts" ], "responses": { "204": { "description": "Deleted" } } } }, "/artifacts/{artifact_id}/export": { "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Export artifact", "description": "Generate a presigned download URL for the artifact in the requested format.", "tags": [ "Artifacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "format" ], "properties": { "format": { "type": "string", "enum": [ "xlsx", "csv", "json" ], "example": "xlsx", "description": "Export format: 'xlsx' for Excel, 'csv' for comma-separated, 'json' for raw JSON." } } } } } }, "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "example": "https://s3.amazonaws.com/...presigned..." }, "expires_in": { "type": "integer", "example": 900 } } } } } }, "400": { "description": "Invalid format. Must be one of: xlsx, json, csv" }, "404": { "description": "Artifact not found" } } } }, "/files/upload-url": { "post": { "summary": "Get presigned upload URL", "description": "Step 1 of 2 for file upload. Returns a presigned S3 URL. PUT your file binary to that URL, then confirm with POST /files/confirm.", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename" ], "properties": { "filename": { "type": "string", "example": "Q4_report.pdf", "description": "Original filename including extension (required)" }, "project_id": { "type": "string", "example": "proj_abc123", "description": "Associate with a project (optional)" }, "content_type": { "type": "string", "example": "application/pdf", "description": "MIME type (optional, auto-detected if omitted)" } } } } } }, "responses": { "200": { "description": "Presigned URL and file_id", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": "string", "example": "https://s3.amazonaws.com/...presigned..." }, "file_id": { "type": "string", "example": "file_a1b2c3d4" }, "expires_in": { "type": "integer", "example": 900 } } } } } } } } }, "/files/confirm": { "post": { "summary": "Confirm file upload", "description": "Step 2 of 2. Call after successfully PUTting the file to the presigned URL to mark the file as ready.", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "example": "file_a1b2c3d4", "description": "The file_id returned by POST /files/upload-url (required)" } } } } } }, "responses": { "200": { "description": "Confirmed file metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } } } } }, "/files": { "get": { "summary": "List files", "description": "Returns all uploaded files for the authenticated user.", "tags": [ "Files" ], "responses": { "200": { "description": "Array of files", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } } } } } } } }, "/files/{file_id}/download": { "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get download URL", "description": "Returns a presigned URL to download the file. URL is valid for 15 minutes.", "tags": [ "Files" ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string" }, "expires_in": { "type": "integer", "example": 900 } } } } } }, "404": { "description": "File not found" } } } }, "/projects/{project_id}/threads": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "List execution threads", "description": "Returns execution history (threads) for a project. Each thread corresponds to one supervisor run, with its prompt, response, status, and credit cost.", "tags": [ "Threads" ], "responses": { "200": { "description": "Array of threads", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" } } } } } } } } } }, "/projects/{project_id}/threads/{thread_id}": { "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete thread", "tags": [ "Threads" ], "responses": { "204": { "description": "Deleted" } } } }, "/threads/{thread_id}": { "parameters": [ { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get a single thread", "description": "Retrieve a single execution thread by ID. Requires `project_id` as a query parameter.", "tags": [ "Threads" ], "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Thread" } } } }, "404": { "description": "Not found" } } } }, "/integrations": { "get": { "summary": "List integrations", "description": "Returns all available integrations and their connected status.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Array of integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } } } } }, "/integrations/{name}/connect": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "example": "linkedin" } ], "post": { "summary": "Connect integration (start OAuth)", "description": "Returns an OAuth authorization URL. Redirect your user to this URL to connect the integration.", "tags": [ "Integrations" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "example": "https://your-app.com/oauth/callback" } } } } } }, "responses": { "200": { "description": "OAuth authorization URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_url": { "type": "string" } } } } } } } } }, "/integrations/{name}/disconnect": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Disconnect integration", "tags": [ "Integrations" ], "responses": { "204": { "description": "Disconnected" } } } }, "/integrations/{name}/status": { "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get integration status", "tags": [ "Integrations" ], "responses": { "200": { "description": "Integration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } } } } } }, "/integrations/email": { "post": { "summary": "Add email account", "description": "Connect an email account (Gmail or Outlook) for agents that send/read emails.", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "name", "password", "provider" ], "properties": { "email": { "type": "string", "example": "john.doe@acmecorp.com" }, "name": { "type": "string", "example": "John Doe" }, "password": { "type": "string", "description": "App-specific password (Gmail) or account password (Outlook)" }, "provider": { "type": "string", "enum": [ "gmail", "outlook" ], "example": "gmail" } } } } } }, "responses": { "201": { "description": "Email account added" } } } }, "/integrations/email/{email}": { "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Remove email account", "tags": [ "Integrations" ], "responses": { "204": { "description": "Removed" } } } }, "/billing/plans": { "get": { "summary": "List billing plans", "description": "Returns available subscription plans and their features.", "tags": [ "Billing" ], "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string", "default": "eur", "enum": [ "eur", "usd" ] } } ], "responses": { "200": { "description": "Array of plans", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } } } } } } }, "/billing/balance": { "get": { "summary": "Get credit balance", "description": "Returns current credit balance, tier, and subscription status.", "tags": [ "Billing" ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } } } } }, "/billing/invoices": { "get": { "summary": "List invoices", "tags": [ "Billing" ], "responses": { "200": { "description": "Invoice list" } } } }, "/billing/checkout": { "post": { "summary": "Create checkout session", "description": "Returns a Stripe checkout URL to upgrade to a paid plan.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "pro", "pro_plus", "ultra" ], "example": "pro" }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ], "default": "monthly" } } } } } }, "responses": { "200": { "description": "Stripe checkout URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_url": { "type": "string" } } } } } } } } }, "/billing/upgrade": { "post": { "summary": "Upgrade subscription", "description": "Upgrade an existing subscription to a higher tier.", "tags": [ "Billing" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "pro", "pro_plus", "ultra" ] } } } } } }, "responses": { "200": { "description": "Upgraded" } } } }, "/billing/cancel": { "post": { "summary": "Cancel subscription", "tags": [ "Billing" ], "responses": { "200": { "description": "Subscription cancelled at period end" } } } }, "/billing/activate-trial": { "post": { "summary": "Activate trial", "tags": [ "Billing" ], "responses": { "200": { "description": "Trial activated" } } } }, "/usage": { "get": { "summary": "Get credit usage", "description": "Returns credit usage summary for the current or a specific billing period.", "tags": [ "Usage" ], "parameters": [ { "name": "period", "in": "query", "schema": { "type": "string", "default": "current" }, "description": "'current' for active period, or 'YYYY-MM' for a specific month" } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-03" }, "total_consumed": { "type": "number", "example": 49.5 }, "breakdown": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/triggers": { "get": { "summary": "List triggers", "description": "Returns scheduled and webhook triggers for the authenticated user.", "tags": [ "Triggers" ], "responses": { "200": { "description": "Array of triggers", "content": { "application/json": { "schema": { "type": "object", "properties": { "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" } } } } } } } } }, "post": { "summary": "Create trigger", "description": "Create a scheduled (cron) or webhook trigger that automatically runs a prompt.", "tags": [ "Triggers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "example": "Every Monday at 9am find new leads and append to the Q2 artifact", "description": "Human-readable trigger description (required)" }, "schedule": { "type": "string", "nullable": true, "example": "every Monday at 9am", "description": "Natural-language schedule (leave null for webhook-only triggers)" }, "webhook": { "type": "boolean", "default": false, "description": "If true, also creates a webhook endpoint that can trigger execution" }, "project_id": { "type": "string", "example": "proj_abc123", "description": "Project to associate this trigger with" } } } } } }, "responses": { "201": { "description": "Trigger created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trigger" } } } } } } }, "/triggers/{trigger_id}": { "parameters": [ { "name": "trigger_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete trigger", "tags": [ "Triggers" ], "responses": { "204": { "description": "Deleted" } } } }, "/api-keys": { "get": { "summary": "List API keys", "description": "Returns all API keys (masked). The actual key value is only shown once at creation.", "tags": [ "API Keys" ], "responses": { "200": { "description": "Array of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } } } }, "post": { "summary": "Create API key", "description": "Create a new API key. The plaintext key (`sk_live_...`) is returned once and cannot be retrieved again.", "tags": [ "API Keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "example": "Production \u2014 ACME Corp backend" } } } } } }, "responses": { "201": { "description": "Created key (plaintext shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "example": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" }, "key_id": { "type": "string", "example": "key_abc123" }, "label": { "type": "string" } } } } } } } } }, "/api-keys/{key_id}": { "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Revoke API key", "description": "Immediately revokes the key. Any requests using this key will return 401.", "tags": [ "API Keys" ], "responses": { "204": { "description": "Revoked" } } } }, "/support": { "post": { "summary": "Submit support request", "description": "Submit a support ticket. The team will respond via email.", "tags": [ "Support" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "message" ], "properties": { "subject": { "type": "string", "example": "Task stuck in processing state" }, "message": { "type": "string", "example": "Task task_xyz789 has been in processing for over 10 minutes." }, "category": { "type": "string", "enum": [ "general", "billing", "technical", "feature_request", "bug_report", "other" ], "default": "general" } } } } } }, "responses": { "200": { "description": "Support request submitted" } } } }, "/expert/sessions": { "get": { "summary": "List expert sessions", "tags": [ "Expert" ], "responses": { "200": { "description": "Expert session list" } } }, "post": { "summary": "Request expert session", "description": "Book a session with a Starnus AI expert.", "tags": [ "Expert" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "example": "Setting up automated lead generation" }, "notes": { "type": "string" } } } } } }, "responses": { "201": { "description": "Session booked" } } } }, "/updates": { "get": { "summary": "Get platform updates", "description": "Returns recent platform announcements, feature releases, and notices.", "tags": [ "Updates" ], "responses": { "200": { "description": "Array of platform updates" } } } }, "/updates/{id}/seen": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Mark update as seen", "tags": [ "Updates" ], "responses": { "200": { "description": "Marked as seen" } } } }, "/openapi.json": { "get": { "summary": "OpenAPI specification", "description": "This specification. No authentication required.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.0 specification JSON" } } } } } }