{"openapi":"3.1.0","info":{"title":"Veripoint Workspace API","version":"1.1.0","description":"Use a Veripoint workspace key to research companies, retrieve saved reports and inspect allowance. Research uses the same allowance as the website and MCP. Free allowance resets daily at 00:00 UTC; paid allowance resets monthly. Read-only keys cannot run research. Requests are limited to 60 per minute per key. This specification covers the implemented Veripoint workspace routes; separately licensed data APIs have their own contract and credentials."},"servers":[{"url":"https://veripoint.ai/api/v1"}],"security":[{"WorkspaceKey":[]}],"externalDocs":{"description":"API documentation and client setup","url":"https://veripoint.ai/api-docs/workspace-api"},"paths":{"/usage":{"get":{"operationId":"getWorkspaceUsage","summary":"Check workspace allowance","responses":{"200":{"description":"Current workspace usage. This call does not consume a search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"Invalid request or parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace or research permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Key rate limit or research allowance reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports":{"get":{"operationId":"listWorkspaceReports","summary":"Find saved workspace reports","parameters":[{"name":"q","in":"query","description":"Words to find in saved questions or answers.","schema":{"type":"string","maxLength":200}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}}],"responses":{"200":{"description":"At most 20 completed reports per page.","content":{"application/json":{"schema":{"type":"object","required":["reports","total","page","pages"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/Report"}},"total":{"type":"integer","minimum":0},"page":{"type":"integer","minimum":1},"pages":{"type":"integer","minimum":1}}}}}},"400":{"description":"Invalid request or parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace or research permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Key rate limit or research allowance reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}":{"get":{"operationId":"getWorkspaceReport","summary":"Retrieve a saved report and financial datasets","parameters":[{"name":"id","in":"path","required":true,"description":"Report ID returned by research or report listing; not a company ID.","schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Report belonging to the authorized workspace.","content":{"application/json":{"schema":{"type":"object","required":["report","financialStatements"],"properties":{"report":{"$ref":"#/components/schemas/Report"},"financialStatements":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Derived statement datasets. Fields depend on the available evidence."}}}}}},"400":{"description":"Invalid request or parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace or research permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Report unavailable, deleted or outside the authorized workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Key rate limit or research allowance reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/research":{"post":{"operationId":"researchCompanyFinancials","summary":"Research a company or compare company financials","description":"Requires a research-scoped workspace key. Returns SSE; read complete or error rather than treating HTTP 200 as a completed analysis. Completed analyses consume one search. The same requestId can identify an attempt but this API does not promise replay of a stored response; check saved reports before retrying an interrupted request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":3000,"description":"Identify the legal entity, jurisdiction and financial question."},"requestId":{"type":"string","format":"uuid","description":"Optional request identifier for progress/cancellation. It is not a general idempotency guarantee."},"conversationId":{"type":"string","description":"Continue the caller’s existing conversation; use the ID in the terminal event."},"companySelections":{"type":"array","maxItems":10,"items":{"type":"object","required":["lookupKey","companyId"],"properties":{"lookupKey":{"type":"string","maxLength":240},"companyId":{"type":"string","pattern":"^[0-9]{1,20}$"}},"additionalProperties":false},"description":"Confirm choices returned by an ambiguous lookup in this conversation."}},"additionalProperties":false},"example":{"query":"Analyse Microsoft Corporation (MSFT), United States. Show available revenue, operating margin and cash flow with periods, currency, scope and evidence."}}}},"responses":{"200":{"description":"Server-Sent Events stream. Events contain type and payload fields. Text fragments use type=text and content; tool_result includes data; terminal complete includes id, conversationId, kind (analysis or conversation), charged; error includes message. A clarification is not a charged financial analysis.","content":{"text/event-stream":{"schema":{"type":"string"},"example":"data: {\"type\":\"text\",\"content\":\"Example analysis fragment.\"}\n\ndata: {\"type\":\"complete\",\"id\":\"EXAMPLE_REPORT_ID\",\"kind\":\"analysis\",\"charged\":true}\n\n"}}},"400":{"description":"Invalid request or parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked workspace API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace or research permission denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Key rate limit or research allowance reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"WorkspaceKey":{"type":"http","scheme":"bearer","bearerFormat":"vp_live_<64 hexadecimal characters>","description":"Create a key inside your Veripoint workspace. Keep it in server or client secret settings; never put it in a URL or public source."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true},"Usage":{"type":"object","required":["workspaceId","plan","used","limit","remaining","resetAt"],"properties":{"workspaceId":{"type":"string"},"plan":{"type":"string"},"used":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"resetAt":{"type":"string","format":"date-time"}}},"Report":{"type":"object","required":["id","query","answer","tools","created_at"],"properties":{"id":{"type":"string"},"query":{"type":"string"},"answer":{"type":"string"},"tools":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Returned source evidence and tool results; preserve periods, currency, units and accounting scope."},"created_at":{"type":"string","format":"date-time"},"conversationId":{"type":["string","null"]}},"additionalProperties":true}}}}