{ "openapi": "3.1.0", "info": { "title": "MightyKey.ai API", "version": "1.0.0", "description": "MightyKey.ai REST API — programmatically create and manage autonomous agent runs, organizations, projects, billing, webhooks, and integrations.", "contact": { "name": "MightyKey API Support", "email": "api@mightykey.ai", "url": "https://mightykey.ai/docs" }, "license": { "name": "Proprietary", "url": "https://mightykey.ai/terms" } }, "servers": [ { "url": "https://mightykey.ai/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "tags": [ { "name": "Auth", "description": "Authentication endpoints (login, register, logout, password reset)" }, { "name": "Runs", "description": "Agent run management — create, list, get, approve, deny, cancel, replay, stream" }, { "name": "Organizations", "description": "Organization management — list, create, get, update, delete" }, { "name": "Projects", "description": "Project management — list, create, get, update, delete, environments" }, { "name": "Billing", "description": "Credit balance, usage tracking, and credit purchases" }, { "name": "Webhooks", "description": "Webhook registration and management" }, { "name": "Integrations", "description": "Third-party integration management" }, { "name": "Export", "description": "GDPR Article 20 data export" } ], "paths": { "/auth/register": { "post": { "tags": ["Auth"], "summary": "Register a new account", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password", "name"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "orgName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Custom organization name (defaults to \"{name}'s Organization\")" } } } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserSummary" }, "organization": { "$ref": "#/components/schemas/OrgSummary" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/auth/login": { "post": { "tags": ["Auth"], "summary": "Log in with email and password", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful (session cookie set)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserSummary" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/logout": { "post": { "tags": ["Auth"], "summary": "Log out (invalidate session)", "operationId": "logout", "security": [{ "sessionCookie": [] }], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "loggedOut": { "type": "boolean" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/forgot-password": { "post": { "tags": ["Auth"], "summary": "Request a password reset email", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } } } } }, "responses": { "200": { "description": "Always returns success to prevent email enumeration", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/auth/reset-password": { "post": { "tags": ["Auth"], "summary": "Reset password using a token", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token", "password"], "properties": { "token": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Password reset successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/runs": { "get": { "tags": ["Runs"], "summary": "List agent runs", "operationId": "listRuns", "parameters": [ { "name": "projectId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by project" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/RunStatus" }, "description": "Filter by status" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated list of runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Runs"], "summary": "Create a new agent run", "operationId": "createRun", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["requestText"], "properties": { "requestText": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "What the agent should do" }, "projectId": { "type": "string", "format": "uuid", "description": "Associate with an existing project" } } } } } }, "responses": { "201": { "description": "Run created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/runs/{id}": { "get": { "tags": ["Runs"], "summary": "Get run detail with events and approvals", "operationId": "getRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RunDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runs/{id}/approve": { "post": { "tags": ["Runs"], "summary": "Approve a pending action", "operationId": "approveRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["approvalId"], "properties": { "approvalId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Approval resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Approval" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runs/{id}/deny": { "post": { "tags": ["Runs"], "summary": "Deny a pending action (cancels the run)", "operationId": "denyRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["approvalId"], "properties": { "approvalId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Approval denied", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Approval" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runs/{id}/cancel": { "post": { "tags": ["Runs"], "summary": "Cancel an active run", "operationId": "cancelRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Run" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runs/{id}/replay": { "get": { "tags": ["Runs"], "summary": "Get replay data for a completed run", "operationId": "getRunReplay", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Replay data", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReplayData" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/runs/{id}/stream": { "get": { "tags": ["Runs"], "summary": "Stream run events via SSE", "operationId": "streamRunEvents", "description": "Server-Sent Events stream for real-time run events. Heartbeat every 15s. Auto-closes on terminal status. Supports Last-Event-ID for reconnection.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string" }, "description": "Resume from a specific event for reconnection" } ], "responses": { "200": { "description": "SSE stream of run events", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Run not found" } } } }, "/orgs": { "get": { "tags": ["Organizations"], "summary": "List user's organizations", "operationId": "listOrgs", "responses": { "200": { "description": "List of organizations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/OrgListItem" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Organizations"], "summary": "Create a new organization", "operationId": "createOrg", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 } } } } } }, "responses": { "201": { "description": "Organization created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/orgs/{id}": { "get": { "tags": ["Organizations"], "summary": "Get organization details", "operationId": "getOrg", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Organizations"], "summary": "Update organization (admin/owner only)", "operationId": "updateOrg", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "autonomyLevel": { "$ref": "#/components/schemas/AutonomyLevel" } } } } } }, "responses": { "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Organizations"], "summary": "Delete organization (owner only)", "operationId": "deleteOrg", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/projects": { "get": { "tags": ["Projects"], "summary": "List projects", "operationId": "listProjects", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/ProjectStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Paginated list of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Projects"], "summary": "Create a new project", "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 5000 }, "githubRepoUrl": { "type": "string", "format": "uri", "maxLength": 1000 } } } } } }, "responses": { "201": { "description": "Project created with default environments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/projects/{id}": { "get": { "tags": ["Projects"], "summary": "Get project details", "operationId": "getProject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Projects"], "summary": "Update a project", "operationId": "updateProject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 5000 }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "githubRepoUrl": { "type": ["string", "null"], "format": "uri", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Projects"], "summary": "Delete a project", "operationId": "deleteProject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/projects/{id}/environments": { "get": { "tags": ["Projects"], "summary": "List project environments", "operationId": "listProjectEnvironments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of project environments", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectEnvironment" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/billing/balance": { "get": { "tags": ["Billing"], "summary": "Get credit balance", "operationId": "getCreditBalance", "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creditBalance": { "type": "string" }, "subscriptionTier": { "$ref": "#/components/schemas/SubscriptionTier" }, "currency": { "type": "string", "example": "USD" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/billing/usage": { "get": { "tags": ["Billing"], "summary": "Get usage summary and recent events", "operationId": "getUsage", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "description": "Lookback period in days" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Max recent events to return" } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UsageResponse" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/billing/credits": { "post": { "tags": ["Billing"], "summary": "Purchase credits", "operationId": "purchaseCredits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["amount"], "properties": { "amount": { "type": "number", "minimum": 5, "maximum": 10000, "description": "Dollar amount ($5–$10,000)" }, "paymentMethodId": { "type": "string", "description": "Stripe payment method ID" } } } } } }, "responses": { "201": { "description": "Credits purchased", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "purchase": { "type": "object", "properties": { "id": { "type": "string" }, "amountPaid": { "type": "string" }, "creditsGranted": { "type": "string" }, "stripePaymentIntentId": { "type": "string" } } }, "message": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhooks", "operationId": "listWebhooks", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Webhooks"], "summary": "Register a new webhook", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "events"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1 }, "description": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "201": { "description": "Webhook created (includes signing secret)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks/{id}": { "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/integrations": { "get": { "tags": ["Integrations"], "summary": "List integrations", "operationId": "listIntegrations", "responses": { "200": { "description": "List of integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Integrations"], "summary": "Connect an integration", "operationId": "connectIntegration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["provider"], "properties": { "provider": { "$ref": "#/components/schemas/IntegrationProvider" }, "authMethod": { "$ref": "#/components/schemas/IntegrationAuthMethod" }, "config": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "Integration connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/integrations/{id}": { "delete": { "tags": ["Integrations"], "summary": "Disconnect an integration", "operationId": "disconnectIntegration", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Integration disconnected", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" }, "provider": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/export": { "get": { "tags": ["Export"], "summary": "Export all user/org data (GDPR Article 20)", "operationId": "exportData", "responses": { "200": { "description": "JSON data export file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExport" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=\"mightykey-export-...json\"" } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (starts with `mk_live_` or `mk_test_`). Pass as `Authorization: Bearer mk_live_...`" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "mk_session", "description": "Session cookie set by POST /auth/login" } }, "schemas": { "RunStatus": { "type": "string", "enum": ["intake", "clarify", "scope", "plan", "build", "verify", "deploy", "monitor", "completed", "failed", "cancelled"] }, "AutonomyLevel": { "type": "string", "enum": ["observe", "assist", "act", "autopilot"] }, "SubscriptionTier": { "type": "string", "enum": ["free", "starter", "pro", "business", "enterprise"] }, "ProjectStatus": { "type": "string", "enum": ["active", "paused", "archived"] }, "IntegrationProvider": { "type": "string", "enum": ["github", "neon", "vercel", "cloudflare", "stripe", "slack", "custom_mcp"] }, "IntegrationAuthMethod": { "type": "string", "enum": ["oauth", "api_key", "phantom_token"] }, "WebhookEventType": { "type": "string", "enum": ["run.created", "run.stage_changed", "run.completed", "run.failed", "run.cancelled", "approval.requested", "approval.resolved", "credit.low", "credit.purchased", "project.created", "project.deleted", "member.invited", "member.removed"] }, "UserSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } }, "OrgSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "OrgListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "subscriptionTier": { "$ref": "#/components/schemas/SubscriptionTier" }, "autonomyLevel": { "$ref": "#/components/schemas/AutonomyLevel" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logoUrl": { "type": ["string", "null"] }, "subscriptionTier": { "$ref": "#/components/schemas/SubscriptionTier" }, "stripeCustomerId": { "type": ["string", "null"] }, "stripeSubscriptionId": { "type": ["string", "null"] }, "settings": { "type": "object" }, "constitutionVersion": { "type": "integer" }, "autonomyLevel": { "$ref": "#/components/schemas/AutonomyLevel" }, "creditBalance": { "type": "string" }, "maxSeats": { "type": "integer" }, "isActive": { "type": "boolean" }, "suspendedAt": { "type": ["string", "null"], "format": "date-time" }, "suspendedReason": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "role": { "type": "string", "description": "The authenticated user's role in this org" } } }, "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "projectId": { "type": ["string", "null"], "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/RunStatus" }, "stageStartedAt": { "type": ["string", "null"], "format": "date-time" }, "stageHistory": { "type": "array", "items": { "$ref": "#/components/schemas/StageHistoryEntry" } }, "requestText": { "type": "string" }, "scopeArtifact": { "type": ["object", "null"] }, "planArtifact": { "type": ["object", "null"] }, "totalCreditsUsed": { "type": "string" }, "totalTokensInput": { "type": "integer" }, "totalTokensOutput": { "type": "integer" }, "parentRunId": { "type": ["string", "null"], "format": "uuid" }, "modelUsed": { "type": ["string", "null"] }, "errorMessage": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" } } }, "RunDetail": { "allOf": [ { "$ref": "#/components/schemas/Run" }, { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/RunEvent" } }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } } } } ] }, "RunEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "sequenceNumber": { "type": "integer" }, "eventType": { "type": "string", "enum": ["tool_call", "tool_result", "message", "approval_requested", "approval_granted", "approval_denied", "error", "stage_transition", "artifact_created", "rollback_created", "cost_update"] }, "data": { "type": "object" }, "modelUsed": { "type": ["string", "null"] }, "tokensUsed": { "type": ["integer", "null"] }, "replayVisible": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "eventId": { "type": ["string", "null"], "format": "uuid" }, "actionSummary": { "type": "string" }, "reason": { "type": "string" }, "riskDescription": { "type": ["string", "null"] }, "costEstimate": { "type": ["string", "null"] }, "undoPlan": { "type": ["string", "null"] }, "evidence": { "type": ["object", "null"] }, "status": { "type": "string", "enum": ["pending", "approved", "denied", "auto_approved", "expired"] }, "decidedBy": { "type": ["string", "null"], "format": "uuid" }, "policyRuleId": { "type": ["string", "null"], "format": "uuid" }, "decidedAt": { "type": ["string", "null"], "format": "date-time" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "StageHistoryEntry": { "type": "object", "properties": { "stage": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" } } }, "ReplayData": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RunStatus" }, "requestText": { "type": "string" }, "totalCreditsUsed": { "type": "string" }, "totalTokensInput": { "type": "integer" }, "totalTokensOutput": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" }, "stageHistory": { "type": "array", "items": { "$ref": "#/components/schemas/StageHistoryEntry" } } } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/RunEvent" } }, "eventCount": { "type": "integer" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": ["string", "null"] }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "githubRepoUrl": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ProjectEnvironment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["active", "inactive", "deploying", "failed"] }, "lastDeployedAt": { "type": ["string", "null"], "format": "date-time" }, "healthStatus": { "type": ["string", "null"], "enum": ["healthy", "degraded", "down", "unknown", null] }, "healthCheckedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "description": { "type": ["string", "null"] }, "isActive": { "type": "boolean" }, "failCount": { "type": "integer" }, "lastTriggeredAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookWithSecret": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "HMAC-SHA256 signing secret (shown only once at creation)" } } } ] }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "$ref": "#/components/schemas/IntegrationProvider" }, "status": { "type": "string", "enum": ["connected", "disconnected", "error"] }, "authMethod": { "type": ["string", "null"], "enum": ["oauth", "api_key", "phantom_token", null] }, "config": { "type": ["object", "null"] }, "connectedAt": { "type": ["string", "null"], "format": "date-time" }, "lastVerifiedAt": { "type": ["string", "null"], "format": "date-time" }, "errorMessage": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" } } }, "UsageResponse": { "type": "object", "properties": { "period": { "type": "object", "properties": { "days": { "type": "integer" }, "since": { "type": "string", "format": "date-time" } } }, "summary": { "type": "object", "properties": { "totalCreditsCharged": { "type": "string" }, "totalEvents": { "type": "integer" }, "totalTokensInput": { "type": "integer" }, "totalTokensOutput": { "type": "integer" } } }, "recentEvents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "modelUsed": { "type": ["string", "null"] }, "tokensInput": { "type": ["integer", "null"] }, "tokensOutput": { "type": ["integer", "null"] }, "creditsCharged": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "DataExport": { "type": "object", "properties": { "exportedAt": { "type": "string", "format": "date-time" }, "format": { "type": "string" }, "user": { "type": "object" }, "organization": { "type": "object" }, "members": { "type": "array", "items": { "type": "object" } }, "projects": { "type": "array", "items": { "type": "object" } }, "agentRuns": { "type": "array", "items": { "type": "object" } }, "creditLedger": { "type": "array", "items": { "type": "object" } }, "auditLog": { "type": "array", "items": { "type": "object" } } } } }, "responses": { "BadRequest": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "Unauthorized": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Insufficient permissions" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not found" } } } } } }, "Conflict": { "description": "Resource already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "Deleted": { "description": "Resource deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "id": { "type": "string" } } } } } } } } } } }