{ "openapi": "3.0.0", "info": { "title": "Zipf AI External API", "description": "Persistent web monitoring for AI agents. Search, crawl, extract, and monitor web sources on a schedule.\n\nFor human-readable documentation: https://zipf.ai/docs\nFor LLM-optimized reference: https://zipf.ai/llms.txt\nOpenAPI spec: https://zipf.ai/openapi.json", "version": "1.7.0", "contact": { "name": "Zipf AI Support", "email": "support@zipf.ai", "url": "https://zipf.ai" }, "license": { "name": "Proprietary", "url": "https://zipf.ai/terms" } }, "servers": [ { "url": "https://api.zipf.ai/v1", "description": "Production server" }, { "url": "http://localhost:3000/api/v1", "description": "Development server" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API token authentication. Create tokens at /dashboard/tokens. Prefix: wvr_" } }, "schemas": { "CreditsInfo": { "type": "object", "properties": { "consumed": { "type": "integer", "description": "Credits consumed by this operation" }, "balance_after": { "type": "integer", "description": "Credit balance after operation" }, "pricing_tier": { "type": "string", "enum": [ "basic", "advanced" ], "description": "Pricing tier applied" }, "advanced_features": { "type": "array", "items": { "type": "string" }, "description": "AI features that triggered advanced pricing" } } }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Error type" }, "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "Actionable suggestions to resolve the error" }, "details": { "type": "object", "description": "Additional error context" } } }, "SearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 1000, "description": "Search query" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "rerank_results": { "type": "boolean", "default": false, "description": "Enable semantic reranking (triggers advanced pricing)" }, "generate_suggestions": { "type": "boolean", "default": false, "description": "Generate follow-up query suggestions (triggers advanced pricing)" }, "generate_summary": { "type": "boolean", "default": true, "description": "Generate AI summary (FREE)" }, "source_type": { "type": "string", "enum": [ "academic", "commercial", "news", "community", "mixed" ], "description": "Target source type" }, "session_id": { "type": "string", "format": "uuid", "description": "Link search to a session" }, "processing_mode": { "type": "string", "enum": [ "sync", "async", "webhook" ], "default": "async" }, "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL for completion notification" }, "dry_run": { "type": "boolean", "default": false, "description": "Estimate cost without executing" } } }, "QuickSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 1000, "description": "Search query" }, "max_results": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "include_domains": { "type": "array", "items": { "type": "string" }, "description": "Only include results from these domains" }, "exclude_domains": { "type": "array", "items": { "type": "string" }, "description": "Exclude results from these domains" } } }, "SearchResult": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "published_date": { "type": "string", "format": "date-time" }, "relevance_score": { "type": "number" } } }, "CrawlRequest": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "maxItems": 100, "description": "Seed URLs to crawl" }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "classify_documents": { "type": "boolean", "default": true, "description": "Enable AI document classification (triggers advanced pricing)" }, "generate_summary": { "type": "boolean", "default": false, "description": "Generate AI summary (FREE)" }, "extraction_schema": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field extraction schema (triggers advanced pricing)", "example": { "title": "Extract the article title", "author": "Extract the author name" } }, "expansion": { "type": "string", "enum": [ "internal", "external", "both", "none" ], "description": "URL expansion mode" }, "link_extraction_config": { "type": "object", "properties": { "max_depth": { "type": "integer", "minimum": 1, "maximum": 10 }, "url_patterns": { "type": "array", "items": { "type": "string" } }, "exclude_patterns": { "type": "array", "items": { "type": "string" } }, "detect_pagination": { "type": "boolean" } } }, "session_id": { "type": "string", "format": "uuid" }, "processing_mode": { "type": "string", "enum": [ "sync", "async", "webhook" ], "default": "async" }, "webhook_url": { "type": "string", "format": "uri" }, "dry_run": { "type": "boolean", "default": false } } }, "CreateSessionRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Session name" }, "description": { "type": "string" }, "session_config": { "type": "object", "properties": { "auto_deduplicate": { "type": "boolean", "default": true }, "accumulate_context": { "type": "boolean", "default": true }, "use_session_context": { "type": "boolean", "default": true }, "max_operations": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "metadata": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "domain_context": { "type": "string", "enum": [ "general", "academic", "news", "technical" ] } }, "additionalProperties": true } } }, "CreateWorkflowRequest": { "type": "object", "required": [ "name", "workflow_type", "operation_config" ], "properties": { "name": { "type": "string", "description": "Workflow name" }, "workflow_type": { "type": "string", "enum": [ "search", "crawl" ] }, "operation_config": { "type": "object", "description": "Search or crawl configuration" }, "interval_minutes": { "type": "integer", "minimum": 1, "description": "Execution frequency" }, "max_executions": { "type": "integer", "description": "Maximum number of executions" }, "stop_condition": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "natural_language", "threshold", "none" ] }, "description": { "type": "string", "description": "Condition description (for NL type)" }, "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1 } } }, "notification_config": { "type": "object", "properties": { "email": { "type": "boolean" }, "webhook_url": { "type": "string", "format": "uri" } } } } }, "AskRequest": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "Question to answer" }, "depth": { "type": "string", "enum": [ "quick", "standard", "deep" ], "default": "standard", "description": "Research depth (affects credits: quick=2, standard=3, deep=5+)" }, "max_sources": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "session_id": { "type": "string", "format": "uuid" } } } } }, "paths": { "/search/quick": { "post": { "tags": [ "Search" ], "summary": "Quick synchronous search", "description": "Fast, simple search with immediate results. 1 credit per call.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuickSearchRequest" } } } } } }, "/search": { "get": { "tags": [ "Search" ], "summary": "Get search capabilities", "description": "Returns available search providers, features, and user statistics.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Search" ], "summary": "Execute full-featured search", "description": "Search with optional AI features. 1 credit (basic) or 2 credits (advanced with AI features).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } } } }, "/search/jobs": { "get": { "tags": [ "Search" ], "summary": "List search jobs", "description": "List search jobs with pagination and filtering.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] } } ] } }, "/search/jobs/{id}": { "get": { "tags": [ "Search" ], "summary": "Get search job details", "description": "Get specific job details including results, timing, and suggested queries.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "tags": [ "Search" ], "summary": "Delete search job", "description": "Delete a search job from history.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/search/jobs/{id}/share": { "post": { "tags": [ "Search" ], "summary": "Toggle public sharing", "description": "Enable or disable public sharing for a search job.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_share": { "type": "boolean" } } } } } } } }, "/crawls": { "post": { "tags": [ "Crawl" ], "summary": "Create crawl job", "description": "Start a web crawl. 1 credit/page (basic) or 2 credits/page (with AI features). Supports sync mode for immediate results.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlRequest" } } } } }, "get": { "tags": [ "Crawl" ], "summary": "List crawl jobs", "description": "List crawl jobs with pagination and filtering.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed", "cancelled" ] } } ] } }, "/crawls/{id}": { "get": { "tags": [ "Crawl" ], "summary": "Get crawl job details", "description": "Get detailed job status, configuration, stats, and documents.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "tags": [ "Crawl" ], "summary": "Cancel crawl job", "description": "Cancel a running or scheduled crawl. Credits are refunded.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/crawls/{id}/execute": { "post": { "tags": [ "Crawl" ], "summary": "Execute scheduled crawl", "description": "Execute a scheduled crawl job immediately.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/crawls/preview-extraction": { "post": { "tags": [ "Crawl" ], "summary": "Preview extraction schema", "description": "Test extraction schema on a single URL before full crawl. 1 credit.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "extraction_schema" ], "properties": { "url": { "type": "string", "format": "uri" }, "extraction_schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } }, "/sessions": { "post": { "tags": [ "Sessions" ], "summary": "Create session", "description": "Create a new research session for multi-step workflows.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } } }, "get": { "tags": [ "Sessions" ], "summary": "List sessions", "description": "List sessions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "completed", "archived" ] } }, { "name": "days_back", "in": "query", "schema": { "type": "integer", "default": 7 } } ] } }, "/sessions/{id}": { "get": { "tags": [ "Sessions" ], "summary": "Get session details", "description": "Get detailed session information including operations and context summary.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "tags": [ "Sessions" ], "summary": "Update session", "description": "Update session metadata, name, description, or configuration.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "tags": [ "Sessions" ], "summary": "Delete session", "description": "Delete session and all associated operations. Permanent.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/sessions/{id}/search": { "post": { "tags": [ "Sessions" ], "summary": "Search within session", "description": "Execute search with automatic URL deduplication against session history.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SearchRequest" }, { "type": "object", "properties": { "filter_seen_urls": { "type": "boolean", "default": false, "description": "Exclude URLs already in session" } } } ] } } } } } }, "/sessions/{id}/crawl": { "post": { "tags": [ "Sessions" ], "summary": "Crawl within session", "description": "Execute crawl with automatic URL deduplication.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CrawlRequest" }, { "type": "object", "properties": { "filter_seen_urls": { "type": "boolean", "default": true } } } ] } } } } } }, "/sessions/{id}/timeline": { "get": { "tags": [ "Sessions" ], "summary": "Get session timeline", "description": "Get chronological timeline of all operations in session.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/sessions/{id}/complete": { "post": { "tags": [ "Sessions" ], "summary": "Complete session", "description": "Mark session as completed. Prevents new operations.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/sessions/{id}/archive": { "post": { "tags": [ "Sessions" ], "summary": "Archive session", "description": "Archive completed session. Frees up quota.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/sessions/{id}/share": { "post": { "tags": [ "Sessions" ], "summary": "Toggle session sharing", "description": "Toggle session sharing", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_share": { "type": "boolean" } } } } } } } }, "/workflows": { "post": { "tags": [ "Workflow" ], "summary": "Create workflow", "description": "Create a scheduled monitoring workflow. 1-2 credits per execution.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" } } } } }, "get": { "tags": [ "Workflow" ], "summary": "List workflows", "description": "List workflows", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "stopped" ] } } ] } }, "/workflows/{id}": { "get": { "tags": [ "Workflow" ], "summary": "Get workflow details", "description": "Get workflow details", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "tags": [ "Workflow" ], "summary": "Update workflow", "description": "Update workflow configuration, frequency, or stop condition.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "tags": [ "Workflow" ], "summary": "Delete workflow", "description": "Delete workflow", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/workflows/{id}/execute": { "post": { "tags": [ "Workflow" ], "summary": "Execute workflow manually", "description": "Trigger immediate execution of a workflow.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/workflows/{id}/timeline": { "get": { "tags": [ "Workflow" ], "summary": "Get workflow execution history", "description": "Get workflow execution history", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/ask": { "post": { "tags": [ "Ask" ], "summary": "Ask a question", "description": "Get AI-generated answers with source citations. Credits: quick=2, standard=3, deep=5+.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } } } } }, "/ask/jobs/{id}": { "get": { "tags": [ "Ask" ], "summary": "Get answer job details", "description": "Get answer job details", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List API tokens", "description": "List API tokens", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Tokens" ], "summary": "Create API token", "description": "Create a new API token. Token is only shown once.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token_name" ], "properties": { "token_name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/tokens/{id}": { "delete": { "tags": [ "Tokens" ], "summary": "Revoke API token", "description": "Revoke API token", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Resource ID (UUID)", "schema": { "type": "string", "format": "uuid" } } ] } }, "/docs": { "get": { "tags": [ "Docs" ], "summary": "Get API documentation", "description": "Returns full API documentation in markdown or JSON format.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "markdown", "json", "structured" ], "default": "markdown" } }, { "name": "section", "in": "query", "schema": { "type": "string", "enum": [ "overview", "search", "crawl", "sessions", "workflow", "common" ] } } ] } }, "/": { "get": { "tags": [ "Docs" ], "summary": "API info and credit balance", "description": "Returns API info, user credits balance, available endpoints, and credit costs.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API token" }, "402": { "description": "Payment required - insufficient credits" }, "429": { "description": "Rate limit exceeded" }, "500": { "description": "Internal server error" } } } } }, "tags": [ { "name": "Search", "description": "Web search with optional AI enhancements (query rewriting, reranking, suggestions)" }, { "name": "Crawl", "description": "Web crawling with AI-powered classification and data extraction" }, { "name": "Sessions", "description": "Multi-step research workflows with URL deduplication" }, { "name": "Workflow", "description": "Scheduled recurring monitoring with stop conditions" }, { "name": "Ask", "description": "AI-native question answering with direct answers" }, { "name": "Tokens", "description": "API token management" }, { "name": "Docs", "description": "API documentation endpoints" } ] }