{ "openapi": "3.1.0", "info": { "title": "Plith API", "description": "Agent infrastructure suite — task deduplication, cost prediction, output validation, behavioral governance, and cross-org failure learning. One API key, five products.", "version": "1.0.0", "contact": { "email": "support@plith.ai", "url": "https://plith.ai/docs" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://api.plith.ai", "description": "Production" } ], "security": [{ "ApiKeyAuth": [] }], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Plith API key. Create at POST /api/keys. Prefix: plth_" } }, "schemas": { "StandardMeta": { "type": "object", "required": ["request_id", "credits_used", "credits_remaining", "fallback_behavior"], "properties": { "request_id": { "type": "string", "example": "req_a1b2c3d4e5f6" }, "credits_used": { "type": "integer", "example": 1 }, "credits_remaining": { "type": "integer", "example": 4999 }, "fallback_behavior": { "type": "string", "example": "proceed_without_dedup" }, "cross_product": { "type": "string", "nullable": true } } }, "Error": { "type": "object", "required": ["error", "message", "request_id", "status"], "properties": { "error": { "type": "string", "example": "invalid_request" }, "message": { "type": "string", "example": "task_description is required." }, "request_id": { "type": "string" }, "status": { "type": "integer", "example": 400 }, "fix": { "type": "string", "nullable": true }, "docs": { "type": "string", "format": "uri" }, "support": { "type": "string", "example": "support@plith.ai" } } } }, "responses": { "401": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/keys": { "post": { "summary": "Create API key", "operationId": "createApiKey", "security": [], "tags": ["Auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "example": "dev@example.com" } } } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "example": "plth_7f8a9b2c..." }, "org_id": { "type": "string", "format": "uuid" }, "products": { "type": "array", "items": { "type": "string" } }, "free_tier": { "type": "object", "properties": { "calls_remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } }, "rate_limit": { "type": "string" }, "docs": { "type": "string", "format": "uri" } } } } } } } } }, "/api/health": { "get": { "summary": "Service health", "operationId": "getHealth", "security": [], "tags": ["Infrastructure"], "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ok", "degraded", "down"] }, "timestamp": { "type": "string", "format": "date-time" }, "services": { "type": "object", "properties": { "supabase": { "type": "object" }, "redis": { "type": "object" } } }, "products": { "type": "object" }, "version": { "type": "string" } } } } } } } } }, "/api/mcp": { "get": { "summary": "MCP tool manifest", "operationId": "getMcpManifest", "security": [], "tags": ["MCP"], "description": "Returns the MCP tool definition for registry discovery (Smithery, Composio, etc.)", "responses": { "200": { "description": "Tool manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol": { "type": "string" }, "version": { "type": "string" }, "server": { "type": "object" }, "tools": { "type": "array" } } } } } } } }, "post": { "summary": "MCP JSON-RPC endpoint", "operationId": "mcpJsonRpc", "tags": ["MCP"], "description": "JSON-RPC 2.0 MCP server. Supports: initialize, ping, tools/list, tools/call. The 'plith' tool accepts { action, params } where action is product.operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["jsonrpc", "method"], "properties": { "jsonrpc": { "type": "string", "enum": ["2.0"] }, "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }] }, "method": { "type": "string", "example": "tools/call" }, "params": { "type": "object" } } }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "plith", "arguments": { "action": "dedupq.check", "params": { "content": "Research competitive landscape", "task_id": "my-task-1" } } } } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "id": {}, "result": {}, "error": { "type": "object" } } } } } } } } }, "/api/dedupq/check": { "post": { "summary": "Check for duplicate task", "operationId": "dedupqCheck", "tags": ["DedupQ"], "description": "Semantic task-level deduplication. Not LLM-call caching — catches semantically similar tasks across agents, sessions, and frameworks. Costs 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "Task description to check for duplicates" }, "task_id": { "type": "string", "description": "Optional caller task ID for tracing" }, "hash_only": { "type": "boolean", "default": false, "description": "Skip semantic search, use hash matching only" }, "similarity_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.92 } } } } } }, "responses": { "200": { "description": "Dedup result (hit, miss, or locked)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "duplicate": { "type": "boolean" }, "match": { "type": "object", "properties": { "task_id": { "type": "string" }, "similarity": { "type": "number" }, "result": {}, "match_type": { "type": "string", "enum": ["exact", "semantic"] }, "cached_at": { "type": "string", "format": "date-time" } } }, "cache_hit": { "type": "string", "enum": ["redis", "db_exact", "vector"] } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" } } } }, "/api/dedupq/complete": { "post": { "summary": "Store completed task result", "operationId": "dedupqComplete", "tags": ["DedupQ"], "description": "Store the result of a completed task so future duplicate checks return it. Costs 2 credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["task_id", "result"], "properties": { "task_id": { "type": "string" }, "result": { "description": "Task result to cache (JSON or text)" }, "result_type": { "type": "string", "enum": ["json", "text", "code"], "default": "json" }, "result_summary": { "type": "string" }, "actual_cost": { "type": "number" }, "ttl_seconds": { "type": "integer", "default": 7200 }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Result stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } }, "401": { "$ref": "#/components/responses/401" }, "413": { "$ref": "#/components/responses/413" } } } }, "/api/dedupq/stats": { "get": { "summary": "DedupQ usage statistics", "operationId": "dedupqStats", "tags": ["DedupQ"], "description": "Returns cache hit rates, cost savings, and ROI for the current month. FREE.", "responses": { "200": { "description": "Statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "total_checks": { "type": "integer" }, "cache_hits": { "type": "integer" }, "hit_rate": { "type": "string" }, "total_cost_saved": { "type": "string" }, "cost_of_service": { "type": "string" }, "net_savings": { "type": "string" }, "roi": { "type": "string" } } } } } } } } }, "/api/burnrate/estimate": { "post": { "summary": "Estimate execution cost", "operationId": "burnrateEstimate", "tags": ["BurnRate"], "description": "Predict the cost of an agent plan before execution. Accepts precise token counts or approximate prompt lengths. Costs 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["plan"], "properties": { "plan": { "type": "array", "items": { "type": "object", "required": ["action", "provider"], "properties": { "step": { "type": "integer" }, "action": { "type": "string", "example": "llm_call" }, "provider": { "type": "string", "example": "anthropic" }, "model": { "type": "string", "example": "claude-sonnet-4-6" }, "estimated_input_tokens": { "type": "integer" }, "estimated_output_tokens": { "type": "integer" }, "prompt_length": { "type": "string", "enum": ["short", "medium", "long", "very_long"] }, "prompt_text_sample": { "type": "string" }, "count": { "type": "integer", "description": "For web_search actions" } } } }, "budget_limit": { "type": "number", "description": "Flag if total exceeds this USD amount" } } } } } }, "responses": { "200": { "description": "Cost estimate", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "estimate": { "type": "object", "properties": { "total_cost_usd_formatted": { "type": "string", "example": "$1.47" }, "within_budget": { "type": "boolean" }, "steps": { "type": "array" } } }, "optimization_suggestions": { "type": "array" } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" } } } }, "/api/burnrate/track": { "post": { "summary": "Record actual spend", "operationId": "burnrateTrack", "tags": ["BurnRate"], "description": "Record actual token spend after task execution. FREE. Improves future estimates.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["provider", "model", "actual_cost"], "properties": { "task_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "actual_cost": { "type": "number" } } } } } }, "responses": { "200": { "description": "Recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } } } } }, "/api/burnrate/optimize": { "post": { "summary": "Get cost optimizations", "operationId": "burnrateOptimize", "tags": ["BurnRate"], "description": "Returns ranked cost-reduction suggestions for a plan. Costs 1 credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["plan"], "properties": { "plan": { "type": "array" }, "max_suggestions": { "type": "integer", "default": 5 } } } } } }, "responses": { "200": { "description": "Optimization suggestions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } } } } }, "/api/burnrate/budget": { "get": { "summary": "Check daily budget", "operationId": "burnrateBudget", "tags": ["BurnRate"], "description": "Returns current spend vs daily budget. FREE.", "parameters": [ { "name": "daily_limit", "in": "query", "schema": { "type": "number" }, "description": "Daily USD budget limit" } ], "responses": { "200": { "description": "Budget status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } } } } }, "/api/qualitygate/validate": { "post": { "summary": "Validate agent output", "operationId": "qualitygateValidate", "tags": ["QualityGate"], "description": "Validates agent output against directives, schema, or code syntax. Deterministic — no LLM for most checks. Pattern checks cost 1 credit; LLM checks cost 8 credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["output"], "properties": { "output": { "type": "string", "description": "Agent output to validate" }, "directives": { "type": "array", "items": { "type": "string" }, "description": "Business rules the output must comply with" }, "check_types": { "type": "array", "items": { "type": "string", "enum": ["directive_compliance", "schema_validation", "code_syntax", "internal_consistency", "length", "tone", "factual_claims"] } }, "schema": { "type": "object", "description": "JSON Schema for schema_validation check" }, "language": { "type": "string", "description": "Language for code_syntax check (python, typescript, javascript)" }, "override": { "type": "boolean", "default": false }, "override_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "verdict": { "type": "string", "enum": ["pass", "warn", "fail"] }, "issues": { "type": "array" }, "recommendation": { "type": "string" }, "suggested_prompt_addition": { "type": "string" } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" } } } }, "/api/qualitygate/trends": { "get": { "summary": "Validation trends", "operationId": "qualitygateTrends", "tags": ["QualityGate"], "description": "Returns pass/fail rates, override rates, and directive effectiveness. FREE.", "responses": { "200": { "description": "Trend data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } } } } }, "/api/guardrail/check": { "post": { "summary": "Check action against policies", "operationId": "guardrailCheck", "tags": ["GuardRail"], "description": "Evaluates a proposed agent action against active governance policies. Deterministic rule evaluation — no LLM. Costs 1 credit. Fails open on DB unavailability.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["agent_id", "proposed_action"], "properties": { "agent_id": { "type": "string", "example": "sales-agent" }, "proposed_action": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "example": "send_email" }, "cost_estimate": { "type": "number" }, "description": { "type": "string" } }, "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Governance decision", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "decision": { "type": "string", "enum": ["allow", "deny"] }, "reason": { "type": "string" }, "policy_id": { "type": "string", "format": "uuid", "nullable": true }, "override": { "type": "object", "properties": { "available": { "type": "boolean" }, "requires": { "type": "string" } } }, "audit_id": { "type": "string", "format": "uuid", "nullable": true } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" } } } }, "/api/guardrail/policies": { "post": { "summary": "Create governance policy", "operationId": "guardrailCreatePolicy", "tags": ["GuardRail"], "description": "Create a behavioral policy with deterministic rules. Supports eq, starts_with, contains, gt, lt, and, or, not operators. FREE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "rules"], "properties": { "name": { "type": "string", "example": "no-outreach-build-mode" }, "description": { "type": "string" }, "rules": { "type": "array", "items": { "type": "object" }, "description": "Array of rule objects. All rules must match for policy to trigger (implicit AND).", "example": [{ "operator": "eq", "field": "type", "value": "send_email" }] }, "action_types": { "type": "array", "items": { "type": "string" }, "description": "Action types this policy applies to. Used for GIN index optimization." }, "priority": { "type": "integer", "default": 0, "description": "Higher priority policies evaluated first." } } } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMeta" } } } }, "409": { "description": "Policy name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List policies", "operationId": "guardrailListPolicies", "tags": ["GuardRail"], "description": "Returns all governance policies for the org. FREE.", "responses": { "200": { "description": "Policy list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "policies": { "type": "array" }, "total": { "type": "integer" } } } ] } } } } } } }, "/api/pitfalldb/query": { "post": { "summary": "Query known failure patterns", "operationId": "pitfalldbQuery", "tags": ["PitfallDB"], "description": "Returns known failure patterns for a task type, ranked by severity and report count. Semantic search if task_description provided. Only returns verified pitfalls. Costs 2 credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["task_type"], "properties": { "task_type": { "type": "string", "example": "code_generation" }, "task_description": { "type": "string", "example": "Generate multi-file MCP server in one LLM call" }, "filters": { "type": "object", "properties": { "language": { "type": "string", "example": "typescript" }, "framework": { "type": "string", "example": "langchain" }, "provider": { "type": "string", "example": "anthropic" } } } } } } } }, "responses": { "200": { "description": "Matching pitfalls", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "pitfalls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "title": { "type": "string" }, "description": { "type": "string" }, "frequency": { "type": "string" }, "reports": { "type": "integer" }, "fix": { "type": "string" }, "fix_confidence": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "applies_to": { "type": "object" } } } }, "total_matching": { "type": "integer" } } } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/402" } } } }, "/api/pitfalldb/report": { "post": { "summary": "Report a failure", "operationId": "pitfalldbReport", "tags": ["PitfallDB"], "description": "Submit an agent failure report. PII-scrubbed before storage. Contributes to the shared failure database. FREE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["task_type", "task_description", "failure"], "properties": { "task_type": { "type": "string", "example": "code_generation" }, "task_description": { "type": "string" }, "failure": { "type": "object", "properties": { "error_type": { "type": "string", "example": "json_parse_error" }, "error_message": { "type": "string" }, "root_cause": { "type": "string" }, "fix_applied": { "type": "string" }, "fix_worked": { "type": "boolean" }, "language": { "type": "string" }, "framework": { "type": "string" }, "provider": { "type": "string" } } } } } } } }, "responses": { "201": { "description": "Report stored", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "report_id": { "type": "string", "format": "uuid" }, "linked_pitfall_id": { "type": "string", "format": "uuid", "nullable": true }, "verified": { "type": "boolean" }, "message": { "type": "string" } } } ] } } } } } } }, "/api/pitfalldb/stats": { "get": { "summary": "PitfallDB statistics", "operationId": "pitfalldbStats", "tags": ["PitfallDB"], "description": "Returns aggregate database statistics: total pitfalls, total reports, top task types, recent activity. FREE.", "responses": { "200": { "description": "Database statistics", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/StandardMeta" }, { "type": "object", "properties": { "total_pitfalls": { "type": "integer" }, "total_reports": { "type": "integer" }, "top_task_types": { "type": "array", "items": { "type": "object", "properties": { "task_type": { "type": "string" }, "report_count": { "type": "integer" } } } }, "recent_activity": { "type": "object" } } } ] } } } } } } } }, "tags": [ { "name": "Auth", "description": "API key management" }, { "name": "Infrastructure", "description": "Health, changelog, data management" }, { "name": "MCP", "description": "Model Context Protocol server — single combined tool for all 5 products" }, { "name": "DedupQ", "description": "Semantic task deduplication across agents and sessions" }, { "name": "BurnRate", "description": "Pre-execution cost prediction and tracking" }, { "name": "QualityGate", "description": "Deterministic output validation against directives and schemas" }, { "name": "GuardRail", "description": "Framework-agnostic behavioral governance with policy rules" }, { "name": "PitfallDB", "description": "Cross-org anonymized failure learning database" } ] }