openapi: 3.1.0 info: title: Okra Document API version: 1.14.0 description: |- REST API for document ingestion, extraction, structured output, and collections. ## Authentication Most endpoints require a Bearer token (API key) in the `Authorization` header. Public document endpoints (GET) do not require authentication. contact: name: Okra API Support servers: - url: https://api.okrapdf.com description: Production security: - BearerApiKey: [] tags: - name: System description: Health and status endpoints. - name: Resources description: Discover top-level API nouns and action endpoints. - name: Context description: Context7-shaped PDF source tools with bounded, cited retrieval. - name: Authentication description: API key verification. - name: Agents description: Reusable agent profiles and deployed multi-document agents. - name: Files description: Passive PDF upload and retrieval primitives. - name: Jobs description: Long-running job status, lifecycle actions, and event streams. - name: Parse description: Stateless and file-backed parse jobs. - name: Uploads description: PDF upload jobs and direct-upload helpers. - name: Webhooks description: Webhook subscription management. - name: Renders description: Docless PDF rendering. - name: Layerizations description: PDF-to-layer graph jobs. - name: Sessions description: Document, agent, and environment sessions. - name: Tables description: Structured table metadata and ingest runs. - name: Host description: Publish PDFs to clean okrapdf.dev deployment hostnames. - name: Conversions description: One-call file conversion endpoints for hosted PDF assets. - name: Documents description: Document upload, retrieval, extraction, and management. - name: Public Sources description: Curated public source registry and admin indexing endpoints. - name: Collections description: Named groups of documents with cross-document query. - name: Filings description: Public SEC/exchange filing data. - name: Companies description: Public company metadata. - name: Configuration description: API key workflow defaults. - name: Exports description: Pre-formatted document exports. - name: Workflows description: Named document workflows and their runs. paths: /health: get: operationId: getHealth summary: Health check tags: - System security: [] responses: '200': description: Service is healthy. content: application/json: schema: type: object properties: status: type: string version: type: string timestamp: type: integer r2: type: object additionalProperties: type: string required: - status - version - timestamp /auth/verify: get: operationId: verifyAuth summary: Verify API key tags: - Authentication responses: '200': description: Key is valid. content: application/json: schema: type: object properties: authenticated: type: boolean const: true user_id: type: string key_id: type: string key_name: type: string key_type: type: string enum: - secret - publishable - internal scope: type: - string - 'null' scoped_orgs: type: array items: type: string scoped_projects: type: array items: type: string required: - authenticated - user_id - key_id - key_name '401': &ref_2 $ref: '#/components/responses/401' /v1/resources: get: operationId: listResources summary: List API resources description: Returns the top-level Okra API resource nouns and the verb-style action endpoints that create work. tags: - Resources security: [] responses: '200': description: API resource catalog. content: application/json: schema: type: object properties: object: type: string const: api_resource_catalog version: type: string data: type: array items: type: object properties: object: type: string const: api_resource name: type: string path: type: string description: type: string aliases: type: array items: type: string related_actions: type: array items: type: string operations: type: array items: type: object properties: method: type: string enum: &ref_0 - GET - POST - PATCH - PUT - DELETE path: type: string action: type: string description: type: string auth: type: string enum: &ref_1 - required - optional - public returns: type: string required: - method - path - action - description - auth required: - object - name - path - description - aliases - related_actions - operations actions: type: array items: type: object properties: object: type: string const: api_action name: type: string path: type: string description: type: string primary_resource: type: string returns: type: string operations: type: array items: type: object properties: method: type: string enum: *ref_0 path: type: string action: type: string description: type: string auth: type: string enum: *ref_1 returns: type: string required: - method - path - action - description - auth required: - object - name - path - description - primary_resource - returns - operations usage_hint: type: string required: - object - version - data - actions - usage_hint '400': &ref_3 $ref: '#/components/responses/400' '401': *ref_2 '403': &ref_4 $ref: '#/components/responses/403' '404': &ref_5 $ref: '#/components/responses/404' '409': &ref_6 $ref: '#/components/responses/409' '422': &ref_7 $ref: '#/components/responses/422' '429': &ref_8 $ref: '#/components/responses/429' '500': &ref_9 $ref: '#/components/responses/500' '504': &ref_10 $ref: '#/components/responses/504' /v1/resources/{name}: get: operationId: getResource summary: Get an API resource or action description: Returns one catalog entry by canonical resource name, alias, or action name. tags: - Resources security: [] parameters: - in: path name: name description: 'Resource name, alias, or action name. Examples: documents, docs, parse.' schema: type: string required: true responses: '200': description: API resource or action contract. content: application/json: schema: anyOf: - type: object properties: object: type: string const: api_resource name: type: string path: type: string description: type: string aliases: type: array items: type: string related_actions: type: array items: type: string operations: type: array items: type: object properties: method: type: string enum: *ref_0 path: type: string action: type: string description: type: string auth: type: string enum: *ref_1 returns: type: string required: - method - path - action - description - auth required: - object - name - path - description - aliases - related_actions - operations - type: object properties: object: type: string const: api_action name: type: string path: type: string description: type: string primary_resource: type: string returns: type: string operations: type: array items: type: object properties: method: type: string enum: *ref_0 path: type: string action: type: string description: type: string auth: type: string enum: *ref_1 returns: type: string required: - method - path - action - description - auth required: - object - name - path - description - primary_resource - returns - operations '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/context/resolve: post: operationId: resolveSource summary: Resolve a PDF source description: Resolve a URL, SHA-256, or title hint into an allowance-scoped PDF source for context navigation. tags: - Context security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: url: type: string format: uri sha256: type: string title_hint: type: string user_asserted_access: type: boolean responses: '200': description: Resolved PDF source. content: application/json: schema: type: object properties: object: type: string const: pdf_source source_id: type: string canonical_url: type: string format: uri sha256: type: string title: type: string page_count: type: number detected_license: type: object properties: status: type: string enum: - unknown - unlicensed - open_license - public_domain - permissioned - blocked label: type: string url: type: string format: uri confidence: type: number evidence: type: array items: type: string required: - status - label - confidence - evidence allowance_scope: type: string enum: &ref_11 - public_unlicensed - open_license - public_domain - user_private - owner_permissioned - blocked allowance_policy: type: object properties: structure: type: boolean cited_snippets: type: boolean qa: type: boolean summaries: type: string enum: &ref_12 - disabled - bounded - allowed full_text_export: type: boolean full_markdown: type: boolean read_full_section: type: boolean cross_user_cache: type: boolean requires_original_source: type: boolean max_snippet_chars: type: number max_context_tokens: type: number max_adjacent_snippets: type: number required: - structure - cited_snippets - qa - summaries - full_text_export - full_markdown - read_full_section - cross_user_cache - requires_original_source - max_snippet_chars - max_context_tokens - max_adjacent_snippets confidence: type: number warnings: type: array items: type: string is_synthetic: type: boolean required: - object - source_id - detected_license - allowance_scope - confidence - warnings '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: The live context index adapter is not connected yet. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: not_implemented message: type: string endpoint: type: string required: - code - message - endpoint code: type: string const: not_implemented message: type: string endpoint: type: string required: - error - code - message - endpoint '504': *ref_10 /v1/context/structure: post: operationId: readStructure summary: Read source structure description: Return navigable sections, page ranges, and detected artifacts for a resolved PDF source. tags: - Context security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: source_id: type: string max_depth: type: number include_artifacts: type: boolean required: - source_id responses: '200': description: Navigable PDF structure. content: application/json: schema: type: object properties: object: type: string const: pdf_structure source_id: type: string title: type: string canonical_url: type: string format: uri page_count: type: number pages_parsed: type: number coverage: type: string enum: - unknown - empty - partial - complete page_coverage: type: string enum: - unknown - empty - partial - complete page_coverage_percent: type: number allowance_scope: type: string enum: *ref_11 policy: type: object properties: structure: type: boolean cited_snippets: type: boolean qa: type: boolean summaries: type: string enum: *ref_12 full_text_export: type: boolean full_markdown: type: boolean read_full_section: type: boolean cross_user_cache: type: boolean requires_original_source: type: boolean max_snippet_chars: type: number max_context_tokens: type: number max_adjacent_snippets: type: number required: - structure - cited_snippets - qa - summaries - full_text_export - full_markdown - read_full_section - cross_user_cache - requires_original_source - max_snippet_chars - max_context_tokens - max_adjacent_snippets outline: type: array items: type: object properties: id: type: string title: type: string level: type: number kind: type: string enum: - front_matter - toc - section - subsection - appendix - table - figure - form - references - metadata page_start: type: number page_end: type: number parent_id: type: string path: type: array items: type: string token_estimate: type: number content_kinds: type: array items: type: string enum: - text - table - figure - form - appendix - references - metadata confidence: type: number summary_preview: type: string required: - id - title - level - page_start - token_estimate tables: type: array items: type: object properties: id: type: string title_hint: type: string page: type: number section_id: type: string columns: type: array items: type: string row_count_hint: type: number confidence: type: number required: - id - page - columns figures: type: array items: type: object properties: id: type: string title_hint: type: string page: type: number section_id: type: string columns: type: array items: type: string row_count_hint: type: number confidence: type: number required: - id - page - columns generated_at: type: string required: - object - source_id - allowance_scope - outline - tables - figures '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: The live context index adapter is not connected yet. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: not_implemented message: type: string endpoint: type: string required: - code - message - endpoint code: type: string const: not_implemented message: type: string endpoint: type: string required: - error - code - message - endpoint '504': *ref_10 /v1/context/get: post: operationId: getContext summary: Get bounded context description: Retrieve bounded, cited context blocks for a focused query against a resolved PDF source. tags: - Context security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: source_id: type: string query: type: string section_ids: type: array items: type: string context_scope: type: string enum: &ref_13 - metadata - structure - bounded_context - answer - source_redirect - full_text - full_markdown max_tokens: type: number required: - source_id - query responses: '200': description: Bounded context blocks with bbox citation URLs. content: application/json: schema: type: object properties: object: type: string const: pdf_context source_id: type: string query: type: string context_scope: type: string enum: *ref_13 context_blocks: type: array items: type: object properties: block_id: type: string kind: type: string enum: - snippet - table_summary - figure_summary - metadata - section_summary - navigation section_id: type: string page: type: number page_start: type: number page_end: type: number title: type: string text: type: string token_estimate: type: number citations: type: array items: type: object properties: page: type: number section_id: type: string source_url: type: string format: uri citation_url: type: string format: uri short_snippet: type: string bbox: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0 maximum: 1 h: type: number minimum: 0 maximum: 1 required: - x - 'y' - w - h bbox_source: type: string const: node required: - page - citation_url confidence: type: number required: - block_id - kind - text - token_estimate - citations citations: type: array items: type: object properties: page: type: number section_id: type: string source_url: type: string format: uri citation_url: type: string format: uri short_snippet: type: string bbox: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0 maximum: 1 h: type: number minimum: 0 maximum: 1 required: - x - 'y' - w - h bbox_source: type: string const: node required: - page - citation_url omitted_reason: type: string enum: - scope_limit - copyright_guardrail - token_budget - not_found - original_source_required policy: type: object properties: structure: type: boolean cited_snippets: type: boolean qa: type: boolean summaries: type: string enum: *ref_12 full_text_export: type: boolean full_markdown: type: boolean read_full_section: type: boolean cross_user_cache: type: boolean requires_original_source: type: boolean max_snippet_chars: type: number max_context_tokens: type: number max_adjacent_snippets: type: number required: - structure - cited_snippets - qa - summaries - full_text_export - full_markdown - read_full_section - cross_user_cache - requires_original_source - max_snippet_chars - max_context_tokens - max_adjacent_snippets required: - object - source_id - query - context_scope - context_blocks - citations '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: The live context index adapter is not connected yet. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: not_implemented message: type: string endpoint: type: string required: - code - message - endpoint code: type: string const: not_implemented message: type: string endpoint: type: string required: - error - code - message - endpoint '504': *ref_10 /v1/context/ask: post: operationId: askContext summary: Ask a source question description: Answer a focused question from bounded PDF context with required bbox citation URLs. tags: - Context security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: source_id: type: string question: type: string section_ids: type: array items: type: string max_answer_tokens: type: number required: - source_id - question responses: '200': description: Cited source answer. content: application/json: schema: type: object properties: object: type: string const: pdf_answer source_id: type: string question: type: string answer: type: string citations: type: array items: type: object properties: page: type: number section_id: type: string source_url: type: string format: uri citation_url: type: string format: uri short_snippet: type: string bbox: type: object properties: x: type: number minimum: 0 maximum: 1 'y': type: number minimum: 0 maximum: 1 w: type: number minimum: 0 maximum: 1 h: type: number minimum: 0 maximum: 1 required: - x - 'y' - w - h bbox_source: type: string const: node required: - page - citation_url confidence: type: number follow_up_sections: type: array items: type: string policy: type: object properties: structure: type: boolean cited_snippets: type: boolean qa: type: boolean summaries: type: string enum: *ref_12 full_text_export: type: boolean full_markdown: type: boolean read_full_section: type: boolean cross_user_cache: type: boolean requires_original_source: type: boolean max_snippet_chars: type: number max_context_tokens: type: number max_adjacent_snippets: type: number required: - structure - cited_snippets - qa - summaries - full_text_export - full_markdown - read_full_section - cross_user_cache - requires_original_source - max_snippet_chars - max_context_tokens - max_adjacent_snippets required: - object - source_id - question - answer - citations - confidence - follow_up_sections '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: The live context index adapter is not connected yet. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: not_implemented message: type: string endpoint: type: string required: - code - message - endpoint code: type: string const: not_implemented message: type: string endpoint: type: string required: - error - code - message - endpoint '504': *ref_10 /v1/context/open: post: operationId: openSource summary: Open original source description: Return an original-source URL for a resolved PDF source, optionally anchored to a page or section. tags: - Context security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: source_id: type: string page: type: number section_id: type: string required: - source_id responses: '200': description: Original source link. content: application/json: schema: type: object properties: object: type: string const: original_source_link source_id: type: string url: type: string format: uri page: type: number section_id: type: string required: - object - source_id - url '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: The live context index adapter is not connected yet. content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: not_implemented message: type: string endpoint: type: string required: - code - message - endpoint code: type: string const: not_implemented message: type: string endpoint: type: string required: - error - code - message - endpoint '504': *ref_10 /v1/agents: post: operationId: registerAgent summary: Register a reusable JSON-configured agent tags: - Agents requestBody: content: application/json: schema: type: object properties: id: type: string pattern: ^[a-z0-9][a-z0-9/-]*$ minLength: 1 maxLength: 64 name: type: string minLength: 1 maxLength: 128 description: type: string maxLength: 1000 prompt: type: string minLength: 1 maxLength: 10000 capabilities: type: array items: type: string enum: &ref_14 - read:pages - read:nodes - write:nodes - view:regions - read:metadata - network:fetch default: &ref_15 [] builtinTools: type: array items: type: string enum: &ref_16 - query_sql - query_document - view_page_region - get_job_metadata - get_live_status default: &ref_17 - query_sql output: type: object properties: type: type: string const: object properties: type: object additionalProperties: type: object properties: type: type: string description: type: string enum: type: array items: type: string minimum: type: number maximum: type: number required: - type required: type: array items: type: string required: - type - properties model: type: object properties: provider: type: string model: type: string required: - provider - model schedule: type: object properties: trigger: type: string cron: type: string context: type: object properties: pages: type: string default: all nodes: anyOf: - type: string - type: array items: type: string default: all redaction: type: string enum: &ref_18 - none - strip_pii - redact_values default: none required: - id - name - prompt - output responses: '201': description: Agent registered. content: application/json: schema: type: object properties: id: type: string status: type: string const: registered required: - id - status '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 get: operationId: listAgents summary: List visible built-in and custom agents tags: - Agents responses: '200': description: Visible agents. content: application/json: schema: type: object properties: agents: type: array items: type: object properties: id: type: string pattern: ^[a-z0-9][a-z0-9/-]*$ minLength: 1 maxLength: 64 name: type: string minLength: 1 maxLength: 128 description: type: string default: '' prompt: type: string minLength: 1 maxLength: 10000 capabilities: type: array items: type: string enum: *ref_14 default: *ref_15 builtinTools: type: array items: type: string enum: *ref_16 default: *ref_17 output: type: object properties: type: type: string const: object properties: type: object additionalProperties: type: object properties: type: type: string description: type: string enum: type: array items: type: string minimum: type: number maximum: type: number required: - type required: type: array items: type: string required: - type - properties model: type: object properties: provider: type: string model: type: string required: - provider - model schedule: type: object properties: trigger: type: string cron: type: string context: type: object properties: pages: type: string default: all nodes: anyOf: - type: string - type: array items: type: string default: all redaction: type: string enum: *ref_18 default: none required: - pages - nodes - redaction kind: type: string enum: &ref_19 - builtin - custom createdAt: type: - string - 'null' updatedAt: type: - string - 'null' required: - id - name - description - prompt - capabilities - builtinTools - output - kind required: - agents '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/{agentId}: get: operationId: getAgent summary: Get a visible agent definition tags: - Agents parameters: - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true responses: '200': description: Agent definition. content: application/json: schema: type: object properties: id: type: string pattern: ^[a-z0-9][a-z0-9/-]*$ minLength: 1 maxLength: 64 name: type: string minLength: 1 maxLength: 128 description: type: string default: '' prompt: type: string minLength: 1 maxLength: 10000 capabilities: type: array items: type: string enum: *ref_14 default: *ref_15 builtinTools: type: array items: type: string enum: *ref_16 default: *ref_17 output: type: object properties: type: type: string const: object properties: type: object additionalProperties: type: object properties: type: type: string description: type: string enum: type: array items: type: string minimum: type: number maximum: type: number required: - type required: type: array items: type: string required: - type - properties model: type: object properties: provider: type: string model: type: string required: - provider - model schedule: type: object properties: trigger: type: string cron: type: string context: type: object properties: pages: type: string default: all nodes: anyOf: - type: string - type: array items: type: string default: all redaction: type: string enum: *ref_18 default: none required: - pages - nodes - redaction kind: type: string enum: *ref_19 createdAt: type: - string - 'null' updatedAt: type: - string - 'null' required: - id - name - description - prompt - capabilities - builtinTools - output - kind '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 patch: operationId: updateAgent summary: Update an agent tags: - Agents parameters: - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 table_id: type: string minLength: 1 system: type: string minLength: 1 model: type: string minLength: 1 output_schema: {} email_prefix: type: string minLength: 2 responses: '200': description: Updated agent. content: application/json: schema: type: object properties: id: type: string minLength: 1 object: type: string const: agent name: type: string minLength: 1 model: type: - string - 'null' system: type: - string - 'null' output_schema: type: 'null' table_id: type: - string - 'null' email: type: - string - 'null' version: type: integer created_at: type: string updated_at: type: string required: - id - name additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteAgent summary: Delete a custom agent definition tags: - Agents parameters: - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true responses: '200': description: Agent deleted. content: application/json: schema: type: object properties: id: type: string status: type: string const: deleted required: - id - status '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/profiles: get: operationId: listAgentProfiles summary: List reusable agent profiles tags: - Agents responses: '200': description: Available built-in agent profiles. content: application/json: schema: type: object properties: profiles: type: array items: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 description: type: string minLength: 1 kind: type: string enum: &ref_22 - builtin - custom version: type: integer exclusiveMinimum: 0 default: type: boolean default: false resource_types: type: array items: type: string enum: &ref_23 - document - collection minItems: 1 defaults: type: object properties: instructions: type: string minLength: 1 model: type: object properties: chat: type: object properties: provider: type: string enum: &ref_20 - openrouter - anthropic - fireworks model: type: string minLength: 1 query: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 tools: type: object properties: builtinAllowlist: type: array items: type: string enum: &ref_24 - get_job_metadata - get_live_status - query_sql - query_document - view_page_region builtinToolPolicies: type: object properties: get_job_metadata: type: string enum: &ref_21 - allow - deny - delegate - client_handoff - server_only get_live_status: type: string enum: *ref_21 query_sql: type: string enum: *ref_21 query_document: type: string enum: *ref_21 view_page_region: type: string enum: *ref_21 completionToolMode: type: string enum: &ref_25 - builtin - codemode allowUserTools: type: boolean userToolPolicy: type: string enum: *ref_21 context: type: object properties: mode: type: string enum: &ref_26 - preloaded_only - tools_only - hybrid security: type: object properties: redactionRole: type: string enum: &ref_27 - admin - viewer - public sqlReadOnly: type: boolean allowReparseTool: type: boolean runtime: type: object properties: maxToolRounds: type: integer minimum: 0 maximum: 50 cacheDefault: type: boolean stream: type: boolean eval: type: object properties: enabled: type: boolean default: false scope: type: string enum: &ref_28 - document - user default: document instructions: type: string minLength: 1 model: type: object properties: provider: type: string enum: &ref_29 - anthropic - openrouter model: type: string minLength: 1 required: - provider - model additionalProperties: false maxRecentTurns: type: integer minimum: 0 maximum: 20 default: 5 required: - enabled - scope - maxRecentTurns additionalProperties: false required: - id - name - description - kind - version - default - resource_types - defaults required: - profiles '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/profiles/{id}: get: operationId: getAgentProfile summary: Get an agent profile tags: - Agents parameters: - in: path name: id description: Built-in agent profile identifier. schema: type: string required: true responses: '200': description: Resolved agent profile descriptor. content: application/json: schema: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 description: type: string minLength: 1 kind: type: string enum: *ref_22 version: type: integer exclusiveMinimum: 0 default: type: boolean default: false resource_types: type: array items: type: string enum: *ref_23 minItems: 1 defaults: type: object properties: instructions: type: string minLength: 1 model: type: object properties: chat: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 query: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 tools: type: object properties: builtinAllowlist: type: array items: type: string enum: *ref_24 builtinToolPolicies: type: object properties: get_job_metadata: type: string enum: *ref_21 get_live_status: type: string enum: *ref_21 query_sql: type: string enum: *ref_21 query_document: type: string enum: *ref_21 view_page_region: type: string enum: *ref_21 completionToolMode: type: string enum: *ref_25 allowUserTools: type: boolean userToolPolicy: type: string enum: *ref_21 context: type: object properties: mode: type: string enum: *ref_26 security: type: object properties: redactionRole: type: string enum: *ref_27 sqlReadOnly: type: boolean allowReparseTool: type: boolean runtime: type: object properties: maxToolRounds: type: integer minimum: 0 maximum: 50 cacheDefault: type: boolean stream: type: boolean eval: type: object properties: enabled: type: boolean default: false scope: type: string enum: *ref_28 default: document instructions: type: string minLength: 1 model: type: object properties: provider: type: string enum: *ref_29 model: type: string minLength: 1 required: - provider - model additionalProperties: false maxRecentTurns: type: integer minimum: 0 maximum: 20 default: 5 required: - enabled - scope - maxRecentTurns additionalProperties: false required: - id - name - description - kind - version - default - resource_types - defaults '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/deployments: post: operationId: deployAgent summary: Create an immutable multi-document agent deployment tags: - Agents requestBody: content: application/json: schema: type: object properties: documentIds: type: array items: type: string minItems: 1 maxItems: 20 name: type: string documents: type: array items: type: object properties: jobId: type: string fileName: type: string required: - jobId - fileName required: - documentIds responses: '200': description: Existing deployment reused for the same document set. content: application/json: schema: type: object properties: slug: type: string url: type: string format: uri embedUrl: type: string format: uri token: type: string tokenHint: type: string documentIds: type: array items: type: string documents: type: array items: type: object properties: jobId: type: string fileName: type: string required: - jobId - fileName name: type: - string - 'null' version: type: string createdAt: type: integer existing: type: boolean required: - slug - url - embedUrl - tokenHint - documentIds - documents - name - version - createdAt '201': description: New deployment created. content: application/json: schema: type: object properties: slug: type: string url: type: string format: uri embedUrl: type: string format: uri token: type: string tokenHint: type: string documentIds: type: array items: type: string documents: type: array items: type: object properties: jobId: type: string fileName: type: string required: - jobId - fileName name: type: - string - 'null' version: type: string createdAt: type: integer existing: type: boolean required: - slug - url - embedUrl - tokenHint - documentIds - documents - name - version - createdAt '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/{slug}/completion: post: operationId: completeAgent summary: Query a deployed multi-document agent tags: - Agents parameters: - in: path name: slug description: Immutable deployed agent slug. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: query: type: string minLength: 1 prompt: type: string minLength: 1 responses: '200': description: OpenAI-compatible SSE completion stream. content: text/event-stream: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/agents/{slug}/embed: post: operationId: embedAgent summary: Query a deployed multi-document agent without a token tags: - Agents parameters: - in: path name: slug description: Immutable deployed agent slug. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: query: type: string minLength: 1 prompt: type: string minLength: 1 responses: '200': description: OpenAI-compatible SSE completion stream. content: text/event-stream: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{docId}/agents/{agentId}/run: post: operationId: runDocumentAgent summary: Run an agent against a single document tags: - Agents parameters: - in: path name: docId description: Document ID (`doc-...`) or short hash. schema: type: string required: true - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: context: type: object properties: pages: type: string nodes: anyOf: - type: string - type: array items: type: string redaction: type: string enum: &ref_30 - none - strip_pii - redact_values sample: type: integer minimum: 1 maximum: 100 responses: '200': description: Agent run completed. content: application/json: schema: type: object properties: runId: type: string agentId: type: string documentId: type: string status: type: string const: completed output: {} durationMs: type: integer toolCalls: type: array items: {} costUsd: type: number tokensUsed: type: integer required: - runId - agentId - documentId - status - durationMs - toolCalls - costUsd - tokensUsed '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{docId}/agents/{agentId}/results: get: operationId: getAgentResults summary: List recent agent runs for a document tags: - Agents parameters: - in: path name: docId description: Document ID (`doc-...`) or short hash. schema: type: string required: true - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true responses: '200': description: Recent agent runs. content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string agent_id: type: string document_id: type: string status: type: string enum: - running - completed - failed output: {} started_at: type: string completed_at: type: - string - 'null' duration_ms: type: - integer - 'null' tool_calls: type: - integer - 'null' tokens_used: type: - integer - 'null' cost_usd: type: - number - 'null' created_at: type: - string - 'null' required: - id - agent_id - document_id - status - started_at required: - runs '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{colId}/agents/{agentId}/run: post: operationId: runCollectionAgent summary: Run an agent across the documents in a collection tags: - Agents parameters: - in: path name: colId description: Collection ID (`col-...`) or collection name. schema: type: string required: true - in: path name: agentId description: Custom or built-in agent identifier. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: context: type: object properties: pages: type: string nodes: anyOf: - type: string - type: array items: type: string redaction: type: string enum: *ref_30 sample: type: integer minimum: 1 maximum: 100 responses: '200': description: Collection fan-out completed. content: application/json: schema: type: object properties: collectionId: type: string agentId: type: string summary: type: object properties: documents_evaluated: type: integer documents_passed: type: integer documents_failed: type: integer average_score: type: number required: - documents_evaluated - documents_passed - documents_failed - average_score results: type: array items: oneOf: - type: object properties: documentId: type: string runId: type: string status: type: string const: completed output: {} required: - documentId - runId - status - type: object properties: documentId: type: string runId: type: string status: type: string const: failed error: type: string required: - documentId - runId - status - error required: - collectionId - agentId - summary - results '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files: get: operationId: listFiles summary: List files tags: - Files parameters: - in: query name: limit schema: type: integer exclusiveMinimum: 0 maximum: 100 - in: query name: cursor schema: type: string - in: query name: purpose schema: type: string enum: - document - asset - all - in: query name: q schema: type: string responses: '200': description: List of uploaded files. Defaults to passive PDF files; pass purpose=asset for private reference files. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: &ref_31 - multipart - presigned - url purpose: type: string enum: &ref_32 - document - asset default: document kind: type: string enum: &ref_33 - document - asset default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls has_more: type: boolean next_cursor: type: - string - 'null' required: - object - data - has_more - next_cursor '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createFile summary: Upload a passive PDF or private reference file tags: - Files requestBody: description: >- Upload a PDF without automatically starting a parsing workflow, or upload a non-PDF private reference file with purpose=asset. For PNG/JPEG assets, pass derive_pdf=true to also create a hosted PDF derivative. content: multipart/form-data: schema: type: object properties: file: {} purpose: type: string enum: - document - asset derive_pdf: type: boolean paper_size: type: string enum: - letter - a4 - image orientation: type: string enum: - portrait - landscape - auto fit: type: string enum: - contain - cover pdf_file_name: type: string public_id: type: string org_id: type: string project_id: type: string config: type: string responses: '200': description: Duplicate file found for this user. Existing file returned. content: application/json: schema: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document deduplicated: type: boolean const: true required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls - deduplicated '201': description: File stored successfully. content: application/json: schema: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document deduplicated: type: boolean const: false required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls - deduplicated '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files/presign: post: operationId: presignFile summary: Create a direct-to-R2 upload session for a PDF tags: - Files requestBody: content: application/json: schema: type: object properties: fileName: type: string fileSize: type: integer exclusiveMinimum: 0 sha256: type: string responses: '200': description: Either an existing duplicate file or a new upload session. content: application/json: schema: anyOf: - type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document deduplicated: type: boolean const: true required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls - deduplicated - type: object properties: id: type: string file_id: type: string object: type: string const: file_upload file_name: type: string r2_key: type: string upload_url: type: string format: uri upload_method: type: string const: PUT upload_headers: type: object additionalProperties: type: string finalize_url: type: string format: uri expires_in: type: integer exclusiveMinimum: 0 max_bytes: type: integer exclusiveMinimum: 0 workflow_bound: type: boolean const: false required: - id - file_id - object - file_name - r2_key - upload_url - upload_method - upload_headers - finalize_url - expires_in - max_bytes - workflow_bound '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files/finalize: post: operationId: finalizeFile summary: Finalize a direct-to-R2 PDF upload tags: - Files requestBody: content: application/json: schema: type: object properties: id: type: string fileName: type: string r2Key: type: string sha256: type: string org_id: type: string project_id: type: string config: type: string required: - id responses: '200': description: Duplicate file found for this user. Existing file returned. content: application/json: schema: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document deduplicated: type: boolean const: true required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls - deduplicated '201': description: File finalized successfully. content: application/json: schema: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document deduplicated: type: boolean const: false required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls - deduplicated '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files/{id}: get: operationId: getFile summary: Get file metadata tags: - Files parameters: - in: path name: id schema: type: string required: true responses: '200': description: File metadata. content: application/json: schema: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteFile summary: Delete a file tags: - Files parameters: - in: path name: id schema: type: string required: true responses: '204': description: File deleted successfully. '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files/{id}/bytes: get: operationId: getFileBytes summary: Download private file bytes tags: - Files parameters: - in: path name: id schema: type: string required: true responses: '200': description: Raw private file bytes. content: application/octet-stream: schema: {} '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/files/{id}/pdf: post: operationId: createFilePdf summary: Create a hosted PDF from an uploaded image asset tags: - Files - Conversions parameters: - in: path name: id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: paper_size: type: string enum: - letter - a4 - image orientation: type: string enum: - portrait - landscape - auto fit: type: string enum: - contain - cover file_name: type: string public_id: type: string responses: '201': description: Hosted PDF derivative created. content: application/json: schema: type: object properties: object: type: string const: conversion.image2pdf response: type: string format: uri file: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls pdf: type: object properties: object: type: string const: file_pdf_derivative source_file_id: type: string source_sha256: type: string pdf_sha256: type: string size: type: integer minimum: 0 page_count: type: integer exclusiveMinimum: 0 paper_size: type: string enum: &ref_43 - letter - a4 - image orientation: type: string enum: &ref_44 - portrait - landscape fit: type: string enum: &ref_45 - contain - cover r2_key: type: string preview_r2_key: type: string manifest_r2_key: type: string urls: type: object properties: pdf: type: string format: uri download: type: string format: uri preview: type: string format: uri thumbnail: type: string format: uri manifest: type: string format: uri required: - pdf - download - preview - thumbnail - manifest required: - object - source_file_id - source_sha256 - pdf_sha256 - size - page_count - paper_size - orientation - fit - r2_key - preview_r2_key - manifest_r2_key - urls required: - object - response - file - pdf '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs: get: operationId: listJobs summary: List jobs tags: - Jobs parameters: - in: query name: status schema: type: string enum: - queued - running - idle - awaiting_user_input - completed - completed_with_errors - failed - cancelled - succeeded - broken - in: query name: type schema: type: string - in: query name: job_type schema: type: string - in: query name: document_id schema: type: string - in: query name: documentId schema: type: string - in: query name: limit schema: type: integer minimum: 1 maximum: 100 - in: query name: hydrate description: Pass 0 to skip live hydration. schema: type: string - in: query name: live description: Pass 0 to skip live hydration. schema: type: string responses: '200': description: List of jobs. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - object - data - has_more - next_cursor '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createJob summary: Create a job description: >- Create a durable job. For document parsing, send `{ "type": "document.parse", "document_id": "doc-..." }`; the Worker forwards to the document lifecycle workflow and returns the job resource to poll or wait on. tags: - Jobs security: - BearerApiKey: [] requestBody: required: true content: application/json: schema: type: object properties: type: type: string document_id: type: string documentId: type: string document: type: string strategy: type: string engine: type: string processor: type: string parser: anyOf: - type: string - type: object additionalProperties: true required: - type additionalProperties: true responses: '202': description: Job accepted. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs/{job_id}: get: operationId: getJob summary: Get a job tags: - Jobs parameters: - in: path name: job_id schema: type: string required: true - in: query name: format schema: type: string - in: query name: formats schema: type: string - in: query name: output_format schema: type: string - in: query name: expand schema: type: string responses: '200': description: Job status, result, usage, and error details. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs/{job_id}/events: get: operationId: getJobEvents summary: Stream job events tags: - Jobs parameters: - in: path name: job_id schema: type: string required: true - in: query name: format schema: type: string - in: query name: formats schema: type: string - in: query name: output_format schema: type: string - in: query name: expand schema: type: string responses: '200': description: Server-sent event stream containing a job snapshot event. content: text/event-stream: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs/{job_id}/cancel: post: operationId: cancelJob summary: Cancel a job tags: - Jobs parameters: - in: path name: job_id schema: type: string required: true responses: '200': description: Job after cancellation attempt. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs/{job_id}/retry: post: operationId: retryJob summary: Retry failed job pages tags: - Jobs parameters: - in: path name: job_id schema: type: string required: true responses: '202': description: Job retry accepted. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/jobs/{job_id}/resume: post: operationId: resumeJob summary: Resume queued job pages tags: - Jobs parameters: - in: path name: job_id schema: type: string required: true responses: '202': description: Job resume accepted. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string url: type: string created: type: integer completed: type: - integer - 'null' livemode: type: boolean job_id: type: string job_type: type: string job_label: type: - string - 'null' status: type: string internal_status: type: string document_id: type: - string - 'null' file_name: type: - string - 'null' run_id: type: - string - 'null' workflow_name: type: - string - 'null' workflow_id: type: - string - 'null' engine_id: type: - string - 'null' provider: type: - string - 'null' model: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total additionalProperties: true pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 cost_usd: type: number minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message request: type: 'null' result: type: 'null' metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' required: - object - id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/parse: post: operationId: createParseJob summary: Create a parse job tags: - Parse requestBody: content: application/json: schema: type: object properties: file: type: object properties: data: type: string id: type: string mime_type: type: string mimeType: type: string inlineData: type: object properties: data: type: string mimeType: type: string mime_type: type: string inline_data: type: object properties: data: type: string mimeType: type: string mime_type: type: string parser: anyOf: - type: string - type: object properties: id: type: string variant: type: string options: type: object additionalProperties: true vendor_options: type: object additionalProperties: true additionalProperties: true variant: type: string pages: {} format: {} output_format: {} transformation: {} transformations: {} outputs: {} publish: {} metadata: type: object additionalProperties: true options: type: object additionalProperties: true vendor_options: type: object additionalProperties: true schema: {} file_name: type: string required: - file responses: '202': description: Parse job queued. content: application/json: schema: type: object properties: object: type: string const: job id: type: string type: type: string const: parse status: type: string enum: - queued - running - idle - awaiting_user_input - succeeded - completed - completed_with_errors - failed - cancelled created: type: integer completed: type: - integer - 'null' livemode: type: boolean url: type: string status_url: type: string job_id: type: string job_type: type: string const: parse job_label: type: - string - 'null' file_name: type: - string - 'null' progress_current: type: integer minimum: 0 progress_total: type: integer minimum: 0 progress: type: object properties: phase: type: string current: type: integer minimum: 0 total: type: integer minimum: 0 pages_done: type: integer minimum: 0 pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 required: - phase - current - total - pages_done - pages_completed - pages_failed - pages_running - pages_pending - pages_total - chunks_completed - chunks_total pages_completed: type: integer minimum: 0 pages_failed: type: integer minimum: 0 pages_running: type: integer minimum: 0 pages_pending: type: integer minimum: 0 pages_total: type: integer minimum: 0 chunks_completed: type: integer minimum: 0 chunks_total: type: integer minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 error: type: - string - 'null' latest_error: type: - string - 'null' request: type: - object - 'null' additionalProperties: true result: type: - object - 'null' properties: object: type: string const: parse_result job: type: string usage: type: object properties: pages: type: integer minimum: 0 duration_ms: type: - integer - 'null' minimum: 0 required: - pages formats: type: object additionalProperties: true extracted: type: - object - 'null' properties: data: {} schema_valid: type: boolean required: - schema_valid artifacts: type: - object - 'null' additionalProperties: {} required: - object - job - usage additionalProperties: true metadata: type: object additionalProperties: true created_at: type: integer updated_at: type: integer completed_at: type: - integer - 'null' last_error: type: - object - 'null' properties: message: type: string required: - message required: - object - id - type - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/upload: post: operationId: createUpload summary: Upload a PDF and start upload engines tags: - Uploads requestBody: content: multipart/form-data: schema: type: object properties: file: {} file_name: type: string fileName: type: string deployment: type: string preset: type: string engines: anyOf: - type: string - type: array items: type: string engine: anyOf: - type: string - type: array items: type: string public_id: type: string publicId: type: string folder: type: string overwrite: type: boolean metadata: anyOf: - type: string - type: object additionalProperties: true tags: anyOf: - type: string - type: array items: type: string notification_url: type: string responses: '202': description: Upload job queued. content: application/json: schema: type: object properties: id: type: string object: type: string const: engine.job type: type: string const: upload job_id: type: string status: type: string source: type: object properties: kind: type: string const: pdf id: type: string file_id: type: string filename: type: string content_type: type: string sha256: type: string href: type: string bytes: type: integer minimum: 0 metadata: type: object additionalProperties: true required: - kind - id - file_id - filename - content_type - sha256 - href additionalProperties: true deployment: type: object properties: id: type: string name: type: string hostname: type: string url: type: string required: - id - name - hostname - url engines: type: array items: type: object properties: key: type: string enum: &ref_34 - host - thumbnail - extract id: type: string engine_id: type: string job_id: type: string built_in: type: boolean required: - key - id - engine_id - job_id - built_in output: type: 'null' output_url: type: string poll_url: type: string events_url: type: string cancel_url: type: string progress: type: object additionalProperties: true metadata: type: object additionalProperties: true created_at: type: string updated_at: type: string required: - id - object - type - job_id - status - source - deployment - engines - poll_url - events_url - cancel_url - progress - metadata - created_at - updated_at additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/upload/presign: post: operationId: presignUpload summary: Create a direct upload session tags: - Uploads requestBody: content: application/json: schema: type: object properties: fileName: type: string file_name: type: string fileSize: type: integer exclusiveMinimum: 0 file_size: type: integer exclusiveMinimum: 0 mime: type: string content_type: type: string sha256: type: string deployment: type: string preset: type: string engines: anyOf: - type: string - type: array items: type: string public_id: type: string publicId: type: string folder: type: string overwrite: type: boolean metadata: type: object additionalProperties: true tags: anyOf: - type: string - type: array items: type: string notification_url: type: string notificationUrl: type: string responses: '202': description: Direct upload session created. content: application/json: schema: type: object properties: object: type: string const: upload_session id: type: string upload_id: type: string job_id: type: string source: type: object properties: kind: type: string const: pdf id: type: string file_id: type: string filename: type: string content_type: type: string sha256: type: string href: type: string bytes: type: integer minimum: 0 metadata: type: object additionalProperties: true required: - kind - id - file_id - filename - content_type - sha256 - href additionalProperties: true deployment: type: object properties: id: type: string name: type: string hostname: type: string url: type: string required: - id - name - hostname - url engines: type: array items: type: object properties: key: type: string enum: *ref_34 id: type: string engine_id: type: string job_id: type: string built_in: type: boolean required: - key - id - engine_id - job_id - built_in upload_url: type: string upload_method: type: string const: PUT upload_headers: type: object additionalProperties: type: string finalize_url: type: string poll_url: type: string events_url: type: string output_url: type: string expires_in: type: integer exclusiveMinimum: 0 max_bytes: type: integer exclusiveMinimum: 0 required: - object - id - upload_id - job_id - source - deployment - engines - upload_url - upload_method - upload_headers - finalize_url - poll_url - events_url - output_url - expires_in - max_bytes '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/upload/finalize: post: operationId: finalizeUpload summary: Finalize a direct upload tags: - Uploads requestBody: content: application/json: schema: type: object properties: id: type: string upload_id: type: string uploadId: type: string sha256: type: string fileSize: type: integer exclusiveMinimum: 0 file_size: type: integer exclusiveMinimum: 0 responses: '202': description: Upload finalized and job queued. content: application/json: schema: type: object properties: id: type: string object: type: string const: engine.job type: type: string const: upload job_id: type: string status: type: string source: type: object properties: kind: type: string const: pdf id: type: string file_id: type: string filename: type: string content_type: type: string sha256: type: string href: type: string bytes: type: integer minimum: 0 metadata: type: object additionalProperties: true required: - kind - id - file_id - filename - content_type - sha256 - href additionalProperties: true deployment: type: object properties: id: type: string name: type: string hostname: type: string url: type: string required: - id - name - hostname - url engines: type: array items: type: object properties: key: type: string enum: *ref_34 id: type: string engine_id: type: string job_id: type: string built_in: type: boolean required: - key - id - engine_id - job_id - built_in output: type: 'null' output_url: type: string poll_url: type: string events_url: type: string cancel_url: type: string progress: type: object additionalProperties: true metadata: type: object additionalProperties: true created_at: type: string updated_at: type: string required: - id - object - type - job_id - status - source - deployment - engines - poll_url - events_url - cancel_url - progress - metadata - created_at - updated_at additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/webhooks: get: operationId: listWebhooks summary: List webhooks tags: - Webhooks responses: '200': description: List of webhook subscriptions. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: object: type: string const: webhook id: type: string event: type: string enum: &ref_35 - document.created - document.processed - document.deleted - document.failed facet_filter: type: - string - 'null' target_url: type: string source: type: string enum: &ref_36 - api - zapier - make - n8n - manual secret_prefix: type: string created_at: type: string last_delivered_at: type: - string - 'null' last_status: type: - integer - 'null' failure_count: type: integer minimum: 0 disabled_at: type: - string - 'null' required: - object - id - event - facet_filter - target_url - source - secret_prefix - created_at - last_delivered_at - last_status - failure_count - disabled_at required: - object - data '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createWebhook summary: Create a webhook tags: - Webhooks requestBody: required: true content: application/json: schema: type: object properties: event: type: string enum: *ref_35 target_url: type: string format: uri url: type: string format: uri facet_filter: type: - string - 'null' source: type: string enum: *ref_36 required: - event - target_url responses: '201': description: Webhook subscription created. The signing secret is returned once. content: application/json: schema: type: object properties: object: type: string const: webhook id: type: string event: type: string enum: *ref_35 facet_filter: type: - string - 'null' target_url: type: string source: type: string enum: *ref_36 secret_prefix: type: string created_at: type: string last_delivered_at: type: - string - 'null' last_status: type: - integer - 'null' failure_count: type: integer minimum: 0 disabled_at: type: - string - 'null' secret: type: string required: - object - id - event - facet_filter - target_url - source - secret_prefix - created_at - last_delivered_at - last_status - failure_count - disabled_at - secret '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/webhooks/{id}: get: operationId: getWebhook summary: Get a webhook tags: - Webhooks parameters: - in: path name: id schema: type: string required: true responses: '200': description: Webhook subscription. content: application/json: schema: type: object properties: object: type: string const: webhook id: type: string event: type: string enum: *ref_35 facet_filter: type: - string - 'null' target_url: type: string source: type: string enum: *ref_36 secret_prefix: type: string created_at: type: string last_delivered_at: type: - string - 'null' last_status: type: - integer - 'null' failure_count: type: integer minimum: 0 disabled_at: type: - string - 'null' required: - object - id - event - facet_filter - target_url - source - secret_prefix - created_at - last_delivered_at - last_status - failure_count - disabled_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteWebhook summary: Delete a webhook tags: - Webhooks parameters: - in: path name: id schema: type: string required: true responses: '204': description: Webhook deleted. '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/renders: post: operationId: createRender summary: Render a PDF tags: - Renders parameters: - in: query name: format description: Pass pdf to request raw PDF bytes. schema: type: string enum: - pdf requestBody: content: application/json: schema: anyOf: - type: object properties: mode: type: string const: reportlab script: type: string files: anyOf: - type: object additionalProperties: anyOf: - type: string - type: object properties: content: type: string encoding: type: string enum: - utf-8 - base64 required: - content - type: array items: type: object properties: path: type: string content: type: string encoding: type: string enum: - utf-8 - base64 required: - path - content fileName: type: string persist: type: boolean publish: anyOf: - type: boolean - type: object properties: enabled: type: boolean publicId: type: string slug: type: string fileName: type: string cacheControl: type: string metadata: type: object additionalProperties: type: string source: anyOf: - type: boolean - type: object properties: enabled: type: boolean includeInput: type: boolean includeModules: type: boolean llm: type: string readme: type: string additionalProperties: true llm: type: string readme: type: string additionalProperties: true outputPath: type: string timeoutSeconds: type: number exclusiveMinimum: 0 required: - mode - script additionalProperties: true - type: object properties: mode: type: string const: exec code: type: string input: {} modules: type: object additionalProperties: type: string fileName: type: string persist: type: boolean publish: anyOf: - type: boolean - type: object properties: enabled: type: boolean publicId: type: string slug: type: string fileName: type: string cacheControl: type: string metadata: type: object additionalProperties: type: string source: anyOf: - type: boolean - type: object properties: enabled: type: boolean includeInput: type: boolean includeModules: type: boolean llm: type: string readme: type: string additionalProperties: true llm: type: string readme: type: string additionalProperties: true timeoutMs: type: integer exclusiveMinimum: 0 required: - mode - code additionalProperties: true - type: object properties: mode: type: string const: designed spec: type: object properties: title: type: string required: - title additionalProperties: true fileName: type: string persist: type: boolean publish: anyOf: - type: boolean - type: object properties: enabled: type: boolean publicId: type: string slug: type: string fileName: type: string cacheControl: type: string metadata: type: object additionalProperties: type: string source: anyOf: - type: boolean - type: object properties: enabled: type: boolean includeInput: type: boolean includeModules: type: boolean llm: type: string readme: type: string additionalProperties: true llm: type: string readme: type: string additionalProperties: true required: - mode - spec additionalProperties: true responses: '200': description: Rendered PDF metadata, or raw PDF bytes when requested by Accept or format=pdf. content: application/json: schema: type: object properties: ok: type: boolean const: true render_id: type: string sha256: type: string size: type: integer minimum: 0 document_id: type: - string - 'null' download_url: type: - string - 'null' public_url: type: - string - 'null' published_url: type: - string - 'null' publish_base_url: type: - string - 'null' source_url: type: - string - 'null' file_name: type: string required: - ok - render_id - sha256 - size - document_id - download_url - public_url - published_url - publish_base_url - source_url - file_name application/pdf: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/layerizations: post: operationId: createLayerization summary: Create a layerization job tags: - Layerizations security: [] requestBody: content: application/json: schema: type: object properties: source: anyOf: - type: object properties: type: type: string const: image image: type: string required: - type - image - type: object properties: type: type: string const: pdf pdf: type: string page: type: integer minimum: 1 required: - type - pdf provider: type: string metadata: type: - object - 'null' additionalProperties: true required: - source responses: '202': description: Layerization job accepted. content: application/json: schema: type: object properties: id: type: string object: type: string const: layerization status: type: string const: running required: - id - object - status '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/layerizations/{job_id}: get: operationId: getLayerization summary: Get a layerization job tags: - Layerizations security: [] parameters: - in: path name: job_id schema: type: string required: true responses: '200': description: Layerization status or completed layer graph. content: application/json: schema: anyOf: - type: object properties: id: type: string object: type: string const: layerization status: type: string const: running required: - id - object - status - type: object properties: id: type: string object: type: string const: layerization status: type: string const: failed error: type: string required: - id - object - status - error - type: object properties: id: type: string object: type: string const: layerization status: type: string const: complete created: type: integer exclusiveMinimum: 0 source: type: object properties: type: type: string const: image required: - type provider: type: string provider_version: type: string cached: type: boolean composition_id: type: 'null' layer_graph: type: object properties: schema_version: type: string capabilities: type: array items: type: string page: type: object properties: width: type: number exclusiveMinimum: 0 height: type: number exclusiveMinimum: 0 required: - width - height layers: type: array items: anyOf: - type: object properties: id: type: string type: type: string const: image url: type: string frame: type: object properties: x: type: number 'y': type: number w: type: number exclusiveMinimum: 0 h: type: number exclusiveMinimum: 0 required: - x - 'y' - w - h provenance: type: object properties: kind: type: string const: detected provider: type: string provider_version: type: string confidence: type: - number - 'null' minimum: 0 maximum: 1 required: - kind - provider - provider_version - confidence binding: type: 'null' required: - id - type - url - frame - provenance - binding - type: object properties: id: type: string type: type: string const: text text: type: string frame: type: object properties: x: type: number 'y': type: number w: type: number exclusiveMinimum: 0 h: type: number exclusiveMinimum: 0 required: - x - 'y' - w - h style: type: object properties: font_family: type: string font_style: type: string font_size: type: number exclusiveMinimum: 0 color: type: string text_anchor: type: string enum: - start - middle - end required: - font_family - font_style - font_size - color - text_anchor provenance: type: object properties: kind: type: string const: detected provider: type: string provider_version: type: string confidence: type: - number - 'null' minimum: 0 maximum: 1 required: - kind - provider - provider_version - confidence binding: type: 'null' required: - id - type - text - frame - style - provenance - binding required: - schema_version - capabilities - page - layers cost: type: - object - 'null' properties: amount: type: number minimum: 0 currency: type: string const: credits required: - amount - currency livemode: type: boolean metadata: type: - object - 'null' additionalProperties: true required: - id - object - status - created - source - provider - provider_version - cached - composition_id - layer_graph - cost - livemode - metadata '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/sessions: get: operationId: listSessions summary: List sessions tags: - Sessions parameters: - in: query name: cursor schema: type: string - in: query name: limit schema: type: integer minimum: 1 maximum: 100 - in: query name: include_deleted schema: type: boolean - in: query name: document_id schema: type: string - in: query name: agent_id schema: type: string responses: '200': description: List of sessions. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string object: type: string const: session title: type: - string - 'null' model: type: - string - 'null' agent_id: type: - string - 'null' status: type: - string - 'null' document_id: type: - string - 'null' document_ids: type: array items: type: string message_count: type: integer minimum: 0 created_at: type: string last_active: type: string deleted_at: type: - string - 'null' required: - id additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - data additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createSession summary: Create a session tags: - Sessions requestBody: content: application/json: schema: type: object properties: documents: type: array items: anyOf: - type: string - type: object properties: id: type: string document_id: type: string name: type: string displayName: type: string default: [] model: type: string agent_id: type: string environment_id: type: string project_id: type: string create_environment: {} ui_capabilities: type: object properties: slots: type: array items: type: object properties: id: type: string title: type: string description: type: string accepts: type: array items: type: string required: - id mode: type: string enum: - extract - chat - create title: type: string responses: '201': description: Session created. content: application/json: schema: type: object properties: id: type: string object: type: string const: session title: type: - string - 'null' model: type: - string - 'null' agent_id: type: - string - 'null' status: type: - string - 'null' document_id: type: - string - 'null' document_ids: type: array items: type: string message_count: type: integer minimum: 0 created_at: type: string last_active: type: string deleted_at: type: - string - 'null' required: - id additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/sessions/{session_id}: get: operationId: getSession summary: Get a session tags: - Sessions parameters: - in: path name: session_id schema: type: string required: true - in: query name: include_deleted schema: type: boolean responses: '200': description: Session detail with message history. content: application/json: schema: type: object properties: id: type: string object: type: string const: session title: type: - string - 'null' model: type: - string - 'null' agent_id: type: - string - 'null' status: type: - string - 'null' document_id: type: - string - 'null' document_ids: type: array items: type: string message_count: type: integer minimum: 0 created_at: type: string last_active: type: string deleted_at: type: - string - 'null' messages: type: array items: {} default: [] required: - id - messages additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/sessions/{session_id}/events: get: operationId: getSessionEvents summary: Get session events tags: - Sessions parameters: - in: path name: session_id schema: type: string required: true responses: '200': description: Session events. Agent-backed sessions may stream events; legacy sessions return an event list. content: text/event-stream: schema: type: string application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string type: type: string payload: type: object additionalProperties: true seq: type: integer minimum: 0 created_at: type: string thread_id: type: - string - 'null' turn_id: type: - string - 'null' content: type: array items: type: object properties: type: type: string text: type: string required: - type required: - id - type additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - data additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/tables: get: operationId: listTables summary: List tables tags: - Tables parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 - in: query name: cursor schema: type: string responses: '200': description: List of tables. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string name: type: string template: type: - string - 'null' agent_id: type: - string - 'null' created_at: type: string required: - id - name additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - data additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createTable summary: Create a table tags: - Tables requestBody: content: application/json: schema: type: object properties: name: type: string template: type: - string - 'null' columns: type: array items: type: object properties: name: type: string original_name: type: string type: type: string enum: &ref_37 - text - integer - real - boolean - date - datetime - currency - json required: type: boolean unique: type: boolean default: anyOf: - type: string - type: number - type: boolean - type: 'null' sort_order: type: integer required: - name - type minItems: 1 required: - name - columns responses: '200': description: Table created. content: application/json: schema: type: object properties: id: type: string name: type: string template: type: - string - 'null' columns: type: array items: type: object properties: name: type: string original_name: type: string type: type: string enum: *ref_37 required: type: boolean unique: type: boolean default: anyOf: - type: string - type: number - type: boolean - type: 'null' sort_order: type: integer required: - name - type created_at: type: - string - 'null' required: - name - columns additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/tables/{table_id}: patch: operationId: updateTable summary: Update table metadata tags: - Tables parameters: - in: path name: table_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: name: type: string template: type: - string - 'null' columns: type: array items: type: object properties: name: type: string original_name: type: string type: type: string enum: *ref_37 required: type: boolean unique: type: boolean default: anyOf: - type: string - type: number - type: boolean - type: 'null' sort_order: type: integer required: - name - type responses: '200': description: Table updated. content: application/json: schema: type: object properties: id: type: string name: type: string template: type: - string - 'null' columns: type: array items: type: object properties: name: type: string original_name: type: string type: type: string enum: *ref_37 required: type: boolean unique: type: boolean default: anyOf: - type: string - type: number - type: boolean - type: 'null' sort_order: type: integer required: - name - type created_at: type: - string - 'null' required: - name - columns additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteTable summary: Delete a table tags: - Tables parameters: - in: path name: table_id schema: type: string required: true responses: '204': description: Table deleted. '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/tables/{table_id}/ingest: post: operationId: ingestTable summary: Ingest files into a table tags: - Tables parameters: - in: path name: table_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: inputs: type: array items: type: object properties: file_id: type: string required: - file_id minItems: 1 mode: type: string enum: - extract - chat steps: type: array items: {} required: - inputs responses: '202': description: Table ingest run started. content: application/json: schema: type: object properties: id: type: string run_id: type: string object: type: string const: run status: type: string workflow_name: type: string workflow_version: type: integer exclusiveMinimum: 0 workflow_label: type: string inputs: type: array items: type: object properties: file_id: type: string required: - file_id table_id: type: string agent_id: type: string events_url: type: string stream_url: type: string rows_url: type: string created_at: type: string required: - id - run_id - object - status - workflow_name - workflow_version - workflow_label - inputs - table_id - agent_id - events_url - stream_url - rows_url - created_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/host: get: operationId: listHostedPdfs summary: List hosted PDF deployments tags: - Host parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Hosted PDFs for the authenticated account. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: id: type: string object: type: string const: hosted_pdf namespace: type: string hostname: type: - string - 'null' document_id: type: string file_id: type: string title: type: string file_name: type: string mime: type: string const: application/pdf size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string access: type: object properties: mode: type: string enum: &ref_38 - public - unlisted - disabled expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri allow_download: type: boolean do_index: type: boolean password_required: type: boolean required: - mode - expires_at - expired_url - allow_download - do_index - password_required deployment: type: object properties: id: type: - string - 'null' name: type: string hostname: type: - string - 'null' url: type: string format: uri engine_id: type: string public_id: type: string output_id: type: - string - 'null' required: - id - name - hostname - url - engine_id - public_id - output_id published_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time urls: type: object properties: view: type: string format: uri pdf: type: string format: uri download: type: string format: uri embed: type: string format: uri manifest: type: string format: uri thumbnail: type: string format: uri page: type: string html: type: string format: uri text: type: string format: uri data: type: string format: uri required: - view - pdf - download - embed - manifest - thumbnail - page - html - text - data required: - id - object - namespace - hostname - document_id - file_id - title - file_name - mime - size - bytes - sha256 - access - deployment - published_at - created_at - updated_at - urls required: - object - data '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createHostedPdf summary: Publish a PDF file to a clean okrapdf.dev deployment hostname description: >- Publish an existing PDF from `/v1/files` or `/v1/documents` as `https://{namespace}.okrapdf.dev` and clean derived routes. Internal storage keys such as `original.pdf` are not exposed. tags: - Host requestBody: required: true content: application/json: schema: type: object properties: file_id: type: string namespace: type: string title: type: string replace: type: boolean access: type: object properties: mode: type: string enum: &ref_39 - public - unlisted - disabled expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri password: type: - string - 'null' maxLength: 2048 allow_download: type: boolean do_index: type: boolean required: - file_id responses: '200': description: Existing owned deployment updated. content: application/json: schema: type: object properties: id: type: string object: type: string const: hosted_pdf namespace: type: string hostname: type: - string - 'null' document_id: type: string file_id: type: string title: type: string file_name: type: string mime: type: string const: application/pdf size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string access: type: object properties: mode: type: string enum: *ref_38 expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri allow_download: type: boolean do_index: type: boolean password_required: type: boolean required: - mode - expires_at - expired_url - allow_download - do_index - password_required deployment: type: object properties: id: type: - string - 'null' name: type: string hostname: type: - string - 'null' url: type: string format: uri engine_id: type: string public_id: type: string output_id: type: - string - 'null' required: - id - name - hostname - url - engine_id - public_id - output_id published_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time urls: type: object properties: view: type: string format: uri pdf: type: string format: uri download: type: string format: uri embed: type: string format: uri manifest: type: string format: uri thumbnail: type: string format: uri page: type: string html: type: string format: uri text: type: string format: uri data: type: string format: uri required: - view - pdf - download - embed - manifest - thumbnail - page - html - text - data required: - id - object - namespace - hostname - document_id - file_id - title - file_name - mime - size - bytes - sha256 - access - deployment - published_at - created_at - updated_at - urls '201': description: Hosted PDF deployment created. content: application/json: schema: type: object properties: id: type: string object: type: string const: hosted_pdf namespace: type: string hostname: type: - string - 'null' document_id: type: string file_id: type: string title: type: string file_name: type: string mime: type: string const: application/pdf size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string access: type: object properties: mode: type: string enum: *ref_38 expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri allow_download: type: boolean do_index: type: boolean password_required: type: boolean required: - mode - expires_at - expired_url - allow_download - do_index - password_required deployment: type: object properties: id: type: - string - 'null' name: type: string hostname: type: - string - 'null' url: type: string format: uri engine_id: type: string public_id: type: string output_id: type: - string - 'null' required: - id - name - hostname - url - engine_id - public_id - output_id published_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time urls: type: object properties: view: type: string format: uri pdf: type: string format: uri download: type: string format: uri embed: type: string format: uri manifest: type: string format: uri thumbnail: type: string format: uri page: type: string html: type: string format: uri text: type: string format: uri data: type: string format: uri required: - view - pdf - download - embed - manifest - thumbnail - page - html - text - data required: - id - object - namespace - hostname - document_id - file_id - title - file_name - mime - size - bytes - sha256 - access - deployment - published_at - created_at - updated_at - urls '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/host/{namespace}: get: operationId: getHostedPdf summary: Retrieve a hosted PDF deployment tags: - Host parameters: - name: namespace in: path required: true schema: type: string responses: '200': description: Hosted PDF deployment. content: application/json: schema: type: object properties: id: type: string object: type: string const: hosted_pdf namespace: type: string hostname: type: - string - 'null' document_id: type: string file_id: type: string title: type: string file_name: type: string mime: type: string const: application/pdf size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string access: type: object properties: mode: type: string enum: *ref_38 expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri allow_download: type: boolean do_index: type: boolean password_required: type: boolean required: - mode - expires_at - expired_url - allow_download - do_index - password_required deployment: type: object properties: id: type: - string - 'null' name: type: string hostname: type: - string - 'null' url: type: string format: uri engine_id: type: string public_id: type: string output_id: type: - string - 'null' required: - id - name - hostname - url - engine_id - public_id - output_id published_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time urls: type: object properties: view: type: string format: uri pdf: type: string format: uri download: type: string format: uri embed: type: string format: uri manifest: type: string format: uri thumbnail: type: string format: uri page: type: string html: type: string format: uri text: type: string format: uri data: type: string format: uri required: - view - pdf - download - embed - manifest - thumbnail - page - html - text - data required: - id - object - namespace - hostname - document_id - file_id - title - file_name - mime - size - bytes - sha256 - access - deployment - published_at - created_at - updated_at - urls '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 patch: operationId: updateHostedPdf summary: Update a hosted PDF deployment description: >- Update the hosted PDF title, repoint an owned deployment hostname to another PDF with `replace: true`, or change access settings such as unlisted, disabled, expiry, password, download availability, and indexing. tags: - Host parameters: - name: namespace in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: file_id: type: string title: type: string replace: type: boolean access: type: object properties: mode: type: string enum: *ref_39 expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri password: type: - string - 'null' maxLength: 2048 allow_download: type: boolean do_index: type: boolean responses: '200': description: Hosted PDF deployment updated. content: application/json: schema: type: object properties: id: type: string object: type: string const: hosted_pdf namespace: type: string hostname: type: - string - 'null' document_id: type: string file_id: type: string title: type: string file_name: type: string mime: type: string const: application/pdf size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string access: type: object properties: mode: type: string enum: *ref_38 expires_at: type: - string - 'null' format: date-time expired_url: type: - string - 'null' format: uri allow_download: type: boolean do_index: type: boolean password_required: type: boolean required: - mode - expires_at - expired_url - allow_download - do_index - password_required deployment: type: object properties: id: type: - string - 'null' name: type: string hostname: type: - string - 'null' url: type: string format: uri engine_id: type: string public_id: type: string output_id: type: - string - 'null' required: - id - name - hostname - url - engine_id - public_id - output_id published_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time urls: type: object properties: view: type: string format: uri pdf: type: string format: uri download: type: string format: uri embed: type: string format: uri manifest: type: string format: uri thumbnail: type: string format: uri page: type: string html: type: string format: uri text: type: string format: uri data: type: string format: uri required: - view - pdf - download - embed - manifest - thumbnail - page - html - text - data required: - id - object - namespace - hostname - document_id - file_id - title - file_name - mime - size - bytes - sha256 - access - deployment - published_at - created_at - updated_at - urls '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/conversion/image2pdf: post: operationId: imageToPdfLegacy summary: Create a hosted PDF from an image description: >- Stores a PNG or JPEG from multipart upload or source URL as a private file asset, then publishes an immutable PDF derivative with preview and download URLs. Legacy alias of POST /v1/conversions/image-to-pdf. tags: &ref_46 - Conversions deprecated: true requestBody: required: true content: multipart/form-data: schema: type: object properties: paper_size: type: string enum: &ref_40 - letter - a4 - image orientation: type: string enum: &ref_41 - portrait - landscape - auto fit: type: string enum: &ref_42 - contain - cover pdf_file_name: type: string public_id: type: string file: {} application/json: schema: type: object properties: paper_size: type: string enum: *ref_40 orientation: type: string enum: *ref_41 fit: type: string enum: *ref_42 pdf_file_name: type: string public_id: type: string url: type: string format: uri file_name: type: string required: - url responses: '201': description: File asset and hosted PDF derivative created. content: application/json: schema: type: object properties: object: type: string const: conversion.image2pdf response: type: string format: uri file: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls pdf: type: object properties: object: type: string const: file_pdf_derivative source_file_id: type: string source_sha256: type: string pdf_sha256: type: string size: type: integer minimum: 0 page_count: type: integer exclusiveMinimum: 0 paper_size: type: string enum: *ref_43 orientation: type: string enum: *ref_44 fit: type: string enum: *ref_45 r2_key: type: string preview_r2_key: type: string manifest_r2_key: type: string urls: type: object properties: pdf: type: string format: uri download: type: string format: uri preview: type: string format: uri thumbnail: type: string format: uri manifest: type: string format: uri required: - pdf - download - preview - thumbnail - manifest required: - object - source_file_id - source_sha256 - pdf_sha256 - size - page_count - paper_size - orientation - fit - r2_key - preview_r2_key - manifest_r2_key - urls required: - object - response - file - pdf '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/conversions/image-to-pdf: post: operationId: imageToPdf summary: Create a hosted PDF from an image description: >- Stores a PNG or JPEG from multipart upload or source URL as a private file asset, then publishes an immutable PDF derivative with preview and download URLs. tags: *ref_46 requestBody: required: true content: multipart/form-data: schema: type: object properties: paper_size: type: string enum: *ref_40 orientation: type: string enum: *ref_41 fit: type: string enum: *ref_42 pdf_file_name: type: string public_id: type: string file: {} application/json: schema: type: object properties: paper_size: type: string enum: *ref_40 orientation: type: string enum: *ref_41 fit: type: string enum: *ref_42 pdf_file_name: type: string public_id: type: string url: type: string format: uri file_name: type: string required: - url responses: '201': description: File asset and hosted PDF derivative created. content: application/json: schema: type: object properties: object: type: string const: conversion.image2pdf response: type: string format: uri file: type: object properties: id: type: string file_id: type: string object: type: string const: file name: type: string mime: type: string size: type: integer minimum: 0 bytes: type: integer minimum: 0 sha256: type: string upload_mode: type: string enum: *ref_31 purpose: type: string enum: *ref_32 default: document kind: type: string enum: *ref_33 default: document created_at: type: string format: date-time updated_at: type: string format: date-time workflow_bound: anyOf: - type: boolean const: false - type: 'null' urls: type: object properties: bytes: type: string format: uri pdf: type: - string - 'null' format: uri document: type: - string - 'null' format: uri required: - bytes - pdf - document required: - id - file_id - object - name - mime - size - bytes - sha256 - upload_mode - purpose - kind - created_at - updated_at - workflow_bound - urls pdf: type: object properties: object: type: string const: file_pdf_derivative source_file_id: type: string source_sha256: type: string pdf_sha256: type: string size: type: integer minimum: 0 page_count: type: integer exclusiveMinimum: 0 paper_size: type: string enum: *ref_43 orientation: type: string enum: *ref_44 fit: type: string enum: *ref_45 r2_key: type: string preview_r2_key: type: string manifest_r2_key: type: string urls: type: object properties: pdf: type: string format: uri download: type: string format: uri preview: type: string format: uri thumbnail: type: string format: uri manifest: type: string format: uri required: - pdf - download - preview - thumbnail - manifest required: - object - source_file_id - source_sha256 - pdf_sha256 - size - page_count - paper_size - orientation - fit - r2_key - preview_r2_key - manifest_r2_key - urls required: - object - response - file - pdf '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents: get: operationId: listDocuments summary: List documents tags: - Documents parameters: - in: query name: limit description: Max results to return (default 20). schema: type: integer minimum: 1 maximum: 100 - in: query name: after description: 'Cursor: return results after this document ID.' schema: type: string - in: query name: before description: 'Cursor: return results before this document ID.' schema: type: string - in: query name: order description: Sort order by inserted_at. schema: type: string enum: - asc - desc responses: '200': description: Paginated list of documents. content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string status: type: string enum: - queued - extracting - completed - failed file_name: type: - string - 'null' total_pages: type: - integer - 'null' pages_completed: type: integer inserted_at: type: string format: date-time updated_at: type: string format: date-time thumbnail_url: type: string format: uri is_public: type: boolean source: type: string required: - id - status - file_name - total_pages - pages_completed - inserted_at - updated_at - is_public has_more: type: boolean required: - data - has_more '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: uploadDocument summary: Upload a document tags: - Documents parameters: - in: query name: page_images description: >- Page image rendering strategy. 'none' = no rendering; 'cover' = page 1 only; 'eager' = ALL pages rendered at upload (default). 'lazy' is a deprecated alias for 'eager'. schema: type: string enum: - none - cover - eager - lazy - in: query name: processor description: >- OCR processor/vendor override. Defaults to gemini-vision for Gemini Flash VLM parsing when capabilities is omitted. Shorthand for capabilities.phases.ocr.vendor. schema: type: string - in: query name: strategy description: Legacy shorthand for vendor_options.strategy. schema: type: string - in: query name: intent description: Free-text parsing goal used to publish an upload-time parse plan on the DocumentAgent state. schema: type: string requestBody: description: PDF file upload as multipart/form-data, with optional initial document config. content: multipart/form-data: schema: type: object properties: file: {} org_id: type: string project_id: type: string config: type: string capabilities: type: string processor: type: string vendor_options: type: string intent: type: string responses: '202': description: Document accepted for processing. content: application/json: schema: type: object properties: documentId: type: string r2Key: type: string rootNodeId: type: string phase: type: string status: type: string enum: - queued - processing - complete - error workflowId: type: - string - 'null' parsePlan: type: object properties: object: type: string const: document_parse_plan version: type: string const: okra.parse_plan.v1 intent: type: object properties: raw: type: - string - 'null' kind: type: string summary: type: string required: - raw - kind - summary workflow: type: object properties: engine: type: string const: DOC_LIFECYCLE_WORKFLOW runner: type: string const: AgentWorkflow resumable: type: boolean const: true trigger: type: string required: - engine - runner - resumable - trigger strategy: type: object properties: processor: type: - string - 'null' pageImages: type: string enum: - none - cover - eager cache: type: string enum: - disabled - prefer runParse: type: boolean runRender: type: boolean skipParse: type: boolean required: - processor - pageImages - cache - runParse - runRender - skipParse steps: type: array items: type: object properties: id: type: string title: type: string detail: type: string phase: type: string resumable: type: boolean status: type: string const: planned required: - id - title - detail - phase - resumable - status toolPolicy: type: object properties: free: type: array items: type: string requiresGrant: type: array items: type: string required: - free - requiresGrant createdAt: type: string required: - object - version - intent - workflow - strategy - steps - toolPolicy - createdAt required: - documentId - phase '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}: get: operationId: getDocument summary: Get document status tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Document status object. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteDocument summary: Delete a document tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Document deleted. content: application/json: schema: type: object properties: deleted: type: boolean id: type: string required: - deleted - id '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/pages/{page_number}: get: operationId: getDocumentPage summary: Get page content tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: page_number description: 1-based page number. schema: type: integer minimum: 1 required: true responses: '200': description: Page content in markdown. content: application/json: schema: type: object properties: page: type: integer content: type: string required: - page - content '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/pages/{page_number}/markdown: get: operationId: getDocumentPageMarkdown summary: Get page as markdown tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: page_number description: 1-based page number. schema: type: integer minimum: 1 required: true responses: '200': description: Raw markdown text for the page. content: text/markdown: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/pages/{page_number}/image.png: get: operationId: getDocumentPageImage summary: Get page image tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: page_number description: 1-based page number. schema: type: integer minimum: 1 required: true responses: '200': description: PNG image of the page. content: image/png: schema: type: string format: binary '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/full.md: get: operationId: getDocumentFullMarkdown summary: Get full document as markdown tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Full document markdown. content: text/markdown: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/full.json: get: operationId: getDocumentFullJson summary: Get full document as JSON tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Full document content as JSON. content: application/json: schema: type: object properties: content: type: string required: - content '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/node/{node_id}/vendor-debug: get: operationId: getDocumentNodeVendorDebug summary: Get raw vendor/provider debug payload for a node description: >- Returns the normalized node row together with page ledger context, vendor lineage metadata, and the raw vendor payload excerpt used to produce it. tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: node_id description: Document node ID (`node_doc-...`). schema: type: string required: true responses: '200': description: Vendor debug payload for the requested node. content: application/json: schema: type: object properties: nodeId: type: string found: type: boolean vendor: type: - string - 'null' normalized: type: object additionalProperties: true ledger: type: - object - 'null' additionalProperties: true vendorLog: type: - object - 'null' additionalProperties: true raw: anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: {} - type: object additionalProperties: true required: - nodeId - found - vendor - normalized - ledger - vendorLog - raw '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/entities/tables: get: operationId: listDocumentTables summary: List tables in a document tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: query name: limit schema: type: integer - in: query name: offset schema: type: integer responses: '200': description: List of table nodes. content: application/json: schema: type: object properties: nodes: type: array items: type: object properties: type: type: string enum: &ref_47 - table - figure value: type: - string - 'null' required: - type - value required: - nodes '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/entities/tables/{index}: get: operationId: getDocumentTable summary: Get a specific table tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: index schema: type: string required: true - in: query name: format schema: type: string enum: - json - csv - html - markdown responses: '200': description: Table in requested format. content: application/json: schema: type: object additionalProperties: true text/csv: schema: type: string text/html: schema: type: string text/markdown: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/entities/figures: get: operationId: listDocumentFigures summary: List figures in a document tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: query name: limit schema: type: integer - in: query name: offset schema: type: integer responses: '200': description: List of figure nodes. content: application/json: schema: type: object properties: nodes: type: array items: type: object properties: type: type: string enum: *ref_47 value: type: - string - 'null' required: - type - value required: - nodes '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/entities/figures/{index}: get: operationId: getDocumentFigure summary: Get a specific figure tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: index schema: type: string required: true responses: '200': description: Figure node. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/redact: post: operationId: redactDocument summary: Redact regions of a document page description: >- Composites opaque black overlays onto the page image at the requested regions using the Cloudflare Images binding and returns the redacted image bytes inline. The output is not stored. Access is governed by the underlying page-image route (`/v1/documents/{id}/pg_{n}.png`): this operation carries no auth of its own and cannot reveal more than that route already exposes to the caller. tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: required: true content: application/json: schema: type: object properties: page: type: integer minimum: 1 regions: type: array items: type: object properties: x: type: number minimum: 0 'y': type: number minimum: 0 w: type: number exclusiveMinimum: 0 h: type: number exclusiveMinimum: 0 required: - x - 'y' - w - h minItems: 1 maxItems: 100 format: type: string enum: - image/avif - image/webp - image/png - image/jpeg required: - page - regions responses: '200': description: Composited redacted page image bytes in the requested format (defaults to AVIF). content: image/avif: schema: type: string format: binary image/webp: schema: type: string format: binary image/png: schema: type: string format: binary image/jpeg: schema: type: string format: binary '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/reparse: post: operationId: reparseDocument summary: Reparse a document description: >- Owner document command that restarts the document lifecycle workflow and returns the workflow id. For stateless CLI/agent execution, prefer `POST /v1/jobs` with `type: "document.parse"`; this path exists as the document-scoped owner recovery command. tags: - Documents security: - BearerApiKey: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: query name: strategy description: Parser strategy/vendor alias, for example `gemini-vision` or `textlayer`. schema: type: string responses: '200': description: Reparse workflow started. content: application/json: schema: type: object properties: message: type: string phase: type: string workflowId: type: string strategy: type: string pages_parsed: type: integer minimum: 0 page_count: type: integer minimum: 0 page_coverage: type: string enum: - unknown - empty - partial - complete page_coverage_percent: type: integer minimum: 0 maximum: 100 required: - message - phase - workflowId - strategy additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/structured-output: post: operationId: structuredOutput summary: Extract structured data from a document tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: query: type: string prompt: type: string schema: type: object additionalProperties: {} timeoutMs: type: integer minimum: 1 maximum: 120000 required: - schema responses: '200': description: Extracted structured data. content: application/json: schema: type: object properties: data: {} meta: type: object properties: confidence: type: number model: type: string durationMs: type: integer citations: type: array items: type: object properties: page: type: integer text: type: string required: - page - text cached: type: boolean required: - meta '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/chat/completions: post: operationId: chatCompletions summary: Chat with a document (OpenAI-compatible) tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: messages: type: array items: type: object properties: role: type: string enum: &ref_48 - system - user - assistant content: type: string required: - role - content minItems: 1 stream: type: boolean model: type: string temperature: type: number minimum: 0 maximum: 2 max_tokens: type: integer exclusiveMinimum: 0 required: - messages responses: '200': description: Chat completion response (or SSE stream if stream=true). content: application/json: schema: type: object properties: id: type: string object: type: string const: chat.completion choices: type: array items: type: object properties: index: type: integer message: type: object properties: role: type: string enum: *ref_48 content: type: string required: - role - content finish_reason: type: - string - 'null' required: - index - message - finish_reason usage: type: object properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer required: - prompt_tokens - completion_tokens - total_tokens required: - id - object - choices text/event-stream: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/resolve/chat/completions: post: operationId: resolveChatCompletions summary: Resolve source and chat with document tags: - Documents requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url - type: object properties: type: type: string const: public_source id: type: string required: - type - id wait_ms: type: integer minimum: 0 maximum: 120000 messages: type: array items: type: object properties: role: type: string enum: &ref_49 - system - user - assistant content: type: string required: - role - content minItems: 1 stream: type: boolean model: type: string temperature: type: number minimum: 0 maximum: 2 max_tokens: type: integer exclusiveMinimum: 0 required: - source - messages responses: '200': description: OpenAI-compatible chat completion response. content: application/json: schema: type: object properties: id: type: string object: type: string const: chat.completion choices: type: array items: type: object properties: index: type: integer message: type: object properties: role: type: string enum: *ref_49 content: type: string required: - role - content finish_reason: type: - string - 'null' required: - index - message - finish_reason usage: type: object properties: prompt_tokens: type: integer completion_tokens: type: integer total_tokens: type: integer required: - prompt_tokens - completion_tokens - total_tokens required: - id - object - choices text/event-stream: schema: type: string '202': description: Document is still ingesting; retry after status indicates completion. content: application/json: schema: type: object properties: run_id: type: string document_id: type: string status_url: type: string retry_after: type: integer phase: type: - string - 'null' required: - run_id - document_id - status_url - retry_after '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/resolve/ai-stream: post: operationId: resolveAiStream summary: Resolve source and stream document completion tags: - Documents requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url - type: object properties: type: type: string const: public_source id: type: string required: - type - id wait_ms: type: integer minimum: 0 maximum: 120000 required: - source additionalProperties: true responses: '200': description: AI stream response from the document endpoint. content: text/event-stream: schema: type: string application/json: schema: type: object additionalProperties: true '202': description: Document is still ingesting; retry after status indicates completion. content: application/json: schema: type: object properties: run_id: type: string document_id: type: string status_url: type: string retry_after: type: integer phase: type: - string - 'null' required: - run_id - document_id - status_url - retry_after '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/config: get: operationId: getDocumentConfig summary: Get document spec tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Current document spec revision. content: application/json: schema: type: object properties: document_id: type: string spec_version: type: integer exclusiveMinimum: 0 spec: type: object properties: version: type: number const: 1 default: 1 access: type: object properties: default_effect: type: string const: deny grants: type: array items: type: object properties: grant_id: type: string principal: oneOf: - type: object properties: type: type: string const: owner required: - type - type: object properties: type: type: string const: public required: - type - type: object properties: type: type: string const: user id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: org id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: project id: type: string minLength: 1 required: - type - id actions: type: array items: type: string enum: &ref_50 - admin - read_meta - read_content - query - download_pdf - update_config - trigger_extract - create_link - list_links - publish minItems: 1 constraints: type: object properties: redaction_role: type: string enum: &ref_51 - admin - viewer - public expires_at: type: string format: date-time not_before: type: string format: date-time output_allowlist: type: array items: type: string minLength: 1 required: - principal - actions redaction_roles: type: object properties: viewer: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true public: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true required: - default_effect - grants extract: type: object properties: page_image_strategy: type: string enum: &ref_52 - none - cover - eager default: eager provider: type: - string - 'null' default: null provider_options: type: object additionalProperties: {} required: - page_image_strategy - provider default: &ref_53 page_image_strategy: eager provider: null features: type: object properties: vlm_qwen: type: boolean default: false structural_check: type: boolean default: false sandbox_verify: type: boolean default: false search: type: boolean default: false required: - vlm_qwen - structural_check - sandbox_verify - search default: &ref_54 vlm_qwen: false structural_check: false sandbox_verify: false search: true runtime: type: object properties: self_heal: type: boolean default: true workflow_watchdog_timeout_ms: type: integer minimum: 60000 maximum: 3600000 default: 600000 max_auto_reparse: type: integer minimum: 0 maximum: 5 default: 2 required: - self_heal - workflow_watchdog_timeout_ms - max_auto_reparse default: &ref_55 self_heal: true workflow_watchdog_timeout_ms: 600000 max_auto_reparse: 2 agent: type: object properties: agent_id: type: string default: okra/default instructions: type: string minLength: 1 model: type: object properties: chat: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 query: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 tools: type: object properties: builtinAllowlist: type: array items: type: string enum: *ref_24 builtinToolPolicies: type: object properties: get_job_metadata: type: string enum: *ref_21 get_live_status: type: string enum: *ref_21 query_sql: type: string enum: *ref_21 query_document: type: string enum: *ref_21 view_page_region: type: string enum: *ref_21 completionToolMode: type: string enum: *ref_25 allowUserTools: type: boolean userToolPolicy: type: string enum: *ref_21 context: type: object properties: mode: type: string enum: *ref_26 security: type: object properties: redactionRole: type: string enum: *ref_27 sqlReadOnly: type: boolean allowReparseTool: type: boolean runtime: type: object properties: maxToolRounds: type: integer minimum: 0 maximum: 50 cacheDefault: type: boolean stream: type: boolean eval: type: object properties: enabled: type: boolean default: false scope: type: string enum: *ref_28 default: document instructions: type: string minLength: 1 model: type: object properties: provider: type: string enum: *ref_29 model: type: string minLength: 1 required: - provider - model additionalProperties: false maxRecentTurns: type: integer minimum: 0 maximum: 20 default: 5 required: - enabled - scope - maxRecentTurns additionalProperties: false required: - agent_id default: &ref_56 {} plugins: type: array items: type: object properties: name: type: string minLength: 1 provider: type: string minLength: 1 model: type: string minLength: 1 providerOptions: type: object additionalProperties: {} required: - name default: &ref_57 [] required: - version - access - extract - features - runtime - agent - plugins required: - document_id - spec_version - spec '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 put: operationId: putDocumentConfig summary: Replace document spec tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: description: Full replacement of the persisted document spec. content: application/json: schema: type: object properties: version: type: number const: 1 default: 1 access: type: object properties: default_effect: type: string const: deny grants: type: array items: type: object properties: grant_id: type: string principal: oneOf: - type: object properties: type: type: string const: owner required: - type - type: object properties: type: type: string const: public required: - type - type: object properties: type: type: string const: user id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: org id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: project id: type: string minLength: 1 required: - type - id actions: type: array items: type: string enum: *ref_50 minItems: 1 constraints: type: object properties: redaction_role: type: string enum: *ref_51 expires_at: type: string format: date-time not_before: type: string format: date-time output_allowlist: type: array items: type: string minLength: 1 required: - principal - actions redaction_roles: type: object properties: viewer: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true public: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true required: - default_effect - grants extract: type: object properties: page_image_strategy: type: string enum: *ref_52 default: eager provider: type: - string - 'null' default: null provider_options: type: object additionalProperties: {} default: *ref_53 features: type: object properties: vlm_qwen: type: boolean default: false structural_check: type: boolean default: false sandbox_verify: type: boolean default: false search: type: boolean default: false default: *ref_54 runtime: type: object properties: self_heal: type: boolean default: true workflow_watchdog_timeout_ms: type: integer minimum: 60000 maximum: 3600000 default: 600000 max_auto_reparse: type: integer minimum: 0 maximum: 5 default: 2 default: *ref_55 agent: type: object properties: agent_id: type: string default: okra/default instructions: type: string minLength: 1 model: type: object properties: chat: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 query: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 tools: type: object properties: builtinAllowlist: type: array items: type: string enum: *ref_24 builtinToolPolicies: type: object properties: get_job_metadata: type: string enum: *ref_21 get_live_status: type: string enum: *ref_21 query_sql: type: string enum: *ref_21 query_document: type: string enum: *ref_21 view_page_region: type: string enum: *ref_21 completionToolMode: type: string enum: *ref_25 allowUserTools: type: boolean userToolPolicy: type: string enum: *ref_21 context: type: object properties: mode: type: string enum: *ref_26 security: type: object properties: redactionRole: type: string enum: *ref_27 sqlReadOnly: type: boolean allowReparseTool: type: boolean runtime: type: object properties: maxToolRounds: type: integer minimum: 0 maximum: 50 cacheDefault: type: boolean stream: type: boolean eval: type: object properties: enabled: type: boolean default: false scope: type: string enum: *ref_28 default: document instructions: type: string minLength: 1 model: type: object properties: provider: type: string enum: *ref_29 model: type: string minLength: 1 required: - provider - model additionalProperties: false maxRecentTurns: type: integer minimum: 0 maximum: 20 default: 5 additionalProperties: false default: *ref_56 plugins: type: array items: type: object properties: name: type: string minLength: 1 provider: type: string minLength: 1 model: type: string minLength: 1 providerOptions: type: object additionalProperties: {} required: - name default: *ref_57 required: - access responses: '200': description: Stored document spec revision. content: application/json: schema: type: object properties: document_id: type: string spec_version: type: integer exclusiveMinimum: 0 spec: type: object properties: version: type: number const: 1 default: 1 access: type: object properties: default_effect: type: string const: deny grants: type: array items: type: object properties: grant_id: type: string principal: oneOf: - type: object properties: type: type: string const: owner required: - type - type: object properties: type: type: string const: public required: - type - type: object properties: type: type: string const: user id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: org id: type: string minLength: 1 required: - type - id - type: object properties: type: type: string const: project id: type: string minLength: 1 required: - type - id actions: type: array items: type: string enum: *ref_50 minItems: 1 constraints: type: object properties: redaction_role: type: string enum: *ref_51 expires_at: type: string format: date-time not_before: type: string format: date-time output_allowlist: type: array items: type: string minLength: 1 required: - principal - actions redaction_roles: type: object properties: viewer: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true public: type: object properties: pii: type: object additionalProperties: {} additionalProperties: true required: - default_effect - grants extract: type: object properties: page_image_strategy: type: string enum: *ref_52 default: eager provider: type: - string - 'null' default: null provider_options: type: object additionalProperties: {} required: - page_image_strategy - provider default: *ref_53 features: type: object properties: vlm_qwen: type: boolean default: false structural_check: type: boolean default: false sandbox_verify: type: boolean default: false search: type: boolean default: false required: - vlm_qwen - structural_check - sandbox_verify - search default: *ref_54 runtime: type: object properties: self_heal: type: boolean default: true workflow_watchdog_timeout_ms: type: integer minimum: 60000 maximum: 3600000 default: 600000 max_auto_reparse: type: integer minimum: 0 maximum: 5 default: 2 required: - self_heal - workflow_watchdog_timeout_ms - max_auto_reparse default: *ref_55 agent: type: object properties: agent_id: type: string default: okra/default instructions: type: string minLength: 1 model: type: object properties: chat: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 query: type: object properties: provider: type: string enum: *ref_20 model: type: string minLength: 1 tools: type: object properties: builtinAllowlist: type: array items: type: string enum: *ref_24 builtinToolPolicies: type: object properties: get_job_metadata: type: string enum: *ref_21 get_live_status: type: string enum: *ref_21 query_sql: type: string enum: *ref_21 query_document: type: string enum: *ref_21 view_page_region: type: string enum: *ref_21 completionToolMode: type: string enum: *ref_25 allowUserTools: type: boolean userToolPolicy: type: string enum: *ref_21 context: type: object properties: mode: type: string enum: *ref_26 security: type: object properties: redactionRole: type: string enum: *ref_27 sqlReadOnly: type: boolean allowReparseTool: type: boolean runtime: type: object properties: maxToolRounds: type: integer minimum: 0 maximum: 50 cacheDefault: type: boolean stream: type: boolean eval: type: object properties: enabled: type: boolean default: false scope: type: string enum: *ref_28 default: document instructions: type: string minLength: 1 model: type: object properties: provider: type: string enum: *ref_29 model: type: string minLength: 1 required: - provider - model additionalProperties: false maxRecentTurns: type: integer minimum: 0 maximum: 20 default: 5 required: - enabled - scope - maxRecentTurns additionalProperties: false required: - agent_id default: *ref_56 plugins: type: array items: type: object properties: name: type: string minLength: 1 provider: type: string minLength: 1 model: type: string minLength: 1 providerOptions: type: object additionalProperties: {} required: - name default: *ref_57 required: - version - access - extract - features - runtime - agent - plugins required: - document_id - spec_version - spec '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/links: get: operationId: listDocumentLinks summary: List document capability links tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true responses: '200': description: Issued link metadata. Raw token material is never returned from this endpoint. content: application/json: schema: type: object properties: document_id: type: string links: type: array items: type: object properties: link_id: type: string token_hint: type: string actions: type: array items: type: string enum: &ref_58 - read_content - download_pdf - query minItems: 1 constraints: type: - object - 'null' properties: redaction_role: type: string enum: &ref_59 - admin - viewer - public expires_in_seconds: type: integer minimum: 1 maximum: 31536000 expires_at: type: string format: date-time max_views: type: integer minimum: 1 password_mode: type: string enum: &ref_60 - none - generated - required ip_lock: type: boolean created_at: type: string format: date-time revoked_at: type: - string - 'null' format: date-time last_viewed_at: type: - string - 'null' format: date-time required: - link_id - token_hint - actions - created_at required: - document_id - links '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createDocumentLink summary: Create a document capability link tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: description: Create a constrained capability link for document access. content: application/json: schema: type: object properties: actions: type: array items: type: string enum: *ref_58 minItems: 1 constraints: type: object properties: redaction_role: type: string enum: *ref_59 expires_in_seconds: type: integer minimum: 1 maximum: 31536000 expires_at: type: string format: date-time max_views: type: integer minimum: 1 password_mode: type: string enum: *ref_60 ip_lock: type: boolean required: - actions responses: '201': description: Capability link created. Raw token material is returned only once. content: application/json: schema: type: object properties: document_id: type: string link_id: type: string token: type: string token_hint: type: string actions: type: array items: type: string enum: *ref_58 minItems: 1 constraints: type: - object - 'null' properties: redaction_role: type: string enum: *ref_59 expires_in_seconds: type: integer minimum: 1 maximum: 31536000 expires_at: type: string format: date-time max_views: type: integer minimum: 1 password_mode: type: string enum: *ref_60 ip_lock: type: boolean urls: type: object properties: markdown: type: - string - 'null' format: uri pdf: type: - string - 'null' format: uri completion: type: - string - 'null' format: uri required: - markdown - pdf - completion created_at: type: string format: date-time revoked_at: type: - string - 'null' format: date-time last_viewed_at: type: - string - 'null' format: date-time required: - document_id - link_id - token - token_hint - actions - urls - created_at - revoked_at - last_viewed_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/links/{link_id}: delete: operationId: deleteDocumentLink summary: Revoke a document capability link tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: path name: link_id description: Issued capability link identifier. schema: type: string required: true responses: '200': description: Capability link revoked. content: application/json: schema: type: object properties: document_id: type: string link_id: type: string revoked: type: boolean const: true required: - document_id - link_id - revoked '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/original.pdf: get: operationId: getDocumentPdf summary: Download original PDF tags: - Documents security: [] parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true - in: query name: token description: Short-lived token returned by POST /v1/documents/{id}/original.pdf/token. schema: type: string responses: '200': description: Original PDF binary. content: application/pdf: schema: type: string format: binary '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/original.pdf/token: post: operationId: createOriginalPdfToken summary: Create a signed original PDF URL tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: ttlSeconds: type: integer exclusiveMinimum: 0 maximum: 3600 ttl_seconds: type: integer exclusiveMinimum: 0 maximum: 3600 responses: '200': description: Short-lived URL for opening the original PDF in a browser. content: application/json: schema: type: object properties: token: type: string url: type: string format: uri documentId: type: string expires_in: type: integer exclusiveMinimum: 0 expires_at: type: string format: date-time required: - token - url - documentId - expires_in - expires_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/documents/{id}/clone: post: operationId: cloneDocument summary: Clone a document (not yet implemented) tags: - Documents parameters: - in: path name: id description: Document ID (`doc-abc123`) or 6-char short hash. schema: type: string required: true requestBody: content: application/json: schema: type: object responses: '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '501': description: Not implemented. content: application/json: schema: type: object properties: error: type: string '504': *ref_10 /v1/documents/ingest: post: operationId: ingestDocument summary: Ingest raw vendor output into a document tags: - Documents requestBody: content: application/json: schema: type: object properties: document_id: type: string vendor: type: string payload: {} pdf_sha256: type: string capabilities: type: object properties: vlm_qwen: type: boolean structural_check: type: boolean sandbox_verify: type: boolean search: type: boolean phases: type: object additionalProperties: type: object properties: vendor: type: string tier: type: string enum: - fast - standard - premium enabled: type: boolean middleware: type: array items: type: object properties: name: type: string required: - name required: - document_id responses: '200': description: Ingested successfully. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/resolve/{hash}: get: operationId: resolveHash summary: Resolve a short hash to a document ID tags: - Documents security: [] parameters: - in: path name: hash description: 6-character hex short hash. schema: type: string pattern: ^[a-f0-9]{6}$ required: true responses: '200': description: Resolved document reference. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/public/sources/{id}: get: operationId: getPublicSource summary: Get curated public source status tags: - Public Sources parameters: - name: id in: path required: true schema: type: string responses: '200': description: Public source metadata. content: application/json: schema: type: object properties: id: type: string source_type: type: string enum: &ref_61 - url - filing provider: type: string enum: &ref_62 - arxiv - hkex - generic_url normalized_url: type: - string - 'null' source_hash: type: string document_id: type: - string - 'null' canonical_path: type: string canonical_url: type: string status: type: string enum: &ref_63 - pending - processing - ready - failed enabled: type: boolean metadata: type: - object - 'null' additionalProperties: {} status_url: type: string document_url: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - source_type - provider - normalized_url - source_hash - document_id - canonical_path - canonical_url - status - enabled - metadata - created_at - updated_at /v1/public/resolve: post: operationId: resolvePublicSource summary: Resolve a curated public source tags: - Public Sources requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url - type: object properties: type: type: string const: public_source id: type: string required: - type - id required: - source responses: '200': description: Curated public source metadata. content: application/json: schema: type: object properties: id: type: string source_type: type: string enum: *ref_61 provider: type: string enum: *ref_62 normalized_url: type: - string - 'null' source_hash: type: string document_id: type: - string - 'null' canonical_path: type: string canonical_url: type: string status: type: string enum: *ref_63 enabled: type: boolean metadata: type: - object - 'null' additionalProperties: {} status_url: type: string document_url: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - source_type - provider - normalized_url - source_hash - document_id - canonical_path - canonical_url - status - enabled - metadata - created_at - updated_at '202': description: Public source exists but is still indexing. content: application/json: schema: type: object properties: source_id: type: string document_id: type: - string - 'null' status: type: string enum: &ref_64 - pending - processing - failed phase: type: - string - 'null' status_url: type: string retry_after: type: integer canonical_path: type: string canonical_url: type: string required: - source_id - document_id - status - phase - status_url - retry_after - canonical_path - canonical_url /v1/public/resolve/chat/completions: post: operationId: resolvePublicSourceChatCompletions summary: Chat with a curated public source tags: - Public Sources requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url - type: object properties: type: type: string const: public_source id: type: string required: - type - id wait_ms: type: integer messages: type: array items: type: object properties: role: type: string enum: - system - user - assistant content: type: string required: - role - content required: - source - messages additionalProperties: true responses: '200': description: OpenAI-compatible completion response. content: application/json: schema: type: object additionalProperties: true '202': description: Public source exists but is still indexing. content: application/json: schema: type: object properties: source_id: type: string document_id: type: - string - 'null' status: type: string enum: *ref_64 phase: type: - string - 'null' status_url: type: string retry_after: type: integer canonical_path: type: string canonical_url: type: string required: - source_id - document_id - status - phase - status_url - retry_after - canonical_path - canonical_url /v1/public/resolve/ai-stream: post: operationId: resolvePublicSourceAiStream summary: Stream chat against a curated public source tags: - Public Sources requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url - type: object properties: type: type: string const: public_source id: type: string required: - type - id required: - source additionalProperties: true responses: '200': description: Stream response from the underlying document endpoint. content: text/event-stream: schema: type: string application/json: schema: type: object additionalProperties: true '202': description: Public source exists but is still indexing. content: application/json: schema: type: object properties: source_id: type: string document_id: type: - string - 'null' status: type: string enum: *ref_64 phase: type: - string - 'null' status_url: type: string retry_after: type: integer canonical_path: type: string canonical_url: type: string required: - source_id - document_id - status - phase - status_url - retry_after - canonical_path - canonical_url /v1/public/index-requests: post: operationId: createPublicIndexRequest summary: Request public indexing for a curated source tags: - Public Sources security: - BearerApiKey: [] requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url required: - source additionalProperties: true responses: '200': description: Source already exists or request already open. content: application/json: schema: type: object properties: request: type: object properties: id: type: string requested_source_type: type: string enum: &ref_65 - url - filing requested_url: type: - string - 'null' requested_exchange: type: - string - 'null' requested_ticker: type: - string - 'null' requested_slug: type: - string - 'null' normalized_url: type: - string - 'null' source_hash: type: string requester_user_id: type: string requester_org_id: type: - string - 'null' status: type: string enum: &ref_66 - pending - approved - rejected - indexed - duplicate public_source_id: type: - string - 'null' admin_note: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - requested_source_type - requested_url - requested_exchange - requested_ticker - requested_slug - normalized_url - source_hash - requester_user_id - requester_org_id - status - public_source_id - admin_note - created_at - updated_at public_source: type: object properties: id: type: string source_type: type: string enum: *ref_61 provider: type: string enum: *ref_62 normalized_url: type: - string - 'null' source_hash: type: string document_id: type: - string - 'null' canonical_path: type: string canonical_url: type: string status: type: string enum: *ref_63 enabled: type: boolean metadata: type: - object - 'null' additionalProperties: {} status_url: type: string document_url: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - source_type - provider - normalized_url - source_hash - document_id - canonical_path - canonical_url - status - enabled - metadata - created_at - updated_at already_indexed: type: boolean already_requested: type: boolean suggested_source_id: type: - string - 'null' '201': description: Index request created. content: application/json: schema: type: object properties: request: type: object properties: id: type: string requested_source_type: type: string enum: *ref_65 requested_url: type: - string - 'null' requested_exchange: type: - string - 'null' requested_ticker: type: - string - 'null' requested_slug: type: - string - 'null' normalized_url: type: - string - 'null' source_hash: type: string requester_user_id: type: string requester_org_id: type: - string - 'null' status: type: string enum: *ref_66 public_source_id: type: - string - 'null' admin_note: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - requested_source_type - requested_url - requested_exchange - requested_ticker - requested_slug - normalized_url - source_hash - requester_user_id - requester_org_id - status - public_source_id - admin_note - created_at - updated_at suggested_source_id: type: - string - 'null' required: - request - suggested_source_id /v1/public/index-requests/{id}: get: operationId: getPublicIndexRequest summary: Get an authenticated public index request tags: - Public Sources security: - BearerApiKey: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Index request metadata. content: application/json: schema: type: object properties: request: type: object properties: id: type: string requested_source_type: type: string enum: *ref_65 requested_url: type: - string - 'null' requested_exchange: type: - string - 'null' requested_ticker: type: - string - 'null' requested_slug: type: - string - 'null' normalized_url: type: - string - 'null' source_hash: type: string requester_user_id: type: string requester_org_id: type: - string - 'null' status: type: string enum: *ref_66 public_source_id: type: - string - 'null' admin_note: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - requested_source_type - requested_url - requested_exchange - requested_ticker - requested_slug - normalized_url - source_hash - requester_user_id - requester_org_id - status - public_source_id - admin_note - created_at - updated_at required: - request /v1/admin/public-sources: post: operationId: createAdminPublicSource summary: Create or curate a public source tags: - Public Sources security: - SharedSecret: [] requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url status: type: string enum: - pending - processing - ready - failed enabled: type: boolean canonical_path: type: string document_id: type: string metadata: type: object additionalProperties: {} required: - source additionalProperties: true responses: '201': description: Public source created. content: application/json: schema: type: object properties: public_source: type: object properties: id: type: string source_type: type: string enum: *ref_61 provider: type: string enum: *ref_62 normalized_url: type: - string - 'null' source_hash: type: string document_id: type: - string - 'null' canonical_path: type: string canonical_url: type: string status: type: string enum: *ref_63 enabled: type: boolean metadata: type: - object - 'null' additionalProperties: {} status_url: type: string document_url: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - source_type - provider - normalized_url - source_hash - document_id - canonical_path - canonical_url - status - enabled - metadata - created_at - updated_at required: - public_source /v1/admin/public-sources/{id}: patch: operationId: updateAdminPublicSource summary: Patch curated public source metadata tags: - Public Sources security: - SharedSecret: [] parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: status: type: string enum: - pending - processing - ready - failed enabled: type: boolean canonical_path: type: string document_id: type: string metadata: type: - object - 'null' additionalProperties: {} additionalProperties: true responses: '200': description: Public source updated. content: application/json: schema: type: object properties: public_source: type: object properties: id: type: string source_type: type: string enum: *ref_61 provider: type: string enum: *ref_62 normalized_url: type: - string - 'null' source_hash: type: string document_id: type: - string - 'null' canonical_path: type: string canonical_url: type: string status: type: string enum: *ref_63 enabled: type: boolean metadata: type: - object - 'null' additionalProperties: {} status_url: type: string document_url: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - source_type - provider - normalized_url - source_hash - document_id - canonical_path - canonical_url - status - enabled - metadata - created_at - updated_at required: - public_source /v1/admin/public-sources/index: post: operationId: indexAdminPublicSource summary: Approve and index a curated public source tags: - Public Sources security: - SharedSecret: [] requestBody: content: application/json: schema: type: object properties: source: oneOf: - type: object properties: type: type: string const: filing exchange: type: string ticker: type: string slug: type: string required: - type - exchange - ticker - slug - type: object properties: type: type: string const: url url: type: string format: uri required: - type - url request_id: type: string public_source_id: type: string wait_ms: type: integer additionalProperties: true responses: '200': description: Public source indexed. content: application/json: schema: type: object additionalProperties: true '202': description: Public source indexing is still in progress. content: application/json: schema: type: object properties: source_id: type: string document_id: type: - string - 'null' status: type: string enum: *ref_64 phase: type: - string - 'null' status_url: type: string retry_after: type: integer canonical_path: type: string canonical_url: type: string required: - source_id - document_id - status - phase - status_url - retry_after - canonical_path - canonical_url /v1/admin/index-requests/{id}/approve: post: operationId: approvePublicIndexRequest summary: Approve an index request tags: - Public Sources security: - SharedSecret: [] parameters: - name: id in: path required: true schema: type: string responses: '200': description: Index request approved. content: application/json: schema: type: object properties: request: type: object properties: id: type: string requested_source_type: type: string enum: *ref_65 requested_url: type: - string - 'null' requested_exchange: type: - string - 'null' requested_ticker: type: - string - 'null' requested_slug: type: - string - 'null' normalized_url: type: - string - 'null' source_hash: type: string requester_user_id: type: string requester_org_id: type: - string - 'null' status: type: string enum: *ref_66 public_source_id: type: - string - 'null' admin_note: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - requested_source_type - requested_url - requested_exchange - requested_ticker - requested_slug - normalized_url - source_hash - requester_user_id - requester_org_id - status - public_source_id - admin_note - created_at - updated_at public_source_id: type: - string - 'null' required: - request - public_source_id /v1/admin/index-requests/{id}/reject: post: operationId: rejectPublicIndexRequest summary: Reject an index request tags: - Public Sources security: - SharedSecret: [] parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: note: type: string additionalProperties: true responses: '200': description: Index request rejected. content: application/json: schema: type: object properties: request: type: object properties: id: type: string requested_source_type: type: string enum: *ref_65 requested_url: type: - string - 'null' requested_exchange: type: - string - 'null' requested_ticker: type: - string - 'null' requested_slug: type: - string - 'null' normalized_url: type: - string - 'null' source_hash: type: string requester_user_id: type: string requester_org_id: type: - string - 'null' status: type: string enum: *ref_66 public_source_id: type: - string - 'null' admin_note: type: - string - 'null' created_at: type: string updated_at: type: string required: - id - requested_source_type - requested_url - requested_exchange - requested_ticker - requested_slug - normalized_url - source_hash - requester_user_id - requester_org_id - status - public_source_id - admin_note - created_at - updated_at required: - request /v1/collections: get: operationId: listCollections summary: List collections tags: - Collections responses: '200': description: List of collections owned by the authenticated key. content: application/json: schema: type: object properties: collections: type: array items: type: object properties: id: type: string name: type: string slug: type: string description: type: - string - 'null' visibility: type: string enum: &ref_68 - private - public created_at: type: string format: date-time document_count: type: integer public_path: type: - string - 'null' public_url: type: - string - 'null' format: uri extraction_schemas: type: array items: type: object properties: id: type: string version: type: number const: 1 name: type: string description: type: string fields: type: array items: type: object properties: key: type: string label: type: string type: type: string enum: &ref_67 - string - number - currency - percentage - date - boolean - array - enum description: type: string required: type: boolean default: true enum_values: type: array items: type: string currency_code: type: string order: type: integer required: - key - label - type - required minItems: 1 maxItems: 50 required: - id - version - name - fields maxItems: 20 required: - id - name - slug - description - visibility - created_at - document_count - public_path - public_url - extraction_schemas required: - collections '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createCollection summary: Create a collection tags: - Collections requestBody: content: application/json: schema: type: object properties: name: type: string slug: type: string description: type: string document_ids: type: array items: type: string extraction_schemas: type: array items: type: object properties: id: type: string version: type: number const: 1 name: type: string description: type: string fields: type: array items: type: object properties: key: type: string label: type: string type: type: string enum: *ref_67 description: type: string required: type: boolean default: true enum_values: type: array items: type: string currency_code: type: string order: type: integer required: - key - label - type minItems: 1 maxItems: 50 required: - id - version - name - fields maxItems: 20 required: - name responses: '201': description: Collection created. content: application/json: schema: type: object properties: id: type: string name: type: string slug: type: string description: type: - string - 'null' visibility: type: string enum: *ref_68 created_at: type: string format: date-time document_count: type: integer public_path: type: - string - 'null' public_url: type: - string - 'null' format: uri extraction_schemas: type: array items: type: object properties: id: type: string version: type: number const: 1 name: type: string description: type: string fields: type: array items: type: object properties: key: type: string label: type: string type: type: string enum: *ref_67 description: type: string required: type: boolean default: true enum_values: type: array items: type: string currency_code: type: string order: type: integer required: - key - label - type - required minItems: 1 maxItems: 50 required: - id - version - name - fields maxItems: 20 required: - id - name - slug - description - visibility - created_at - document_count - public_path - public_url - extraction_schemas '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}: get: operationId: getCollection summary: Get a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: Collection with document list. content: application/json: schema: type: object properties: id: type: string name: type: string slug: type: string description: type: - string - 'null' visibility: type: string enum: *ref_68 created_at: type: string format: date-time document_count: type: integer public_path: type: - string - 'null' public_url: type: - string - 'null' format: uri extraction_schemas: type: array items: type: object properties: id: type: string version: type: number const: 1 name: type: string description: type: string fields: type: array items: type: object properties: key: type: string label: type: string type: type: string enum: *ref_67 description: type: string required: type: boolean default: true enum_values: type: array items: type: string currency_code: type: string order: type: integer required: - key - label - type - required minItems: 1 maxItems: 50 required: - id - version - name - fields maxItems: 20 documents: type: array items: type: object properties: id: type: string added_at: type: string file_name: type: - string - 'null' phase: type: - string - 'null' pages_total: type: - integer - 'null' total_nodes: type: - integer - 'null' source: type: - string - 'null' required: - id - added_at - file_name - phase - pages_total - total_nodes - source required: - id - name - slug - description - visibility - created_at - document_count - public_path - public_url - extraction_schemas - documents '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 patch: operationId: updateCollection summary: Update a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: name: type: string slug: type: string description: type: string visibility: type: string enum: - private - public extraction_schemas: type: - array - 'null' items: type: object properties: id: type: string version: type: number const: 1 name: type: string description: type: string fields: type: array items: type: object properties: key: type: string label: type: string type: type: string enum: *ref_67 description: type: string required: type: boolean default: true enum_values: type: array items: type: string currency_code: type: string order: type: integer required: - key - label - type minItems: 1 maxItems: 50 required: - id - version - name - fields maxItems: 20 responses: '200': description: Collection updated. content: application/json: schema: type: object properties: ok: type: boolean required: - ok '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteCollection summary: Delete a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: Collection deleted. content: application/json: schema: type: object properties: ok: type: boolean required: - ok '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/documents: post: operationId: addDocumentsToCollection summary: Add documents to a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: document_ids: type: array items: type: string minItems: 1 required: - document_ids responses: '200': description: Documents added. content: application/json: schema: type: object properties: ok: type: boolean added: type: integer required: - ok - added '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: removeDocumentsFromCollection summary: Remove documents from a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: document_ids: type: array items: type: string minItems: 1 required: - document_ids responses: '200': description: Documents removed. content: application/json: schema: type: object properties: ok: type: boolean removed: type: integer required: - ok - removed '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/query: post: operationId: queryCollection summary: Query a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: query: type: string stream: type: boolean required: - query responses: '200': description: Query result. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/export: get: operationId: exportCollection summary: Export a collection tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: Collection export. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/cache: delete: operationId: purgeCollectionCache summary: Purge collection cache tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: Cache purged. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/connectors: get: operationId: listConnectors summary: List collection connectors tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: List of connectors. content: application/json: schema: type: object properties: connectors: type: array items: type: object properties: id: type: string type: type: string plugin_ref: type: string config_json: type: string schedule: type: - string - 'null' watermark: type: - string - 'null' watermark_type: type: string status: type: string enum: &ref_69 - active - paused - error allowed_hosts_json: type: string last_polled_at: type: - number - 'null' last_found: type: number last_ingested: type: number created_at: type: number required: - id - type - plugin_ref - config_json - schedule - watermark - watermark_type - status - allowed_hosts_json - last_polled_at - last_found - last_ingested - created_at required: - connectors '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createConnector summary: Create a collection connector description: >- Subscribe this collection to an external feed. The connector will poll the source on a schedule and auto-ingest new PDFs. tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: type: type: string config: type: object additionalProperties: {} schedule: type: string allowed_hosts: type: array items: type: string required: - type responses: '201': description: Connector created. content: application/json: schema: type: object properties: id: type: string type: type: string plugin_ref: type: string config_json: type: string schedule: type: - string - 'null' watermark: type: - string - 'null' watermark_type: type: string status: type: string enum: *ref_69 allowed_hosts_json: type: string last_polled_at: type: - number - 'null' last_found: type: number last_ingested: type: number created_at: type: number required: - id - type - plugin_ref - config_json - schedule - watermark - watermark_type - status - allowed_hosts_json - last_polled_at - last_found - last_ingested - created_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/connectors/{cid}: patch: operationId: updateConnector summary: Update a connector tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: cid description: Connector ID (`conn-...`) schema: type: string required: true requestBody: content: application/json: schema: type: object properties: config: type: object additionalProperties: {} schedule: type: - string - 'null' status: type: string enum: - active - paused - error allowed_hosts: type: array items: type: string responses: '200': description: Connector updated. content: application/json: schema: type: object properties: id: type: string type: type: string plugin_ref: type: string config_json: type: string schedule: type: - string - 'null' watermark: type: - string - 'null' watermark_type: type: string status: type: string enum: *ref_69 allowed_hosts_json: type: string last_polled_at: type: - number - 'null' last_found: type: number last_ingested: type: number created_at: type: number required: - id - type - plugin_ref - config_json - schedule - watermark - watermark_type - status - allowed_hosts_json - last_polled_at - last_found - last_ingested - created_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 delete: operationId: deleteConnector summary: Delete a connector tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: cid description: Connector ID (`conn-...`) schema: type: string required: true responses: '204': description: Connector deleted. '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/connectors/{cid}/poll: post: operationId: pollConnector summary: Trigger on-demand connector poll description: Immediately poll the connector source and ingest any new candidates. Same code path as scheduled ticks. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: cid description: Connector ID (`conn-...`) schema: type: string required: true responses: '200': description: Poll result. content: application/json: schema: type: object properties: found: type: number new: type: number ingested: type: number errors: type: number required: - found - new - ingested - errors '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/connectors/{cid}/log: get: operationId: getConnectorLog summary: Get connector tick history tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: cid description: Connector ID (`conn-...`) schema: type: string required: true - in: query name: limit description: Max entries to return (default 50, max 200) schema: type: number responses: '200': description: Tick history. content: application/json: schema: type: object properties: ticks: type: array items: type: object properties: id: type: number connector_id: type: string tick_at: type: number found: type: number new: type: number ingested: type: number skipped: type: number failed: type: number duration_ms: type: - number - 'null' error: type: - string - 'null' watermark_before: type: - string - 'null' watermark_after: type: - string - 'null' required: - id - connector_id - tick_at - found - new - ingested - skipped - failed - duration_ms - error - watermark_before - watermark_after required: - ticks '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox: get: operationId: listInbox summary: List inbox items description: List candidates in the collection inbox. Filter by tag with `?tag=pending`. tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true - in: query name: tag description: Filter items containing this tag (e.g. "pending", "promoted", "rejected") schema: type: string - in: query name: limit description: Max items to return (default 200, max 500) schema: type: number responses: '200': description: Inbox items. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: number source_id: type: string connector_id: type: string title: type: - string - 'null' pdf_url: type: - string - 'null' html_url: type: - string - 'null' published_at: type: - string - 'null' metadata_json: type: - string - 'null' tags: type: string document_id: type: - string - 'null' score: type: - number - 'null' preview_abstract: type: - string - 'null' preview_authors: type: - string - 'null' preview_thumbnail_url: type: - string - 'null' preview_source_url: type: - string - 'null' received_at: type: number promoted_at: type: - number - 'null' expires_at: type: - number - 'null' required: - id - source_id - connector_id - title - pdf_url - html_url - published_at - metadata_json - tags - document_id - score - preview_abstract - preview_authors - preview_thumbnail_url - preview_source_url - received_at - promoted_at - expires_at required: - items '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox/stats: get: operationId: getInboxStats summary: Get inbox statistics description: Count inbox items grouped by tag. tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: Inbox stats. content: application/json: schema: type: object properties: total: type: number by_tag: type: object additionalProperties: type: number required: - total - by_tag '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox/{iid}/promote: post: operationId: promoteInboxItem summary: Promote an inbox item description: Upload the candidate PDF as a document and register it in the collection. Sets tags to ["promoted"]. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: iid description: Inbox item ID (integer) schema: type: number required: true responses: '200': description: Promotion result. content: application/json: schema: type: object properties: document_id: type: string required: - document_id '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox/{iid}/reject: post: operationId: rejectInboxItem summary: Reject an inbox item description: Remove "pending" tag and add "rejected". The item stays in inbox as audit trail. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: iid description: Inbox item ID (integer) schema: type: number required: true responses: '200': description: Updated item. content: application/json: schema: type: object properties: id: type: number tags: type: array items: type: string required: - id - tags '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox/{iid}/tags: patch: operationId: updateInboxTags summary: Update inbox item tags description: Add or remove freeform tags on an inbox item. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: iid description: Inbox item ID (integer) schema: type: number required: true requestBody: content: application/json: schema: type: object properties: add: type: array items: type: string remove: type: array items: type: string responses: '200': description: Updated item. content: application/json: schema: type: object properties: id: type: number tags: type: array items: type: string required: - id - tags '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/inbox/{iid}: delete: operationId: deleteInboxItem summary: Delete an inbox item description: Permanently remove an inbox item. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: iid description: Inbox item ID (integer) schema: type: number required: true responses: '204': description: Item deleted. '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/plugins: get: operationId: listPlugins summary: List installed plugins tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true responses: '200': description: List of installed plugins. content: application/json: schema: type: array items: type: object properties: id: type: string source: type: string version: type: string manifest_json: type: string config_json: type: string status: type: string enum: &ref_70 - active - paused - error installed_at: type: number last_run_at: type: - number - 'null' docs_processed: type: number docs_total: type: number docs_with_data: type: number required: - id - source - version - manifest_json - config_json - status - installed_at - last_run_at - docs_processed - docs_total '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: installPlugin summary: Install a plugin on a collection description: Register a plugin with the collection. The plugin will be stored and can be triggered to process documents. tags: - Collections parameters: - in: path name: id description: Collection ID (`col-...`), public slug ref (`reading-list-40da0684`), or collection name. schema: type: string required: true requestBody: content: application/json: schema: type: object properties: id: type: string source: type: string version: type: string config: type: object additionalProperties: {} manifest: type: object additionalProperties: {} required: - id - source responses: '201': description: Plugin installed. content: application/json: schema: type: object properties: id: type: string source: type: string version: type: string manifest_json: type: string config_json: type: string status: type: string enum: *ref_70 installed_at: type: number last_run_at: type: - number - 'null' docs_processed: type: number docs_total: type: number docs_with_data: type: number required: - id - source - version - manifest_json - config_json - status - installed_at - last_run_at - docs_processed - docs_total '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/plugins/{pid}: delete: operationId: uninstallPlugin summary: Uninstall a plugin description: Remove a plugin and all its data (plugin_data, plugin_kv) from the collection. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: pid description: Plugin ID schema: type: string required: true responses: '200': description: Plugin uninstalled. content: application/json: schema: type: object properties: ok: type: boolean const: true required: - ok '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/plugins/{pid}/run: post: operationId: runPlugin summary: Trigger a plugin run description: >- Trigger the plugin to process collection documents. Phase 1: updates last_run_at timestamp. Phase 2 will add WfP execution. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: pid description: Plugin ID schema: type: string required: true responses: '200': description: Plugin run triggered. content: application/json: schema: type: object properties: status: type: string const: triggered plugin_id: type: string required: - status - plugin_id '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/plugins/{pid}/data: get: operationId: getPluginData summary: Get plugin output data description: Retrieve data generated by a plugin. Optionally filter by document_id. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: pid description: Plugin ID schema: type: string required: true - in: query name: document_id description: Filter by document ID schema: type: string responses: '200': description: Plugin data rows. content: application/json: schema: type: array items: type: object properties: plugin_id: type: string document_id: type: string component_key: type: string data_json: type: string generated_at: type: number required: - plugin_id - document_id - component_key - data_json - generated_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/collections/{id}/documents/{docId}/components: get: operationId: getDocumentComponents summary: Get plugin components for a document description: Retrieve all plugin-generated component data for a specific document, grouped by component_key. tags: - Collections parameters: - in: path name: id description: Collection ID schema: type: string required: true - in: path name: docId description: Document ID schema: type: string required: true responses: '200': description: Component data keyed by component_key. content: application/json: schema: type: object additionalProperties: type: object properties: plugin_id: type: string source: type: string data: {} generated_at: type: number required: - plugin_id - source - generated_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings: get: operationId: listFilings summary: List filings tags: - Filings security: [] parameters: - in: query name: exchange schema: type: string - in: query name: ticker schema: type: string - in: query name: type schema: type: string - in: query name: limit schema: type: integer responses: '200': description: List of filings. content: application/json: schema: type: object properties: filings: type: array items: type: object properties: exchange: type: string ticker: type: string slug: type: string type: type: string filed_at: type: string required: - exchange - ticker - slug - type - filed_at required: - filings '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}: get: operationId: getFiling summary: Get a filing tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true responses: '200': description: Filing details. content: application/json: schema: type: object properties: exchange: type: string ticker: type: string slug: type: string type: type: string filed_at: type: string required: - exchange - ticker - slug - type - filed_at '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/pages: get: operationId: listFilingPages summary: List pages in a filing tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true responses: '200': description: List of filing pages. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/page/{page_number}: get: operationId: getFilingPage summary: Get a filing page tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true - in: path name: page_number description: 1-based page number. schema: type: integer minimum: 1 required: true responses: '200': description: Filing page content. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/nodes: get: operationId: listFilingNodes summary: List nodes in a filing tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true - in: query name: type schema: type: string - in: query name: page schema: type: integer - in: query name: limit schema: type: integer - in: query name: offset schema: type: integer responses: '200': description: List of filing nodes. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/status: get: operationId: getFilingStatus summary: Get filing processing status tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true responses: '200': description: Filing status. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/search: get: operationId: searchFiling summary: Search within a filing tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true - in: query name: q description: Search query (required). schema: type: string required: true responses: '200': description: Search results. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/filings/{exchange}/{ticker}/{slug}/audit: get: operationId: getFilingAudit summary: Get filing audit trail tags: - Filings security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true - in: path name: slug schema: type: string required: true responses: '200': description: Audit trail for the filing. content: application/json: schema: type: object additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/companies: get: operationId: listCompanies summary: List companies tags: - Companies security: [] parameters: - in: query name: exchange schema: type: string responses: '200': description: List of companies. content: application/json: schema: type: object properties: companies: type: array items: type: object properties: exchange: type: string ticker: type: string name: type: string required: - exchange - ticker - name required: - companies '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/companies/{exchange}/{ticker}: get: operationId: getCompany summary: Get a company tags: - Companies security: [] parameters: - in: path name: exchange schema: type: string required: true - in: path name: ticker schema: type: string required: true responses: '200': description: Company details. content: application/json: schema: type: object properties: exchange: type: string ticker: type: string name: type: string required: - exchange - ticker - name '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/key-workflow: get: operationId: getKeyWorkflow summary: Get default workflow for API key tags: - Configuration responses: '200': description: Key workflow configuration. content: application/json: schema: type: object properties: key_id: type: string user_id: type: string default_capabilities: type: object additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - key_id - user_id - default_capabilities '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 put: operationId: updateKeyWorkflow summary: Update default workflow for API key tags: - Configuration requestBody: content: application/json: schema: type: object properties: default_capabilities: type: object additionalProperties: {} required: - default_capabilities responses: '200': description: Updated key workflow configuration. content: application/json: schema: type: object properties: key_id: type: string user_id: type: string default_capabilities: type: object additionalProperties: {} created_at: type: string format: date-time updated_at: type: string format: date-time required: - key_id - user_id - default_capabilities '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /exports/{id}/{format}: get: operationId: getExport summary: Get document export tags: - Exports security: [] parameters: - in: path name: id description: Document ID. schema: type: string required: true - in: path name: format description: Export format. schema: type: string enum: - snapshot - markdown - excel - docx - audit required: true responses: '200': description: Export file or JSON. content: application/json: schema: type: object additionalProperties: true text/markdown: schema: type: string application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string format: binary application/vnd.openxmlformats-officedocument.wordprocessingml.document: schema: type: string format: binary '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /exports/{id}/audit/verify: get: operationId: verifyAudit summary: Verify audit trail integrity tags: - Exports security: [] parameters: - in: path name: id description: Document ID. schema: type: string required: true - in: query name: v description: Version to verify. schema: type: string responses: '200': description: Audit verification result. content: application/json: schema: type: object properties: version: type: string documentLog: {} vendorLog: {} required: - version '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows: post: operationId: createWorkflow summary: Create a workflow description: >- Creates a hosted workflow from an agent workflow script (`code`), a step-definition `definition`, or a `catalog_workflow_id` seed. Supplying `params`/`inputs` (or `run: true`) also starts a run, returned in the `run` field. tags: - Workflows requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 120 catalog_workflow_id: type: string code: type: string definition: type: object additionalProperties: {} params: {} inputs: {} run: type: boolean retention: type: object properties: successRetention: type: string maxLength: 64 errorRetention: type: string maxLength: 64 responses: '201': description: Workflow created (with an embedded run when one was started). content: application/json: schema: type: object properties: object: type: string const: workflow id: type: string workflow_id: type: string name: type: - string - 'null' version_id: type: string code_hash: type: - string - 'null' agent_workflow: type: - object - 'null' additionalProperties: {} definition_hash: type: - string - 'null' entrypoint: type: - string - 'null' definition: type: - object - 'null' additionalProperties: {} ast: type: - object - 'null' additionalProperties: {} visualization: type: - object - 'null' additionalProperties: {} validation: type: - object - 'null' additionalProperties: {} readiness: type: object additionalProperties: {} execution_mode: type: string runnable: type: boolean created_at: type: string run: type: - object - 'null' properties: object: type: string const: run id: type: string run_id: type: string workflow_id: type: string status: type: string status_url: type: string required: - object - id - run_id - workflow_id - status - status_url required: - object - id - workflow_id - name - version_id - code_hash - agent_workflow - definition_hash - entrypoint - definition - ast - visualization - validation - readiness - execution_mode - runnable - created_at - run additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/catalog: get: operationId: listWorkflowCatalog summary: List the workflow catalog description: >- Returns the built-in workflow templates and their capabilities, including inputs, steps, output contract, AST, and visualization projection. tags: - Workflows security: [] responses: '200': description: Built-in workflow catalog entries. content: application/json: schema: type: object properties: object: type: string const: list type: type: string const: workflow_catalog data: type: array items: type: object properties: object: type: string const: workflow_catalog_entry id: type: string workflow_id: type: string name: type: string label: type: string description: type: string source: type: string visibility: type: string workflow_kind: type: string const: data_pipeline output_contract: type: string execution_mode: type: string runnable: type: boolean run_endpoint: type: - string - 'null' version: type: integer version_id: type: string inputs: type: array items: type: object properties: name: type: string type: type: string required: type: boolean required: - name - type additionalProperties: true steps: type: array items: type: object additionalProperties: {} definition: type: object additionalProperties: {} ast: type: object additionalProperties: {} visualization: type: object additionalProperties: {} tags: type: array items: type: string required: - object - id - workflow_id - name - label - source - visibility - workflow_kind - output_contract - execution_mode - runnable - run_endpoint - version - version_id - inputs - steps - definition - ast - visualization - tags additionalProperties: true required: - object - type - data '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/runs/{run_id}: get: operationId: getWorkflowRun summary: Get a workflow run snapshot description: >- Returns the current snapshot for a workflow run. The fields depend on the run execution mode (agent workflow script, step definition, or dynamic worker code). tags: - Workflows parameters: - in: path name: run_id description: Workflow run ID (`dynrun_...`). schema: type: string required: true responses: '200': description: Workflow run snapshot. content: application/json: schema: type: object properties: object: type: string const: run id: type: string run_id: type: string workflow_id: type: string status: type: string execution_mode: type: string enum: - dynamic_worker_code - step_definition - agent_workflow_script output: {} manifest: type: object additionalProperties: {} required: - object - id - run_id - workflow_id - status additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-device-preprocessing/runs: post: operationId: createInvoiceDevicePreprocessingRun summary: Start invoice device preprocessing description: >- Starts a durable invoice-device-preprocessing workflow before upload. The workflow waits on device_preprocessing.completed while the scanner performs edge detection, perspective correction, crop, deskew, and local normalization. tags: - Workflows requestBody: required: true content: application/json: schema: type: object properties: source: type: string processor: type: string page_count: type: integer exclusiveMinimum: 0 output_mime_type: type: string file_name: type: string responses: '202': description: Device preprocessing workflow started. content: application/json: schema: type: object properties: object: type: string const: workflow_run id: type: string run_id: type: string workflow_name: type: string const: invoice-device-preprocessing workflow_binding: type: string const: INVOICE_DEVICE_PREPROCESSING_WORKFLOW workflow_label: type: string const: Device preprocessing status: type: string event_type: type: string const: device_preprocessing.completed status_url: type: string event_url: type: string required: - object - id - run_id - workflow_name - workflow_binding - workflow_label - status - event_type '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-device-preprocessing/runs/{run_id}: get: operationId: getInvoiceDevicePreprocessingRun summary: Get invoice device preprocessing run tags: - Workflows parameters: - in: path name: run_id description: Invoice device preprocessing workflow run ID (`idp_...`). schema: type: string required: true responses: '200': description: Device preprocessing workflow run. content: application/json: schema: type: object properties: object: type: string const: workflow_run id: type: string run_id: type: string workflow_name: type: string const: invoice-device-preprocessing workflow_binding: type: string const: INVOICE_DEVICE_PREPROCESSING_WORKFLOW workflow_label: type: string const: Device preprocessing status: type: string event_type: type: string const: device_preprocessing.completed status_url: type: string event_url: type: string required: - object - id - run_id - workflow_name - workflow_binding - workflow_label - status - event_type '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-device-preprocessing/runs/{run_id}/events/{event_type}: post: operationId: completeInvoiceDevicePreprocessingRun summary: Complete invoice device preprocessing description: >- Sends the device_preprocessing.completed event to the waiting workflow run. Clients call this after local scan preprocessing and before uploading the normalized image or PDF. tags: - Workflows parameters: - in: path name: run_id description: Invoice device preprocessing workflow run ID (`idp_...`). schema: type: string required: true - in: path name: event_type schema: type: string const: device_preprocessing.completed required: true requestBody: required: true content: application/json: schema: type: object properties: step: type: string const: device_preprocessing event_type: type: string const: device_preprocessing.completed status: type: string const: completed source: type: string processor: type: string operations: type: array items: type: string page_count: type: integer exclusiveMinimum: 0 output_mime_type: type: string processed_before_upload: type: boolean completed_at: type: string responses: '202': description: Device preprocessing completion event accepted. content: application/json: schema: type: object properties: object: type: string const: workflow_run id: type: string run_id: type: string workflow_name: type: string const: invoice-device-preprocessing workflow_binding: type: string const: INVOICE_DEVICE_PREPROCESSING_WORKFLOW workflow_label: type: string const: Device preprocessing status: type: string event_type: type: string const: device_preprocessing.completed status_url: type: string event_url: type: string required: - object - id - run_id - workflow_name - workflow_binding - workflow_label - status - event_type '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs: get: operationId: listInvoiceExtractionRuns summary: List invoice extraction runs description: >- Returns signed-in account invoice extraction runs. Runs are backed by SessionAgent state and indexed from the user session registry. tags: - Workflows parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 - in: query name: cursor schema: type: string responses: '200': description: Invoice extraction runs. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: id: type: string minLength: 1 run_id: type: string minLength: 1 object: type: string const: run status: type: string minLength: 1 workflow_name: type: string const: invoice-extraction workflow_label: type: string minLength: 1 workflow_version: type: integer exclusiveMinimum: 0 quality: type: string enum: &ref_71 - fast - balanced - high inputs: type: array items: type: object properties: file_id: type: string minLength: 1 required: - file_id table_id: type: - string - 'null' minLength: 1 agent_id: type: - string - 'null' minLength: 1 events_url: type: string minLength: 1 stream_url: type: string minLength: 1 rows_url: type: string minLength: 1 exports: type: object properties: csv_url: type: string minLength: 1 json_url: type: string minLength: 1 xml_url: type: string minLength: 1 xlsx_url: type: string minLength: 1 required: - csv_url - json_url additionalProperties: true created_at: type: string minLength: 1 required: - id - run_id - object - status - workflow_name - workflow_label - workflow_version - quality - inputs - table_id - events_url - stream_url - rows_url - exports - created_at additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - object - data - has_more - next_cursor additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 post: operationId: createInvoiceExtractionRun summary: Run invoice extraction description: >- Starts the built-in invoice-extraction workflow for one or more uploaded files. The API accepts File references, an optional existing Table, and a quality preset; parser and model controls remain internal. tags: - Workflows requestBody: required: true content: application/json: schema: type: object properties: inputs: type: array items: type: object properties: file_id: type: string minLength: 1 required: - file_id minItems: 1 table_id: type: string minLength: 1 quality: type: string enum: *ref_71 default: balanced required: - inputs additionalProperties: true responses: '202': description: Invoice extraction run accepted. content: application/json: schema: type: object properties: id: type: string minLength: 1 run_id: type: string minLength: 1 object: type: string const: run status: type: string minLength: 1 workflow_name: type: string const: invoice-extraction workflow_label: type: string minLength: 1 workflow_version: type: integer exclusiveMinimum: 0 quality: type: string enum: *ref_71 inputs: type: array items: type: object properties: file_id: type: string minLength: 1 required: - file_id table_id: type: - string - 'null' minLength: 1 agent_id: type: - string - 'null' minLength: 1 events_url: type: string minLength: 1 stream_url: type: string minLength: 1 rows_url: type: string minLength: 1 exports: type: object properties: csv_url: type: string minLength: 1 json_url: type: string minLength: 1 xml_url: type: string minLength: 1 xlsx_url: type: string minLength: 1 required: - csv_url - json_url additionalProperties: true created_at: type: string minLength: 1 required: - id - run_id - object - status - workflow_name - workflow_label - workflow_version - quality - inputs - table_id - events_url - stream_url - rows_url - exports - created_at additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}: get: operationId: getInvoiceExtractionRun summary: Get an invoice extraction run tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction run status and output links. content: application/json: schema: type: object properties: id: type: string minLength: 1 run_id: type: string minLength: 1 object: type: string const: run status: type: string minLength: 1 workflow_name: type: string const: invoice-extraction workflow_label: type: string minLength: 1 workflow_version: type: integer exclusiveMinimum: 0 quality: type: string enum: *ref_71 inputs: type: array items: type: object properties: file_id: type: string minLength: 1 required: - file_id table_id: type: - string - 'null' minLength: 1 agent_id: type: - string - 'null' minLength: 1 events_url: type: string minLength: 1 stream_url: type: string minLength: 1 rows_url: type: string minLength: 1 exports: type: object properties: csv_url: type: string minLength: 1 json_url: type: string minLength: 1 xml_url: type: string minLength: 1 xlsx_url: type: string minLength: 1 required: - csv_url - json_url additionalProperties: true created_at: type: string minLength: 1 required: - id - run_id - object - status - workflow_name - workflow_label - workflow_version - quality - inputs - table_id - events_url - stream_url - rows_url - exports - created_at additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/retry: post: operationId: retryInvoiceExtractionRun summary: Retry an invoice extraction run description: >- Creates a new invoice extraction run using the same input files, Table, and quality preset as the referenced run. tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '202': description: Retry run accepted. content: application/json: schema: type: object properties: id: type: string minLength: 1 run_id: type: string minLength: 1 object: type: string const: run status: type: string minLength: 1 workflow_name: type: string const: invoice-extraction workflow_label: type: string minLength: 1 workflow_version: type: integer exclusiveMinimum: 0 quality: type: string enum: *ref_71 inputs: type: array items: type: object properties: file_id: type: string minLength: 1 required: - file_id table_id: type: - string - 'null' minLength: 1 agent_id: type: - string - 'null' minLength: 1 events_url: type: string minLength: 1 stream_url: type: string minLength: 1 rows_url: type: string minLength: 1 exports: type: object properties: csv_url: type: string minLength: 1 json_url: type: string minLength: 1 xml_url: type: string minLength: 1 xlsx_url: type: string minLength: 1 required: - csv_url - json_url additionalProperties: true created_at: type: string minLength: 1 required: - id - run_id - object - status - workflow_name - workflow_label - workflow_version - quality - inputs - table_id - events_url - stream_url - rows_url - exports - created_at additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/exceptions: get: operationId: listInvoiceExtractionExceptions summary: List invoice extraction exceptions description: >- Returns review exceptions derived from the run result rows, including missing required invoice fields and failed empty results. tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction exceptions. content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: id: type: string minLength: 1 object: type: string const: invoice_exception run_id: type: string minLength: 1 table_id: type: string minLength: 1 row_id: type: - string - 'null' minLength: 1 file_id: type: - string - 'null' minLength: 1 field: type: - string - 'null' minLength: 1 code: type: string enum: - missing_required_field - document_parse_failed - empty_result - run_failed - validation_warning severity: type: string enum: - warning - error status: type: string enum: - open - resolved message: type: string minLength: 1 value: {} source_page: type: - integer - 'null' exclusiveMinimum: 0 source_bbox: type: - string - 'null' minLength: 1 created_at: type: string minLength: 1 required: - id - object - run_id - table_id - code - severity - status - message - created_at additionalProperties: true has_more: type: boolean next_cursor: type: - string - 'null' required: - object - data additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/exceptions/{exception_id}/resolve: post: operationId: resolveInvoiceExtractionException summary: Resolve an invoice extraction exception description: >- Approves or corrects an invoice exception. Corrections patch the owning Table row, so derived exception lists stop reporting the issue. tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true - in: path name: exception_id description: Invoice exception ID. schema: type: string required: true requestBody: required: true content: application/json: schema: type: object properties: row_id: type: string field: type: string value: {} action: type: string enum: - approve - correct required: - row_id responses: '200': description: Invoice exception resolved. content: application/json: schema: type: object properties: object: type: string const: invoice_exception_resolution id: type: string run_id: type: string table_id: type: string row_id: type: string status: type: string const: resolved required: - object - id - run_id - table_id - row_id - status '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/results.json: get: operationId: getInvoiceExtractionResultsJson summary: Export invoice extraction results as JSON tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction rows in JSON form. content: application/json: schema: type: object properties: object: type: string const: invoice_result run_id: type: string table_id: type: string columns: type: array items: type: object properties: name: type: string type: type: string required: - name rows: type: array items: type: object additionalProperties: {} total: type: integer minimum: 0 required: - object - run_id - table_id - columns - rows - total additionalProperties: true '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/results.csv: get: operationId: getInvoiceExtractionResultsCsv summary: Export invoice extraction results as CSV tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction rows as CSV. content: text/csv: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/results.xml: get: operationId: getInvoiceExtractionResultsXml summary: Export invoice extraction results as XML tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction rows as XML. content: application/xml: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 /v1/workflows/invoice-extraction/runs/{run_id}/results.xlsx: get: operationId: getInvoiceExtractionResultsXlsx summary: Export invoice extraction results as XLSX tags: - Workflows parameters: - in: path name: run_id description: Invoice extraction run ID (`sess_...`). schema: type: string required: true responses: '200': description: Invoice extraction rows as an Excel workbook. content: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: schema: type: string '400': *ref_3 '401': *ref_2 '403': *ref_4 '404': *ref_5 '409': *ref_6 '422': *ref_7 '429': *ref_8 '500': *ref_9 '504': *ref_10 components: securitySchemes: BearerApiKey: type: http scheme: bearer description: >- API key prefixed with `okra_sk_` (secret) or `okra_pk_` (publishable). Pass as `Authorization: Bearer okra_sk_...`. SharedSecret: type: apiKey in: header name: x-document-agent-secret description: Internal shared secret for server-to-server calls. responses: '400': description: The server cannot process the request due to a client error. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - BAD_REQUEST description: Machine-readable UPPER_SNAKE_CASE error code. example: BAD_REQUEST message: type: string description: Human-readable error message. details: description: Optional structured details. '401': description: Authentication is required or the provided credentials are invalid. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED description: Machine-readable UPPER_SNAKE_CASE error code. example: UNAUTHORIZED message: type: string description: Human-readable error message. details: description: Optional structured details. '403': description: The client does not have access rights to the content. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN description: Machine-readable UPPER_SNAKE_CASE error code. example: FORBIDDEN message: type: string description: Human-readable error message. details: description: Optional structured details. '404': description: The server cannot find the requested resource. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND description: Machine-readable UPPER_SNAKE_CASE error code. example: NOT_FOUND message: type: string description: Human-readable error message. details: description: Optional structured details. '409': description: The request conflicts with the current state of the server. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - CONFLICT description: Machine-readable UPPER_SNAKE_CASE error code. example: CONFLICT message: type: string description: Human-readable error message. details: description: Optional structured details. '422': description: The request was well-formed but unable to be followed due to semantic errors. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - SCHEMA_VALIDATION_FAILED description: Machine-readable UPPER_SNAKE_CASE error code. example: SCHEMA_VALIDATION_FAILED message: type: string description: Human-readable error message. details: description: Optional structured details. '429': description: Too many requests in a given amount of time. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - RATE_LIMITED description: Machine-readable UPPER_SNAKE_CASE error code. example: RATE_LIMITED message: type: string description: Human-readable error message. details: description: Optional structured details. '500': description: The server encountered an unexpected condition. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - INTERNAL_ERROR description: Machine-readable UPPER_SNAKE_CASE error code. example: INTERNAL_ERROR message: type: string description: Human-readable error message. details: description: Optional structured details. '504': description: The operation timed out. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - TIMEOUT description: Machine-readable UPPER_SNAKE_CASE error code. example: TIMEOUT message: type: string description: Human-readable error message. details: description: Optional structured details.