{"openapi":"3.1.0","info":{"title":"Verbaterm Developer API","version":"1.0.0","summary":"Judged, citation-checked policy intelligence — public corpus reads and plan-debit AI actions.","description":"Public library endpoints return Verbaterm-derived judged data only — never raw third-party policy text. Keyless public reads are capped; authenticated reads debit API credits. AI actions (private review, Ask) require a Clerk API key and debit the caller plan allowance. Informational only. Not legal advice.","contact":{"name":"Verbaterm","url":"https://verbaterm.com/developers"},"license":{"name":"Proprietary — see site terms","url":"https://verbaterm.com/legal"}},"servers":[{"url":"https://verbaterm.com","description":"Production"}],"tags":[{"name":"Discovery","description":"Machine-readable discovery and agent onboarding."},{"name":"Public library","description":"Keyless (~150/day/IP, 1–2 QPS) or API-credit authenticated corpus reads."},{"name":"Account","description":"API entitlement and current-month credit usage."},{"name":"AI actions","description":"Private review and Ask/Q&A — require API key; debit plan allowance."}],"paths":{"/api/v1":{"get":{"tags":["Discovery"],"operationId":"getApiDiscovery","summary":"API discovery document","responses":{"200":{"description":"Endpoint map, keyless caps, and notes.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/library":{"get":{"tags":["Public library"],"operationId":"listLibraryReviews","summary":"List published public-library reviews","security":[{},{"bearerAuth":[]}],"responses":{"200":{"description":"Published review summaries.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LibraryListItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/library/search":{"get":{"tags":["Public library"],"operationId":"searchLibraryReviews","summary":"Search the public policy corpus","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Company or product name."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Audience category slug."},{"name":"sort","in":"query","schema":{"type":"string","enum":["discover","az","recent"]}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Search results page.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/library/reviews/{companySlug}/{productSlug}/{policyKind}":{"get":{"tags":["Public library"],"operationId":"getLibraryReview","summary":"Full judged review for one published policy","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"companySlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"productSlug","in":"path","required":true,"schema":{"type":"string"}},{"name":"policyKind","in":"path","required":true,"schema":{"type":"string","enum":["terms","privacy","cookies","data_processing","other"]}}],"responses":{"200":{"description":"Findings with verbatim citation excerpts, scores, summary, provenance.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Review not found or not published."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/account":{"get":{"tags":["Account"],"operationId":"getApiAccount","summary":"API entitlement and current-month usage","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Account id, token type, and entitlement snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/reviews":{"post":{"tags":["AI actions"],"operationId":"startPrivateReview","summary":"Start a private paste-text review","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartReviewRequest"}}}},"responses":{"202":{"description":"Review accepted; poll progress/result URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartReviewResponse"}}}},"400":{"description":"Invalid input."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AllowanceExhausted"},"413":{"description":"Document exceeds plan character limit."}}}},"/api/v1/reviews/{sessionId}":{"get":{"tags":["AI actions"],"operationId":"getPrivateReview","summary":"Completed private review (no raw source text)","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Serialized review session.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown session for this account."}}}},"/api/v1/reviews/{sessionId}/progress":{"get":{"tags":["AI actions"],"operationId":"getPrivateReviewProgress","summary":"Poll private review pipeline progress","security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Progress snapshot.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Unknown session for this account."}}}},"/api/v1/ask":{"post":{"tags":["AI actions"],"operationId":"askReviewQuestion","summary":"Ask a citation-grounded question about a review","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"Answer with citations.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/AllowanceExhausted"},"404":{"description":"Review not found."},"503":{"description":"Ask temporarily unavailable."}}}},"/mcp":{"get":{"tags":["Discovery"],"operationId":"getMcpDiscovery","summary":"MCP server discovery (streamable HTTP)","responses":{"200":{"description":"MCP server info and tool summary.","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"tags":["Discovery"],"operationId":"postMcpJsonRpc","summary":"MCP JSON-RPC 2.0 (initialize, tools/list, tools/call)","description":"Public corpus tools work keyless; AI tools require Authorization Bearer API key.","security":[{},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC result or error.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clerk User/Organization API key created in Account → Developer API, or Clerk Dashboard."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key / session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"RateLimited":{"description":"Keyless IP cap or monthly API credits exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"AllowanceExhausted":{"description":"Plan review or Q&A allowance exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"schemas":{"ErrorBody":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}}},"LibraryListItem":{"type":"object","properties":{"companyName":{"type":"string"},"companySlug":{"type":"string"},"productName":{"type":"string"},"productSlug":{"type":"string"},"policyKind":{"type":"string"},"path":{"type":"string"}}},"ApiAccount":{"type":"object","properties":{"accountId":{"type":"string"},"tokenType":{"type":"string","enum":["session_token","api_key"]},"entitlement":{"type":"object","properties":{"tier":{"type":"string","enum":["free","hobby","standard","growth","custom"]},"monthlyCreditLimit":{"type":"integer"},"concurrencyLimit":{"type":"integer"},"creditsUsed":{"type":"integer"},"creditsRemaining":{"type":"integer"}}}}},"StartReviewRequest":{"type":"object","required":["policyText"],"properties":{"policyText":{"type":"string","minLength":80,"description":"Full pasted policy text."},"documentTitle":{"type":"string"},"policyKind":{"type":"string","enum":["terms","privacy","cookies","data_processing","other","auto"]}}},"StartReviewResponse":{"type":"object","properties":{"sessionId":{"type":"string"},"progressUrl":{"type":"string","format":"uri"},"resultUrl":{"type":"string","format":"uri"}}},"AskRequest":{"type":"object","required":["question","reviewRef"],"properties":{"question":{"type":"string","minLength":3},"reviewRef":{"oneOf":[{"type":"object","required":["kind","sessionId"],"properties":{"kind":{"const":"private"},"sessionId":{"type":"string"}}},{"type":"object","required":["kind","libraryReviewId"],"properties":{"kind":{"const":"public"},"libraryReviewId":{"type":"string"}}},{"type":"object","required":["kind","companySlug","productSlug","policyKind"],"properties":{"kind":{"const":"public_path"},"companySlug":{"type":"string"},"productSlug":{"type":"string"},"policyKind":{"type":"string"}}}]},"priorTurns":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}}}}}}},"externalDocs":{"description":"Developer marketing + pricing","url":"https://verbaterm.com/developers"}}