{ "openapi": "3.1.0", "info": { "title": "Maneuvr API", "version": "1.0.0", "description": "Workspace-scoped competitive-intelligence API. All endpoints return a `{ data, error, meta }` envelope. Authenticate with a Bearer API key (`mk_live_...`). For real-time updates, subscribe to webhooks. For AI assistants, point Claude or Cursor at `/api/v1/mcp` (Streamable HTTP MCP).", "contact": { "name": "Maneuvr", "url": "https://maneuvr.app" } }, "servers": [ { "url": "https://maneuvr.app", "description": "Current host" } ], "tags": [ { "name": "Entities", "description": "Tracked competitors and accounts" }, { "name": "Events", "description": "Competitor signals and the impact briefs that go with them" }, { "name": "Battlecards", "description": "Per-entity sales enablement content" }, { "name": "Runs", "description": "Research / refresh runs" }, { "name": "Digests", "description": "Periodic competitive briefings" }, { "name": "Webhooks", "description": "Outbound HTTP notifications" }, { "name": "MCP", "description": "Model Context Protocol server for AI assistants" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (mk_live_...) or Supabase JWT", "description": "Pass `Authorization: Bearer ` with either a workspace API key (`mk_live_...`) or a Supabase access token from the in-app session. API keys are scope-gated; JWT users inherit their workspace role." } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "Forbidden": { "description": "Token is missing the required scope or role", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "NotFound": { "description": "No resource matched in this workspace", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "Validation": { "description": "Request body or query failed validation", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "RateLimited": { "description": "Rate limit exceeded. Inspect `X-RateLimit-Reset` for the next allowed time.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } }, "schemas": { "Meta": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "string" } } }, "PagedMeta": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "string" }, "page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] } } } } }, "Entity": { "type": "object", "required": [ "id", "slug", "name", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "tier": { "type": "integer", "minimum": 1, "maximum": 3 }, "is_self": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EntityCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 120 }, "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,50}$" }, "website": { "type": [ "string", "null" ], "maxLength": 2048 }, "category": { "type": [ "string", "null" ], "maxLength": 120 }, "tier": { "type": "integer", "minimum": 1, "maximum": 3 }, "notes": { "type": [ "string", "null" ], "maxLength": 4000 } } }, "Event": { "type": "object", "required": [ "id", "entity_id", "type", "title", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "entity_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "e.g. launch, pricing, hire, messaging.shift" }, "title": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "event_date": { "type": [ "string", "null" ], "format": "date" }, "importance": { "type": "number", "minimum": 0, "maximum": 1 }, "source": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object" } }, "impact": { "type": [ "object", "null" ], "description": "So-what brief (when generated)", "properties": { "deal_relevance": { "type": "number", "minimum": 0, "maximum": 10 }, "summary": { "type": "string" }, "recommended_actions": { "type": "array", "items": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" } } }, "EventIngest": { "type": "object", "required": [ "entity_id", "type", "title" ], "properties": { "entity_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "maxLength": 80 }, "title": { "type": "string", "maxLength": 280 }, "summary": { "type": "string", "maxLength": 4000 }, "url": { "type": "string", "format": "uri" }, "event_date": { "type": "string", "format": "date" }, "importance": { "type": "number", "minimum": 0, "maximum": 1 } } }, "DealOutcome": { "type": "object", "required": [ "id", "outcome", "close_date", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "won", "lost", "no_decision" ] }, "primary_competitor_id": { "type": [ "string", "null" ], "format": "uuid" }, "competitors_considered": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "segment": { "type": [ "string", "null" ], "enum": [ "smb", "mid_market", "enterprise", null ] }, "region": { "type": [ "string", "null" ] }, "deal_size": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "close_date": { "type": "string", "format": "date" }, "reason_codes": { "type": "array", "items": { "type": "string", "enum": [ "price", "missing_feature", "messaging_positioning", "integration_gap", "relationship_incumbent", "timing_no_budget", "lost_to_status_quo", "product_maturity", "other" ] } }, "notes": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "manual", "api", "document" ] }, "linked_document_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "id": "8f0e3b1c-2a1d-4c2f-9c2a-2e6c8a1b2c3d", "label": "Acme Corp — Q1 renewal", "outcome": "lost", "primary_competitor_id": "11111111-2222-3333-4444-555555555555", "competitors_considered": [], "segment": "mid_market", "region": "NA", "deal_size": 48000, "currency": "USD", "close_date": "2026-03-31", "reason_codes": [ "price", "missing_feature" ], "notes": "Lost on annual pricing; asked for SSO add-on", "source": "api", "linked_document_id": null, "created_at": "2026-04-01T10:00:00Z" } }, "DealOutcomeIngest": { "type": "object", "required": [ "outcome", "close_date" ], "properties": { "label": { "type": "string", "maxLength": 160, "description": "Internal nickname (avoid PII)" }, "outcome": { "type": "string", "enum": [ "won", "lost", "no_decision" ] }, "primary_competitor_id": { "type": "string", "format": "uuid" }, "competitors_considered": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 }, "segment": { "type": "string", "enum": [ "smb", "mid_market", "enterprise" ] }, "region": { "type": "string", "maxLength": 80 }, "deal_size": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 3, "maxLength": 8 }, "close_date": { "type": "string", "format": "date" }, "reason_codes": { "type": "array", "description": "Required when outcome is lost or no_decision", "items": { "type": "string", "enum": [ "price", "missing_feature", "messaging_positioning", "integration_gap", "relationship_incumbent", "timing_no_budget", "lost_to_status_quo", "product_maturity", "other" ] } }, "notes": { "type": "string", "maxLength": 4000 }, "source": { "type": "string", "enum": [ "manual", "api", "document" ], "default": "api" }, "linked_document_id": { "type": "string", "format": "uuid" } }, "example": { "label": "Acme Corp — Q1 renewal", "outcome": "lost", "primary_competitor_id": "11111111-2222-3333-4444-555555555555", "segment": "mid_market", "deal_size": 48000, "currency": "USD", "close_date": "2026-03-31", "reason_codes": [ "price", "missing_feature" ], "notes": "Lost on annual pricing; asked for SSO add-on" } }, "Battlecard": { "type": "object", "properties": { "entity_id": { "type": "string", "format": "uuid" }, "positioning": { "type": [ "string", "null" ] }, "strengths": { "type": [ "array", "null" ], "items": { "type": "string" } }, "weaknesses": { "type": [ "array", "null" ], "items": { "type": "string" } }, "why_we_win": { "type": [ "array", "null" ], "items": { "type": "string" } }, "why_we_lose": { "type": [ "array", "null" ], "items": { "type": "string" } }, "objection_handling": { "type": [ "array", "null" ], "items": { "type": "object" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Run": { "type": "object", "required": [ "id", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "stats": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Digest": { "type": "object", "required": [ "id", "kind", "digest_date", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "daily", "weekly" ] }, "digest_date": { "type": "string", "format": "date" }, "summary": { "type": "string" }, "markdown": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookSubscription": { "type": "object", "required": [ "id", "url", "event_types", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "entity.created", "entity.updated", "event.created", "event.impact_generated", "run.started", "run.completed", "run.failed", "battlecard.updated", "digest.published", "deal_outcome.created", "deal_outcome.updated", "*" ] } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionCreate": { "type": "object", "required": [ "url", "event_types" ], "properties": { "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 200 } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "dead" ] }, "attempt": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_body_snippet": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookPayload": { "type": "object", "description": "Body posted to subscriber URLs. Verify with `X-Maneuvr-Signature`.", "required": [ "id", "type", "workspace_id", "occurred_at", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "entity.created", "entity.updated", "event.created", "event.impact_generated", "run.started", "run.completed", "run.failed", "battlecard.updated", "digest.published", "deal_outcome.created", "deal_outcome.updated" ] }, "workspace_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "links": { "type": "object", "properties": { "self": { "type": "string" } } } } } } } } }, "paths": { "/api/v1/entities": { "get": { "operationId": "listEntities", "tags": [ "Entities" ], "summary": "List entities", "security": [ { "bearerAuth": [ "read:entities" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createEntity", "tags": [ "Entities" ], "summary": "Create an entity", "security": [ { "bearerAuth": [ "write:entities" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Replay-safe key (recommended)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Entity" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "409": { "description": "Slug conflict", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "null" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "validation", "rate_limited", "conflict", "internal" ] }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "422": { "$ref": "#/components/responses/Validation" } } } }, "/api/v1/entities/{id}": { "get": { "operationId": "getEntity", "tags": [ "Entities" ], "summary": "Get an entity", "security": [ { "bearerAuth": [ "read:entities" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Entity" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateEntity", "tags": [ "Entities" ], "summary": "Update an entity", "security": [ { "bearerAuth": [ "write:entities" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCreate" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Entity" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "archiveEntity", "tags": [ "Entities" ], "summary": "Archive an entity", "security": [ { "bearerAuth": [ "write:entities" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archived" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/entities/{id}/autofill": { "post": { "operationId": "autofillEntity", "tags": [ "Entities" ], "summary": "Auto-discover sources and seed signals", "security": [ { "bearerAuth": [ "write:entities" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Run started" } } } }, "/api/v1/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events (newest first)", "security": [ { "bearerAuth": [ "read:events" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/events/{id}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Get an event with impact brief", "security": [ { "bearerAuth": [ "read:events" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Event" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/events:ingest": { "post": { "operationId": "ingestEvent", "tags": [ "Events" ], "summary": "Ingest a competitor signal", "security": [ { "bearerAuth": [ "write:events" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventIngest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Event" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/v1/deal-outcomes": { "get": { "operationId": "listDealOutcomes", "tags": [ "Deal outcomes" ], "summary": "List deal outcomes (newest close first)", "security": [ { "bearerAuth": [ "read:deal_outcomes" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DealOutcome" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createDealOutcome", "tags": [ "Deal outcomes" ], "summary": "Log a won, lost, or no-decision deal", "security": [ { "bearerAuth": [ "write:deal_outcomes" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealOutcomeIngest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DealOutcome" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "422": { "description": "Validation error (invalid reason code, competitor not in workspace, etc.)" } } } }, "/api/v1/deal-outcomes/{id}": { "get": { "operationId": "getDealOutcome", "tags": [ "Deal outcomes" ], "summary": "Get a deal outcome", "security": [ { "bearerAuth": [ "read:deal_outcomes" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DealOutcome" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/battlecards/{entityId}": { "get": { "operationId": "getBattlecard", "tags": [ "Battlecards" ], "summary": "Get the battlecard for an entity", "security": [ { "bearerAuth": [ "read:battlecards" ] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Battlecard" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/battlecards/{entityId}/regenerate": { "post": { "operationId": "regenerateBattlecard", "tags": [ "Battlecards" ], "summary": "Regenerate a battlecard from latest signals", "security": [ { "bearerAuth": [ "write:entities" ] } ], "parameters": [ { "name": "entityId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Regeneration started" } } } }, "/api/v1/runs": { "get": { "operationId": "listRuns", "tags": [ "Runs" ], "summary": "List recent research runs", "security": [ { "bearerAuth": [ "read:runs" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "triggerRun", "tags": [ "Runs" ], "summary": "Kick off a new research run", "security": [ { "bearerAuth": [ "write:runs" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "202": { "description": "Run accepted" } } } }, "/api/v1/runs/{id}": { "get": { "operationId": "getRun", "tags": [ "Runs" ], "summary": "Get a run by id", "security": [ { "bearerAuth": [ "read:runs" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Run" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/digests": { "get": { "operationId": "listDigests", "tags": [ "Digests" ], "summary": "List digests", "security": [ { "bearerAuth": [ "read:digests" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Digest" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/digests/{id}": { "get": { "operationId": "getDigest", "tags": [ "Digests" ], "summary": "Get a digest", "security": [ { "bearerAuth": [ "read:digests" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Digest" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List subscriptions", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a prior `meta.page.next_cursor`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Create a subscription (returns signing secret once)", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreate" } } } }, "responses": { "201": { "description": "Created. `secret` is shown only on creation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscription" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Get a subscription", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Pause, resume, or change a subscription", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] }, "event_types": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a subscription", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List recent delivery attempts", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "error": { "type": "null" }, "meta": { "$ref": "#/components/schemas/PagedMeta" } } } } } } } } }, "/api/v1/webhooks/deliveries/{deliveryId}/replay": { "post": { "operationId": "replayWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Replay a failed delivery", "security": [ { "bearerAuth": [ "admin:webhooks" ] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Requeued" } } } }, "/api/v1/mcp": { "post": { "operationId": "mcpStreamableHttp", "tags": [ "MCP" ], "summary": "Model Context Protocol — Streamable HTTP transport", "description": "Stateless JSON-RPC endpoint. Send MCP `initialize`, `tools/list`, and `tools/call` requests. See `/docs/api` → MCP for client config.", "security": [ { "bearerAuth": [ "mcp:read", "mcp:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response (json or text/event-stream)" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } } }