{ "openapi": "3.1.0", "info": { "title": "markus API", "version": "1.0.0", "description": "markus — the ai marketer. manage campaigns, contacts, conversations, content generation, analytics, and more.", "contact": { "name": "markus", "url": "https://markusai.dev" } }, "servers": [ { "url": "https://markusai.dev/api/v1", "description": "production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "authentication", "description": "verify your API key and view its metadata." }, { "name": "API keys", "description": "programmatically manage API keys." }, { "name": "campaigns", "description": "create and manage outreach campaigns." }, { "name": "contacts", "description": "manage contacts and import leads." }, { "name": "conversations", "description": "manage conversations across all channels." }, { "name": "messages", "description": "manage message approval workflow and sending." }, { "name": "AI", "description": "AI-powered content generation and analysis." }, { "name": "discovery", "description": "search for and discover new contacts." }, { "name": "analytics", "description": "campaign performance metrics and reporting." }, { "name": "billing", "description": "view billing plans and subscription information." }, { "name": "channels", "description": "manage connected accounts and multi-channel messaging." }, { "name": "notifications", "description": "manage user notifications." }, { "name": "webhooks", "description": "manage webhook endpoints for receiving real-time event notifications." }, { "name": "agent credits", "description": "credit-based payments for AI agents using x402 (USDC on Base) or MPP (Stripe). 1 credit = 1 campaign (30 contacts, 300 messages, 50 AI generations). no subscription required." } ], "paths": { "/api/v1/keys/me": { "get": { "tags": [ "authentication" ], "summary": "get information about the currently authenticated API key", "operationId": "getCurrentKey", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "id": "uuid", "name": "production", "key_prefix": "mk_live_a1b2c3d4", "scopes": [ "*" ], "last_used_at": "2024-01-15T10:30:00Z", "is_active": true } } } } } } } }, "/api/v1/keys": { "get": { "tags": [ "API keys" ], "summary": "list all API keys for your account", "operationId": "listKeys", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "uuid", "name": "production", "key_prefix": "mk_live_a1b2c3d4", "scopes": [ "*" ], "is_active": true, "last_used_at": "2024-01-15T10:30:00Z" } ], "meta": { "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } } ] }, "post": { "tags": [ "API keys" ], "summary": "create a new API key. the raw key is only returned once.", "operationId": "createKeys", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "id": "uuid", "name": "staging", "key_prefix": "mk_live_e5f6g7h8", "key": "mk_live_e5f6g7h8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o3p4", "scopes": [ "campaigns:read", "contacts:read" ], "is_active": true } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "key name (1-100 characters)" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "permission scopes (e.g. [\"campaigns:read\", \"contacts:write\"]). defaults to [\"*\"] for full access" }, "expires_at": { "type": "string", "format": "date-time", "description": "optional expiration date" } }, "required": [ "name" ] } } } }, "description": "the raw key value is only returned on creation — store it securely" } }, "/api/v1/keys/{id}": { "delete": { "tags": [ "API keys" ], "summary": "revoke an API key. this action is irreversible.", "operationId": "deleteKey", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "APIKEY_001: API key not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/campaigns": { "get": { "tags": [ "campaigns" ], "summary": "list all campaigns", "operationId": "listCampaigns", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "uuid", "name": "Q1 outreach", "objective_type": "product_promotion", "status": "active", "total_contacts": 150, "contacts_reached": 42, "responses_received": 8, "created_at": "2024-01-15T10:30:00Z" } ], "meta": { "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } } } } } }, "x-scope": "campaigns:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } }, { "name": "status", "in": "query", "required": false, "description": "filter by status (draft, active, paused, completed)", "schema": { "type": "string" } } ] }, "post": { "tags": [ "campaigns" ], "summary": "create a new campaign", "operationId": "createCampaigns", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "id": "uuid", "name": "spring outreach", "objective_type": "product_promotion", "status": "draft", "created_at": "2024-01-15T10:30:00Z" } } } } }, "402": { "description": "PAY_005: insufficient credits (1 credit required) — purchase credits at POST /api/v1/agent/credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "CAMP_009: campaign limit reached for billing period", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "campaign name" }, "objective_type": { "type": "string", "enum": [ "venue_dj", "venue_host", "product_promotion", "custom" ], "description": "campaign objective type" }, "product_name": { "type": "string", "description": "product name (for product_promotion objective)" }, "product_url": { "type": "string", "format": "uri", "description": "product URL for AI analysis" }, "product_description": { "type": "string", "description": "product description for AI context" } }, "required": [ "name", "objective_type" ] } } } }, "description": "agents: 1 credit per campaign. buy credits at POST /api/v1/agent/credits." } }, "/api/v1/campaigns/{id}": { "get": { "tags": [ "campaigns" ], "summary": "get a specific campaign with full details", "operationId": "getCampaign", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "patch": { "tags": [ "campaigns" ], "summary": "update a campaign", "operationId": "updateCampaign", "responses": { "200": { "description": "success" }, "400": { "description": "CAMP_008: invalid status transition", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "campaign name" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "completed" ], "description": "campaign status" }, "product_name": { "type": "string", "description": "product name" }, "product_url": { "type": "string", "format": "uri", "description": "product URL" } } } } } } }, "delete": { "tags": [ "campaigns" ], "summary": "soft-delete a campaign (sets status to 'deleted')", "operationId": "deleteCampaign", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/campaigns/{id}/contacts": { "get": { "tags": [ "campaigns" ], "summary": "list contacts in a campaign", "operationId": "listCampaignContacts", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" }, { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } }, { "name": "status", "in": "query", "required": false, "description": "filter by contact status", "schema": { "type": "string" } } ] } }, "/api/v1/campaigns/{id}/usage": { "get": { "tags": [ "campaigns" ], "summary": "get campaign usage statistics", "operationId": "getCampaignUsage", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "total_contacts": 150, "contacts_reached": 42, "responses_received": 8, "emails_sent": 42, "emails_opened": 28, "emails_clicked": 12 } } } } }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/campaigns/{id}/analyze": { "post": { "tags": [ "campaigns" ], "summary": "trigger AI product analysis for a campaign", "operationId": "analyzeCampaign", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "AI_004: AI rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "description": "analyzes the campaign's product URL/description and generates target profiles\n\nreturns immediately — analysis runs asynchronously" } }, "/api/v1/campaigns/{id}/target-profiles": { "get": { "tags": [ "campaigns" ], "summary": "list target profiles for a campaign", "operationId": "listTargetProfiles", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "uuid", "campaign_id": "uuid", "name": "SaaS founders", "profile_type": "b2b_professional", "fit_score": 0.85, "job_titles": [ "CEO", "CTO", "founder" ], "industries": [ "technology", "SaaS" ], "discovery_keywords": [ "saas founder", "tech startup" ], "recommended_channels": [ "email", "linkedin" ] } ] } } } }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "post": { "tags": [ "campaigns" ], "summary": "create a target profile for a campaign", "operationId": "createTargetProfile", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "profile name" }, "profile_type": { "type": "string", "enum": [ "local_business", "content_creator", "influencer", "b2b_professional", "ecommerce", "saas_company", "agency", "freelancer", "other" ], "description": "target profile type" }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "target job titles" }, "industries": { "type": "array", "items": { "type": "string" }, "description": "target industries" }, "discovery_keywords": { "type": "array", "items": { "type": "string" }, "description": "keywords for contact discovery" }, "recommended_channels": { "type": "array", "items": { "type": "string" }, "description": "recommended outreach channels" } }, "required": [ "name", "profile_type" ] } } } } } }, "/api/v1/campaigns/{id}/target-profiles/{profileId}": { "delete": { "tags": [ "campaigns" ], "summary": "delete a target profile", "operationId": "deleteTargetProfile", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "CAMP_001: campaign or profile not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "campaigns:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" }, { "name": "profileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "profileId" } ] } }, "/api/v1/contacts": { "get": { "tags": [ "contacts" ], "summary": "list all contacts", "operationId": "listContacts", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "uuid", "email": "jane@example.com", "first_name": "Jane", "last_name": "Smith", "company_name": "Acme Inc", "tags": [ "lead", "enterprise" ] } ], "meta": { "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } } } } } }, "x-scope": "contacts:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } }, { "name": "search", "in": "query", "required": false, "description": "search by name or email", "schema": { "type": "string" } } ] }, "post": { "tags": [ "contacts" ], "summary": "create a single contact", "operationId": "createContacts", "responses": { "200": { "description": "success" }, "409": { "description": "CONT_002: duplicate contact email", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "CONT_009: contact limit reached for billing period", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "contact email" }, "first_name": { "type": "string", "description": "first name" }, "last_name": { "type": "string", "description": "last name" }, "company_name": { "type": "string", "description": "company name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "tags for categorization" }, "campaign_id": { "type": "string", "format": "uuid", "description": "campaign to associate with" } }, "required": [ "email" ] } } } } } }, "/api/v1/contacts/{id}": { "get": { "tags": [ "contacts" ], "summary": "get a specific contact", "operationId": "getContact", "responses": { "200": { "description": "success" }, "404": { "description": "CONT_001: contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "patch": { "tags": [ "contacts" ], "summary": "update a contact", "operationId": "updateContact", "responses": { "200": { "description": "success" }, "404": { "description": "CONT_001: contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "first name" }, "last_name": { "type": "string", "description": "last name" }, "company_name": { "type": "string", "description": "company name" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "tags" } } } } } } }, "delete": { "tags": [ "contacts" ], "summary": "soft-delete a contact (sets deleted_at timestamp)", "operationId": "deleteContact", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "CONT_001: contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/contacts/bulk": { "post": { "tags": [ "contacts" ], "summary": "bulk import contacts (up to 500 per request)", "operationId": "bulkMessageAction", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "imported": 48, "skipped": 2, "errors": [] } } } } }, "429": { "description": "CONT_009: contact limit reached for billing period", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "description": "array of contact objects (email required, first_name/last_name/company_name optional)" }, "campaign_id": { "type": "string", "format": "uuid", "description": "campaign to associate contacts with" } }, "required": [ "contacts" ] } } } }, "description": "duplicates are skipped by email. max 500 contacts per request." } }, "/api/v1/contacts/usage": { "get": { "tags": [ "contacts" ], "summary": "get contact usage for the current billing period", "operationId": "getContactUsage", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "used": 150, "limit": 1000, "remaining": 850, "billing_period_start": "2024-01-01T00:00:00Z", "billing_period_end": "2024-02-01T00:00:00Z" } } } } } }, "x-scope": "contacts:read" } }, "/api/v1/contacts/{id}/conversations": { "get": { "tags": [ "contacts" ], "summary": "get conversations for a specific contact", "operationId": "listContactConversations", "responses": { "200": { "description": "success" }, "404": { "description": "CONT_001: contact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "contacts:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/conversations": { "get": { "tags": [ "conversations" ], "summary": "list all conversations", "operationId": "listConversations", "responses": { "200": { "description": "success" } }, "x-scope": "conversations:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } }, { "name": "status", "in": "query", "required": false, "description": "filter by status (active, completed, failed, human_review)", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "filter by campaign", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/conversations/{id}": { "get": { "tags": [ "conversations" ], "summary": "get a conversation with details", "operationId": "getConversation", "responses": { "200": { "description": "success" }, "404": { "description": "CONV_001: conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "conversations:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/conversations/{id}/messages": { "get": { "tags": [ "conversations" ], "summary": "get messages for a conversation", "operationId": "listConversationMessages", "responses": { "200": { "description": "success" }, "404": { "description": "CONV_001: conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "conversations:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/conversations/{id}/read": { "post": { "tags": [ "conversations" ], "summary": "mark a conversation as read", "operationId": "markConversationRead", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "CONV_001: conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "conversations:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/conversations/engagement": { "get": { "tags": [ "conversations" ], "summary": "get engagement metrics across conversations", "operationId": "getEngagement", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "total_conversations": 250, "active_conversations": 42, "response_rate": 0.28, "avg_response_time_hours": 4.5 } } } } } }, "x-scope": "conversations:read" } }, "/api/v1/messages/pending": { "get": { "tags": [ "messages" ], "summary": "list messages pending approval", "operationId": "listPendingMessages", "responses": { "200": { "description": "success" } }, "x-scope": "messages:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "filter by campaign", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/messages/{id}/approve": { "post": { "tags": [ "messages" ], "summary": "approve a pending message for sending", "operationId": "approveMessage", "responses": { "200": { "description": "success" }, "404": { "description": "MSG_005: message not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "409": { "description": "MSG_004: message already approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "messages:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/messages/{id}/reject": { "post": { "tags": [ "messages" ], "summary": "reject a pending message", "operationId": "rejectMessage", "responses": { "200": { "description": "success" }, "404": { "description": "MSG_005: message not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "messages:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "rejection reason" } } } } } } } }, "/api/v1/messages/{id}/retry": { "post": { "tags": [ "messages" ], "summary": "retry a failed message", "operationId": "retryMessage", "responses": { "200": { "description": "success" }, "404": { "description": "MSG_005: message not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "messages:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/messages/{id}/feedback": { "post": { "tags": [ "messages" ], "summary": "submit feedback to revise a message with AI", "operationId": "submitMessageFeedback", "responses": { "200": { "description": "success" }, "404": { "description": "MSG_005: message not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "AI_004: AI rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "messages:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback": { "type": "string", "description": "revision instructions (e.g. 'make it more casual and shorter')" } }, "required": [ "feedback" ] } } } } } }, "/api/v1/messages/bulk": { "post": { "tags": [ "messages" ], "summary": "bulk approve or reject messages", "operationId": "bulkMessageAction", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "processed": 5, "failed": 0 } } } } } }, "x-scope": "messages:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ], "description": "action to perform" }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "message queue item IDs" } }, "required": [ "action", "ids" ] } } } } } }, "/api/v1/ai/generate": { "post": { "tags": [ "AI" ], "summary": "generate AI content (email subject + body)", "operationId": "generateAiContent", "responses": { "200": { "description": "success" }, "429": { "description": "AI_004: AI rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "500": { "description": "AI_002: AI generation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "ai:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "target contact ID" }, "conversation_id": { "type": "string", "format": "uuid", "description": "conversation ID" }, "generation_type": { "type": "string", "enum": [ "initial_outreach", "follow_up", "reply" ], "description": "type of content to generate" }, "context": { "type": "object", "description": "additional context for generation" } }, "required": [ "contact_id", "conversation_id", "generation_type" ] } } } }, "description": "free for agents (bundled with campaign credit)." } }, "/api/v1/ai/generate/campaign": { "post": { "tags": [ "AI" ], "summary": "generate campaign-wide content strategy", "operationId": "generateCampaignContent", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "AI_004: AI rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "ai:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "description": "campaign ID" }, "content_type": { "type": "string", "enum": [ "email_template", "outreach_strategy" ], "description": "type of content to generate" } }, "required": [ "campaign_id", "content_type" ] } } } } } }, "/api/v1/ai/analyze": { "post": { "tags": [ "AI" ], "summary": "analyze a response for sentiment and suggested actions", "operationId": "analyzeCampaign", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "sentiment": "positive", "intent": "interested", "suggested_actions": [ "schedule_meeting", "send_more_info" ], "confidence": 0.92 } } } } }, "429": { "description": "AI_004: AI rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "ai:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid", "description": "conversation ID" }, "message_content": { "type": "string", "description": "message text to analyze" } }, "required": [ "conversation_id", "message_content" ] } } } } } }, "/api/v1/ai/usage": { "get": { "tags": [ "AI" ], "summary": "get AI generation usage for the current billing period", "operationId": "getAiUsage", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "used": 45, "limit": 500, "remaining": 455, "billing_period_start": "2024-01-01T00:00:00Z", "billing_period_end": "2024-02-01T00:00:00Z" } } } } } }, "x-scope": "ai:read" } }, "/api/v1/ai/suggestions": { "get": { "tags": [ "AI" ], "summary": "get AI-suggested responses for a conversation", "operationId": "getAiSuggestions", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "suggestions": [ { "type": "reply", "content": "thanks for your interest! ...", "confidence": 0.88 }, { "type": "follow_up", "content": "just wanted to check in...", "confidence": 0.72 } ] } } } } } }, "x-scope": "ai:read", "parameters": [ { "name": "conversation_id", "in": "query", "required": true, "description": "conversation ID", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/discovery/search": { "post": { "tags": [ "discovery" ], "summary": "run a contact discovery search", "operationId": "searchDiscovery", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "job_id": "uuid", "status": "processing" } } } } }, "429": { "description": "DISC_008: discovery quota exceeded; DISC_006: discovery rate limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "discovery:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "search query" }, "source": { "type": "string", "enum": [ "google_maps", "instagram", "twitter", "linkedin" ], "description": "discovery data source" }, "max_results": { "type": "integer", "description": "maximum results to return", "default": "50" }, "campaign_id": { "type": "string", "format": "uuid", "description": "campaign to associate results with" } }, "required": [ "query", "source" ] } } } }, "description": "discovery runs asynchronously. use the job status endpoint to check progress.\n\nfree for agents (bundled with campaign credit)." } }, "/api/v1/discovery/search/campaign": { "post": { "tags": [ "discovery" ], "summary": "run discovery search using campaign target profiles", "operationId": "searchCampaignDiscovery", "responses": { "200": { "description": "success" }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "DISC_008: discovery quota exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "discovery:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "description": "campaign ID" }, "target_profile_id": { "type": "string", "format": "uuid", "description": "specific target profile to use (defaults to all)" } }, "required": [ "campaign_id" ] } } } } } }, "/api/v1/discovery/jobs/{id}": { "get": { "tags": [ "discovery" ], "summary": "get the status of a discovery job", "operationId": "getDiscoveryJob", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "id": "uuid", "status": "completed", "contacts_found": 42, "source": "google_maps", "completed_at": "2024-01-15T10:35:00Z" } } } } }, "404": { "description": "DISC_002: discovery job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "discovery:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/discovery/sources": { "get": { "tags": [ "discovery" ], "summary": "list available discovery data sources", "operationId": "listDiscoverySources", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "google_maps", "name": "Google Maps", "available": true }, { "id": "instagram", "name": "Instagram", "available": true }, { "id": "twitter", "name": "Twitter", "available": true }, { "id": "linkedin", "name": "LinkedIn", "available": false } ] } } } } }, "x-scope": "discovery:read" } }, "/api/v1/analytics/overview": { "get": { "tags": [ "analytics" ], "summary": "get overall analytics overview", "operationId": "getAnalyticsOverview", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "total_campaigns": 12, "active_campaigns": 3, "total_contacts": 1250, "total_conversations": 450, "overall_response_rate": 0.36, "emails_sent_this_period": 230 } } } } } }, "x-scope": "analytics:read" } }, "/api/v1/analytics/campaigns/{id}": { "get": { "tags": [ "analytics" ], "summary": "get analytics for a specific campaign", "operationId": "getCampaignAnalytics", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "campaign_id": "uuid", "contacts_total": 150, "contacts_reached": 42, "emails_sent": 42, "emails_opened": 28, "emails_clicked": 12, "responses_received": 8, "response_rate": 0.19, "open_rate": 0.67, "click_rate": 0.29 } } } } }, "404": { "description": "CAMP_001: campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "analytics:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/analytics/performance": { "get": { "tags": [ "analytics" ], "summary": "get performance metrics over time", "operationId": "getPerformanceMetrics", "responses": { "200": { "description": "success" } }, "x-scope": "analytics:read", "parameters": [ { "name": "period", "in": "query", "required": false, "description": "time period", "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ], "default": "30d" } } ] } }, "/api/v1/analytics/response-time": { "get": { "tags": [ "analytics" ], "summary": "get average response time metrics", "operationId": "getResponseTimeMetrics", "responses": { "200": { "description": "success" } }, "x-scope": "analytics:read", "parameters": [ { "name": "campaign_id", "in": "query", "required": false, "description": "filter by campaign", "schema": { "type": "string", "format": "uuid" } } ] } }, "/api/v1/analytics/contact-types": { "get": { "tags": [ "analytics" ], "summary": "get contact type distribution", "operationId": "getContactTypeDistribution", "responses": { "200": { "description": "success" } }, "x-scope": "analytics:read" } }, "/api/v1/billing/plans": { "get": { "tags": [ "billing" ], "summary": "get available billing plans and their features", "operationId": "listPlans", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "free", "name": "free", "price_monthly": 0, "limits": { "campaigns": 2, "contacts": 100, "emails_per_month": 50, "ai_generations": 20, "discovery_searches": 5 } }, { "id": "starter", "name": "starter", "price_monthly": 29, "limits": { "campaigns": 10, "contacts": 1000, "emails_per_month": 500, "ai_generations": 200, "discovery_searches": 25 } } ] } } } } }, "x-scope": "billing:read" } }, "/api/v1/channels/accounts": { "get": { "tags": [ "channels" ], "summary": "list connected social accounts", "operationId": "listConnectedAccounts", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "uuid", "platform": "twitter", "account_name": "@myaccount", "status": "active", "connected_at": "2024-01-15T10:30:00Z" } ] } } } } }, "x-scope": "channels:read" } }, "/api/v1/channels/availability": { "get": { "tags": [ "channels" ], "summary": "check which channels are available for messaging", "operationId": "getChannelAvailability", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "email": { "available": true, "configured": true }, "twitter": { "available": true, "configured": true }, "instagram": { "available": true, "configured": false }, "linkedin": { "available": true, "configured": false } } } } } } }, "x-scope": "channels:read" } }, "/api/v1/channels/send": { "post": { "tags": [ "channels" ], "summary": "send a message through a specific channel", "operationId": "sendChannelMessage", "responses": { "200": { "description": "success" }, "404": { "description": "CONV_001: conversation not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "429": { "description": "MSG_015: message limit reached", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "channels:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "twitter", "instagram", "linkedin" ], "description": "outreach channel" }, "conversation_id": { "type": "string", "format": "uuid", "description": "conversation ID" }, "content": { "type": "string", "description": "message content" } }, "required": [ "channel", "conversation_id", "content" ] } } } }, "description": "free for agents (bundled with campaign credit)." } }, "/api/v1/notifications": { "get": { "tags": [ "notifications" ], "summary": "list notifications", "operationId": "listNotifications", "responses": { "200": { "description": "success" } }, "x-scope": "notifications:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } } ] } }, "/api/v1/notifications/{id}": { "patch": { "tags": [ "notifications" ], "summary": "update a notification (e.g. mark as read)", "operationId": "updateNotification", "responses": { "200": { "description": "success" }, "404": { "description": "NOTIF_001: notification not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "notifications:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "read": { "type": "boolean", "description": "mark as read/unread" } } } } } } }, "delete": { "tags": [ "notifications" ], "summary": "delete a notification", "operationId": "deleteNotification", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "NOTIF_001: notification not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "x-scope": "notifications:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/notifications/read-all": { "post": { "tags": [ "notifications" ], "summary": "mark all notifications as read", "operationId": "markAllNotificationsRead", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "updated": 12 } } } } } }, "x-scope": "notifications:write" } }, "/api/v1/webhooks": { "get": { "tags": [ "webhooks" ], "summary": "list all webhook endpoints", "operationId": "listWebhooks", "responses": { "200": { "description": "success" } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } } ] }, "post": { "tags": [ "webhooks" ], "summary": "create a new webhook endpoint", "operationId": "createWebhooks", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "id": "uuid", "url": "https://example.com/webhooks/markus", "secret": "whsec_abc123...", "events": [ "campaign.created", "contact.created" ], "is_active": true } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "webhook endpoint URL (HTTPS)" }, "events": { "type": "array", "items": { "type": "string" }, "description": "event types to subscribe to (e.g. [\"campaign.created\", \"contact.created\"]). use [\"*\"] for all events" }, "description": { "type": "string", "description": "optional description" } }, "required": [ "url", "events" ] } } } }, "description": "the signing secret is only returned on creation — store it securely" } }, "/api/v1/webhooks/{id}": { "get": { "tags": [ "webhooks" ], "summary": "get a specific webhook endpoint", "operationId": "getWebhook", "responses": { "200": { "description": "success" }, "404": { "description": "HOOK_001: webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "patch": { "tags": [ "webhooks" ], "summary": "update a webhook endpoint", "operationId": "updateWebhook", "responses": { "200": { "description": "success" }, "404": { "description": "HOOK_001: webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "webhook endpoint URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "event types" }, "is_active": { "type": "boolean", "description": "enable/disable" } } } } } } }, "delete": { "tags": [ "webhooks" ], "summary": "delete a webhook endpoint", "operationId": "deleteWebhook", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": null } } } }, "404": { "description": "HOOK_001: webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "webhooks" ], "summary": "send a test event to a webhook endpoint", "operationId": "testWebhook", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "delivered": true, "response_status": 200, "response_time_ms": 145 } } } } }, "404": { "description": "HOOK_001: webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "webhooks" ], "summary": "list recent webhook deliveries", "operationId": "getWebhookDeliveries", "responses": { "200": { "description": "success" }, "404": { "description": "HOOK_001: webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" }, { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": "1" } }, { "name": "page_size", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "default": "50" } } ] } }, "/api/v1/agent/credits": { "get": { "tags": [ "agent credits" ], "summary": "check the agent's current credit balance", "operationId": "listCredits", "responses": { "200": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "balance": 7, "identity_id": "uuid" } } } } } }, "description": "requires x402 or MPP identity header (no payment needed for balance check).\n\nreturns null balance for API key users (they don't use credits)." }, "post": { "tags": [ "agent credits" ], "summary": "purchase 5 credits with x402 or MPP payment", "operationId": "createCredits", "responses": { "201": { "description": "success", "content": { "application/json": { "example": { "success": true, "data": { "balance": 5, "credits_added": 5, "pack": "pack_5" } } } } }, "402": { "description": "PAY_001: payment required — $12.00 (MPP) for 5 credits. x402 agents: use per-campaign pricing at POST /campaigns.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } }, "500": { "description": "PAY_007: purchase failed after payment (contact support)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } } } } } }, "description": "credit packs: 5 credits for $12.00 (MPP only). x402 agents pay per-campaign ($2.25) at POST /campaigns.\n\nx402 agents can pay per-campaign ($2.25) by sending X-PAYMENT header with POST /campaigns. MPP agents must use packs.\n\ncredits never expire. send X-PAYMENT (x402) or Authorization: Payment (MPP) header." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key starting with mk_live_. Create at https://markusai.dev/settings under API keys." } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "SERVER_001" }, "message": { "type": "string", "example": "internal server error" } }, "required": [ "code", "message" ] } } } } } }