{ "openapi": "3.1.0", "info": { "title": "Evident Agent service discovery", "version": "0.18.0", "description": "Personal Agent tool discovery, public setup handoffs and advanced service workflows." }, "servers": [ { "url": "https://evidentagents.com" } ], "paths": { "/api/v3/services": { "get": { "operationId": "browseServices", "parameters": [ { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 500 } }, { "in": "query", "name": "deployment", "schema": { "type": "string", "enum": [ "remote", "local_or_configured", "any" ], "default": "remote" } }, { "in": "query", "name": "transport", "schema": { "type": "string", "enum": [ "any", "streamable-http", "sse", "https-api", "local_cli", "python_library" ] } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "name": "task", "in": "query", "schema": { "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] } } ], "responses": { "200": { "description": "Candidate metadata with reasons and next_cursor; follow cursor with identical filters" }, "422": { "description": "Invalid query or expired cursor" } } } }, "/api/v3/services/match": { "post": { "operationId": "matchServices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "q": { "type": "string", "maxLength": 500 }, "deployment": { "type": "string", "enum": [ "remote", "local_or_configured", "any" ] }, "transport": { "type": "string", "enum": [ "any", "streamable-http", "sse", "https-api", "local_cli", "python_library" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "after": { "type": "string" }, "require_no_auth": { "type": "boolean", "description": "Unknown auth does not satisfy this condition" }, "task": { "type": "string", "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] } } } } } }, "responses": { "200": { "description": "Candidates; lexical matching, not success probability" }, "422": { "description": "Unsupported constraints or invalid input" } } } }, "/api/v3/services/{service_id}": { "get": { "operationId": "getService", "parameters": [ { "in": "path", "name": "service_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public source metadata, endpoints and explicit unknowns" }, "404": { "description": "Not in current snapshot" } } } }, "/api/v3/services/{service_id}/handoff": { "get": { "operationId": "getServiceHandoff", "parameters": [ { "in": "path", "name": "service_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection instructions only; no execution, credentials or usage record" }, "404": { "description": "Not in current snapshot" } } } }, "/api/v3/services/coverage": { "get": { "operationId": "getServiceCoverage", "responses": { "200": { "description": "Source, snapshot date, pagination completion and scope limitations" } } } }, "/api/v3/task-schema": { "get": { "summary": "Structured task constraints schema", "responses": { "200": { "description": "JSON Schema" } } } }, "/api/v3/task-match": { "post": { "summary": "Match explicit task constraints", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "task": { "type": "string", "enum": [ "web_research", "technical_docs", "workspace_search", "document_editing", "scanned_pdf_tables", "image_generation", "design_context", "issue_management", "browser_automation", "web_extraction", "repository_research", "payment_operations" ] }, "input": { "type": "string", "enum": [ "any", "text", "url", "workspace", "scanned_pdf" ] }, "output": { "type": "string", "enum": [ "any", "sources", "text", "image", "structured_data" ] }, "deployment": { "type": "string", "enum": [ "any", "remote", "local_or_configured" ] }, "allow_paid": { "type": "boolean" }, "require_no_auth": { "type": "boolean" } }, "required": [ "task" ] } } } }, "responses": { "200": { "description": "Candidates, exclusions and unknown requirements" }, "422": { "description": "Invalid input" } } } }, "/api/v3/service-feedback/schema": { "get": { "summary": "Service-use feedback schema and scoped confirmation flow", "responses": { "200": { "description": "Service-use feedback schema and scoped confirmation flow" } } } }, "/api/v3/service-feedback": { "get": { "summary": "Public consumer-confirmed self-reported feedback", "responses": { "200": { "description": "Public consumer-confirmed self-reported feedback" } } } }, "/api/v3/service-config": { "get": { "summary": "Download credential-free client configuration", "responses": { "200": { "description": "Download credential-free client configuration" } } } }, "/api/v3/task-plan": { "post": { "summary": "Plan research or extraction with explicit constraints", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "microsoft", "cloudflare", "library_docs", "public_web", "public_repository", "scholarly" ] }, "table_layout": { "type": "string", "enum": [ "fixed_columns", "other_or_unknown" ] }, "query": { "type": "string", "maxLength": 1000 }, "task": { "type": "string", "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] }, "input": { "type": "string", "enum": [ "text", "url", "text_pdf", "scanned_pdf", "image", "docx", "pptx", "html" ] }, "output": { "type": "string", "enum": [ "text", "sources", "structured_data", "csv", "xlsx" ] }, "deployment": { "type": "string", "enum": [ "any", "remote", "local_or_configured" ] }, "allow_paid": { "type": "boolean" }, "require_no_auth": { "type": "boolean" }, "local_only": { "type": "boolean" }, "require_tested": { "type": "boolean" }, "language": { "type": "string", "maxLength": 30 }, "region": { "type": "string", "maxLength": 60 }, "max_file_mb": { "type": "number", "minimum": 0.1, "maximum": 1000 }, "exclude_service_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } } } } } }, "responses": { "200": { "description": "Documented fits, unknowns, exclusions and clarification requirements" }, "422": { "description": "Invalid constraints" } } }, "get": { "summary": "Get a curated service connection plan", "parameters": [ { "name": "service_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "task", "in": "query", "schema": { "type": "string", "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] } } ], "responses": { "200": { "description": "Connection instructions and named test assertions" }, "404": { "description": "No curated plan" } } } }, "/api/v3/task-plan/schema": { "get": { "summary": "Planner schema", "responses": { "200": { "description": "JSON schema and workflow" } } } }, "/api/v3/task-benchmarks": { "get": { "summary": "Dated public research and generated PDF task assertions", "parameters": [ { "name": "service_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Measured scope, failures and limitations" } } } }, "/api/v3/workspace": { "get": { "summary": "Read private team watches and latest 100 task attempts", "security": [ { "workspaceToken": [] } ], "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Private team records" }, "401": { "description": "Invalid or revoked token" }, "404": { "description": "Workspace not available" } } }, "post": { "summary": "Manage watches or record own task outcome; no public publication", "security": [ { "workspaceToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "workspace_id" ], "properties": { "action": { "enum": [ "watch", "unwatch", "acknowledge", "refresh", "start_run", "finish_run" ] }, "workspace_id": { "type": "string" }, "service_id": { "type": "string" }, "task_type": { "type": "string" }, "request_key": { "type": "string" }, "run_id": { "type": "string" }, "outcome": { "enum": [ "completed", "partial", "failed" ] }, "failure_code": { "enum": [ "authorization", "rate_limit", "schema_changed", "unsupported_input", "timeout", "output_quality", "other" ] }, "latency_ms": { "type": "number", "minimum": 0 }, "cost": { "type": "number", "minimum": 0 }, "currency": { "enum": [ "USD", "EUR", "GBP", "CNY", "JPY" ] }, "validation": { "type": "object", "additionalProperties": false, "required": [ "contract_hash", "validator_version", "passed", "failed", "unknown", "environment" ], "properties": { "contract_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "validator_version": { "const": "1.0" }, "passed": { "type": "integer", "minimum": 0, "maximum": 100 }, "failed": { "type": "integer", "minimum": 0, "maximum": 100 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 100 }, "environment": { "enum": [ "test", "production" ] } } } } } } } }, "responses": { "200": { "description": "Private state recorded" }, "401": { "description": "Invalid token" }, "403": { "description": "Not permitted" }, "409": { "description": "Conflicting replay or immutable result" }, "422": { "description": "Invalid action" } } } }, "/api/v3/workspace/schema": { "get": { "summary": "Private workspace actions and limits", "responses": { "200": { "description": "Action contract" } } } }, "/api/v3/task-contract": { "post": { "summary": "Prepare a task contract and capability fit; no execution", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "research", "extraction" ] }, "scope": { "type": "string", "enum": [ "microsoft", "cloudflare", "public_web" ] }, "max_latency_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 }, "max_cost_usd": { "type": "number", "minimum": 0, "maximum": 100 }, "local_only": { "type": "boolean" }, "min_sources": { "type": "integer", "minimum": 1, "maximum": 20 }, "required_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "max_age_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "min_pages": { "type": "integer", "minimum": 1, "maximum": 100 }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" }, "type": { "enum": [ "string", "number", "date" ] }, "required": { "type": "boolean" } } } }, "table_columns": { "type": "integer", "minimum": 1, "maximum": 29 } } } } } }, "responses": { "200": { "description": "Normalized constraints, matching, price unknowns and SDK steps" }, "422": { "description": "Invalid contract" } } } }, "/api/v3/task-contract/schema": { "get": { "summary": "Task contract schema and execution boundaries", "responses": { "200": { "description": "Contract schema" } } } }, "/api/v3/task-canaries": { "get": { "summary": "Latest bounded public source/topic checks; no customer success claims", "responses": { "200": { "description": "Dated observations" } } } }, "/api/v3/quality": { "get": { "summary": "Private alerts and caller-reported task metrics", "security": [ { "workspaceToken": [] } ], "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Alerts, next_cursor, grouped metrics" }, "401": { "description": "Sign in or use a scoped workspace token" }, "404": { "description": "Workspace inaccessible" } } }, "post": { "summary": "Acknowledge an alert; owner browser can set thresholds", "security": [ { "workspaceToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "workspace_id" ], "properties": { "action": { "enum": [ "acknowledge" ] }, "workspace_id": { "type": "string" }, "alert_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Private state" }, "403": { "description": "Owner browser required for policy" } } } }, "/api/v3/demands": { "get": { "summary": "Read opt-in public unmet requests", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public items and next_cursor" } } } }, "/api/v3/demands/draft": { "post": { "summary": "Prepare a requester confirmation URL; nothing is saved", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "contract" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 5, "maxLength": 160 }, "contract": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "research", "extraction" ] }, "scope": { "type": "string", "enum": [ "microsoft", "cloudflare", "public_web" ] }, "max_latency_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 }, "max_cost_usd": { "type": "number", "minimum": 0, "maximum": 100 }, "local_only": { "type": "boolean" }, "min_sources": { "type": "integer", "minimum": 1, "maximum": 20 }, "required_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "max_age_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "min_pages": { "type": "integer", "minimum": 1, "maximum": 100 }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" }, "type": { "enum": [ "string", "number", "date" ] }, "required": { "type": "boolean" } } } }, "table_columns": { "type": "integer", "minimum": 1, "maximum": 29 } } } } } } } }, "responses": { "200": { "description": "Consumer confirmation URL" }, "422": { "description": "Invalid title or contract" } } } }, "/api/v3/task-execute": { "post": { "summary": "Signed-in browser execution of Microsoft or Cloudflare public documentation queries only", "description": "Session cookie, same-origin and confirmed=yes required. No Bearer agent execution, files, payments or arbitrary URLs. Use the SDK for Agent execution.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmed", "contract", "query" ], "properties": { "confirmed": { "const": "yes" }, "contract": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "research", "extraction" ] }, "scope": { "type": "string", "enum": [ "microsoft", "cloudflare", "public_web" ] }, "max_latency_ms": { "type": "integer", "minimum": 1000, "maximum": 120000 }, "max_cost_usd": { "type": "number", "minimum": 0, "maximum": 100 }, "local_only": { "type": "boolean" }, "min_sources": { "type": "integer", "minimum": 1, "maximum": 20 }, "required_domains": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "max_age_days": { "type": "integer", "minimum": 1, "maximum": 3650 }, "min_pages": { "type": "integer", "minimum": 1, "maximum": 100 }, "fields": { "type": "array", "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,39}$" }, "type": { "enum": [ "string", "number", "date" ] }, "required": { "type": "boolean" } } } }, "table_columns": { "type": "integer", "minimum": 1, "maximum": 29 } } }, "query": { "type": "string", "maxLength": 1000 }, "workspace_id": { "type": "string" }, "request_key": { "type": "string" }, "environment": { "enum": [ "test", "production" ] } } } } } }, "responses": { "200": { "description": "Public sources and bounded checks" }, "401": { "description": "Browser session required" }, "403": { "description": "Same origin required" }, "409": { "description": "Attempt already claimed" }, "429": { "description": "User quota exceeded" } } } }, "/api/v3/task-candidates": { "get": { "summary": "26 documented research and extraction candidates with operation contracts and setup", "parameters": [ { "name": "family", "in": "query", "schema": { "enum": [ "research", "documents" ] } }, { "name": "task", "in": "query", "schema": { "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] } } ], "responses": { "200": { "description": "All matching candidates with documentation dates, checks and connection plans" }, "422": { "description": "Unknown filter" } } } }, "/api/v3/personal/find": { "post": { "summary": "Find up to three tools for a personal task; no execution", "responses": { "200": { "description": "Public discovery data" }, "422": { "description": "Invalid requirements" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalFind" } } } } } }, "/api/v3/personal/handoff": { "get": { "summary": "Get a public setup brief for a selected tool", "responses": { "200": { "description": "Public discovery data" }, "422": { "description": "Invalid requirements" } }, "security": [], "parameters": [ { "name": "service_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kit", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/api/v3/personal/catalog": { "get": { "summary": "Read public task recipes, clients and personal discovery schema", "responses": { "200": { "description": "Public discovery data" }, "422": { "description": "Invalid requirements" } }, "security": [] } } }, "components": { "securitySchemes": { "workspaceToken": { "type": "http", "scheme": "bearer", "description": "Seven-day workspace-only token, issued by a signed-in member. Not an MCP token." } }, "schemas": { "PersonalFind": { "type": "object", "additionalProperties": false, "properties": { "scope": { "type": "string", "enum": [ "microsoft", "cloudflare", "library_docs", "public_web", "public_repository", "scholarly" ] }, "table_layout": { "type": "string", "enum": [ "fixed_columns", "other_or_unknown" ] }, "query": { "type": "string", "maxLength": 240 }, "task": { "type": "string", "enum": [ "web_research", "technical_docs", "repository_research", "scholarly_research", "news_research", "url_extraction", "pdf_text", "pdf_tables", "scanned_pdf_tables", "document_text", "field_extraction" ] }, "input": { "type": "string", "enum": [ "text", "url", "text_pdf", "scanned_pdf", "image", "docx", "pptx", "html" ] }, "output": { "type": "string", "enum": [ "text", "sources", "structured_data", "csv", "xlsx" ] }, "deployment": { "type": "string", "enum": [ "any", "remote", "local_or_configured" ] }, "allow_paid": { "type": "boolean" }, "require_no_auth": { "type": "boolean" }, "local_only": { "type": "boolean" }, "require_tested": { "type": "boolean" }, "language": { "type": "string", "maxLength": 30 }, "region": { "type": "string", "maxLength": 60 }, "max_file_mb": { "type": "number", "minimum": 0.1, "maximum": 1000 }, "exclude_service_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "client": { "type": "string", "enum": [ "other", "claude", "chatgpt", "cursor", "vscode" ] }, "kit": { "type": "string", "enum": [ "find-sources", "find-papers", "read-web-page", "read-pdf", "pdf-tables", "read-scan" ] } } } } } }