{"openapi":"3.1.0","info":{"title":"Claws - OpenClaw for PlatPhormNews API","version":"0.8.0","description":"AI Integration and Testing PlatPhorm API. Counts are registry backed: 73 tools, 36 sites, 4 MCP server records."},"servers":[{"url":"https://claws.platphormnews.com","description":"Claws public API"}],"security":[],"components":{"securitySchemes":{"platphormApiKeyBearer":{"type":"http","scheme":"bearer","description":"Use Authorization: Bearer $PLATPHORM_API_KEY for protected actions."},"platphormApiKeyHeader":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY for protected actions."}}},"paths":{"/api/health":{"get":{"summary":"Get /health","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/health":{"get":{"summary":"Get /v1/health","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/discovery":{"get":{"summary":"Get /v1/discovery","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/network":{"get":{"summary":"Get /v1/network","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/network/sites":{"get":{"summary":"Get /v1/network/sites","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/network/tools":{"get":{"summary":"Get /v1/network/tools","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/network/mcp":{"get":{"summary":"Get /v1/network/mcp","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/network/integrations":{"get":{"summary":"Get /v1/network/integrations","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/tools":{"get":{"summary":"Get /v1/tools","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/toolchains":{"get":{"summary":"Get /v1/toolchains","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/toolchains/{id}/dry-run":{"get":{"summary":"Get deterministic toolchain dry-run plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Toolchain dry-run plan with handler states","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}},"post":{"summary":"Create deterministic toolchain dry-run plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Toolchain dry-run plan with missing/delegated handlers"}}}},"/api/v1/harness":{"get":{"summary":"Get /v1/harness","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/harness/scenarios":{"get":{"summary":"Get /v1/harness/scenarios","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/runs":{"get":{"summary":"Get /v1/runs","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/integrations":{"get":{"summary":"Get /v1/integrations","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/openclaw/status":{"get":{"summary":"Get /v1/openclaw/status","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/openclaw/config":{"get":{"summary":"Get /v1/openclaw/config","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/openclaw/compatibility":{"get":{"summary":"Get /v1/openclaw/compatibility","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/openclaw/adapters":{"get":{"summary":"Get /v1/openclaw/adapters","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide":{"get":{"summary":"Get /v1/ide","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide/vscode":{"get":{"summary":"Get /v1/ide/vscode","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide/cursor":{"get":{"summary":"Get /v1/ide/cursor","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide/windsurf":{"get":{"summary":"Get /v1/ide/windsurf","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide/codex":{"get":{"summary":"Get /v1/ide/codex","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/ide/mcp":{"get":{"summary":"Get /v1/ide/mcp","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/agent-policy":{"get":{"summary":"Get /v1/agent-policy","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/agent-policy/platforms":{"get":{"summary":"Get /v1/agent-policy/platforms","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/agent-policy/robots":{"get":{"summary":"Get /v1/agent-policy/robots","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/agent-policy/summary":{"get":{"summary":"Get /v1/agent-policy/summary","responses":{"200":{"description":"Public-safe response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/mcp":{"get":{"summary":"MCP metadata","responses":{"200":{"description":"MCP metadata"}}},"post":{"summary":"MCP JSON-RPC 2.0 endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response"}}}},"/api/chat":{"post":{"summary":"Route one chat prompt to a validated MCP contract before model fallback","description":"Claws requires a UUID session and first routes the bounded prompt through mcp.platphormnews.com. Deterministic intent contracts select an allowlisted public tool, construct its declared arguments, validate them against the live tools/list input schema, and execute JSON-RPC tools/call without model inference. Requests that require attachments, synthesis, generation, or protected writes use the bounded Vercel AI Gateway fallback; those model-assisted sessions persist messages and tool receipts in the shared Aurora backend and own a private Files folder. PLATPHORM_API_KEY remains server-side and is never sent to the browser or model.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","messages"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable Claws chat session id."},"prompt":{"type":"string","maxLength":12000},"message":{"type":"string","maxLength":12000},"messages":{"type":"array","maxItems":24}}}}}},"responses":{"200":{"description":"AI SDK UI message stream with deterministic MCP contract output or bounded model fallback plus trace metadata"},"400":{"description":"Invalid or empty bounded prompt"},"503":{"description":"Server platform auth or a required model/persistence dependency is unavailable; no fake response is returned"}}}},"/api/chat/attachments":{"get":{"summary":"List persisted artifacts in a Claws chat session folder","parameters":[{"name":"sessionId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Files-backed session folder contents"},"400":{"description":"Invalid session id"},"503":{"description":"Aurora, Files, or server platform auth unavailable"}}},"post":{"summary":"Store chat attachments in the session Files folder","description":"Creates the Aurora session and Files folder if needed, stores up to five attachments using the server-side PLATPHORM_API_KEY, and creates a real OpenContent record for supported bounded images when available.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["sessionId","files"],"properties":{"sessionId":{"type":"string","format":"uuid"},"files":{"type":"array","maxItems":5,"items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":"Persisted Files receipts and any OpenContent image receipt"},"400":{"description":"Invalid attachment request"},"413":{"description":"Attachment size limit exceeded"},"429":{"description":"Rate limited"},"503":{"description":"Aurora, Files, or server platform auth unavailable"}}}},"/api/v1/workflow-runs":{"get":{"summary":"List recent durable Claws workflow runs","responses":{"200":{"description":"Measured Aurora workflow run summaries"},"503":{"description":"Aurora workflow history is unavailable; totals are not converted to zero"}}}},"/api/v1/workflow-runs/{id}":{"get":{"summary":"Get a durable workflow run and its planned or observed steps","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Workflow run, steps, and Trace link"},"404":{"description":"Workflow run not found"},"503":{"description":"Aurora workflow history is unavailable"}}}},"/api/v1/tools/{idOrName}/call":{"post":{"summary":"Call a public-safe tool or prepare a protected action","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Public-safe tool result"},"401":{"description":"Protected tool requires PLATPHORM_API_KEY"},"501":{"description":"Registered tool has no public handler and is degraded"}}}},"/api/v1/tools/{idOrName}/handler":{"get":{"summary":"Get tool handler truth state","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Handler capability state and execution policy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}}},"/api/v1/tools/{idOrName}/dry-run":{"get":{"summary":"Explain public-safe tool dry-run route","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dry-run metadata without tool execution","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"error":{"type":"object"}}}}}}}},"post":{"summary":"Dry-run one tool schema/handler validation without execution","parameters":[{"name":"idOrName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dry-run plan"}}}},"/api/v1/harness/scenarios/{id}/dry-run":{"post":{"summary":"Dry-run one public-safe harness scenario","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Harness dry-run plan"}}}},"/api/v1/openclaw/validate-config":{"post":{"summary":"Validate OpenClaw-compatible config metadata","responses":{"200":{"description":"Schema/policy validation only; no hosted runtime execution"}}}},"/api/v1/ide/generate-config":{"post":{"summary":"Generate labeled sample IDE/MCP client config","responses":{"200":{"description":"Public-safe sample config without protected credentials"}}}},"/api/internal/migrations/bootstrap-aurora":{"post":{"summary":"Bootstrap the isolated empty Claws schema in shared Aurora","description":"Creates Claws-owned tables and a durable write-verification receipt. It does not copy or alter another service data set.","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["confirm"],"properties":{"confirm":{"type":"string","enum":["BOOTSTRAP_CLAWS_AURORA_EMPTY_SCHEMA"]}}}}}},"responses":{"200":{"description":"Claws schema bootstrapped and write verified without copying source data"},"400":{"description":"Exact empty-schema confirmation required"},"401":{"description":"PLATPHORM_API_KEY required"},"503":{"description":"Shared Aurora unavailable or bootstrap verification failed"}}}},"/api/cron/search-sync":{"get":{"summary":"Reconcile the canonical Claws tool registry into Upstash Search","description":"Scheduled daily by Vercel Cron. The same bounded reconciliation can be triggered by an operator with PLATPHORM_API_KEY. It upserts current registry tools and removes stale search documents.","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Registry-backed reconciliation receipt"},"401":{"description":"Scheduled cron authentication or PLATPHORM_API_KEY required"},"429":{"description":"Reconciliation rate limit reached"},"503":{"description":"Registry-to-search reconciliation failed; no success is claimed"}}},"post":{"summary":"Trigger a protected registry-to-search reconciliation","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Registry-backed reconciliation receipt"},"401":{"description":"PLATPHORM_API_KEY required"},"429":{"description":"Reconciliation rate limit reached"},"503":{"description":"Registry-to-search reconciliation failed; no success is claimed"}}}},"/api/v1/memory":{"post":{"summary":"Protected /v1/memory","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Protected action accepted"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/protected-actions/{id}/execute":{"post":{"summary":"Protected /v1/protected-actions/{id}/execute","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Protected action accepted"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/reports/docs":{"post":{"summary":"Protected /v1/reports/docs","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Protected action accepted"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/reports/sheets":{"post":{"summary":"Protected /v1/reports/sheets","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Protected action accepted"},"401":{"description":"PLATPHORM_API_KEY required"}}}},"/api/v1/reports/decks":{"post":{"summary":"Protected /v1/reports/decks","security":[{"platphormApiKeyBearer":[]},{"platphormApiKeyHeader":[]}],"responses":{"200":{"description":"Protected action accepted"},"401":{"description":"PLATPHORM_API_KEY required"}}}}},"tags":[{"name":"Discovery"},{"name":"Tools"},{"name":"Toolchains"},{"name":"MCP"},{"name":"OpenClaw"},{"name":"Integrations"},{"name":"Workflows"},{"name":"Persistence"},{"name":"Agent Policy"}],"x-claws-policy":{"publicRead":true,"protectedActionsRequire":"PLATPHORM_API_KEY","noGenericApiKeyExamples":true,"noFakeExecution":true}}