openapi: 3.2.0 info: title: Vaquill Ai Matter summary API version: 1.0.0 description: 'Operations tagged Matter summary across 2 of this provider''s published API definitions: vaquill-ai-workspace-openapi.json, vaquill-ai-workspace-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.vaquill.ai/workspace description: Vaquill Legal Workspace API (production) - url: /workspace description: Vaquill Legal Workspace API (relative to the mount) security: - WorkspaceAuth: [] tags: - name: Matter summary description: A citation-backed summary of everything filed to a matter, generated on demand and readable claim by claim. paths: /v1/matters/{matterId}/summaries: get: tags: - Matter summary summary: List matter summaries description: 'Every summary generated for this matter, newest request first. The history of what was asked for and what came back, across both altitudes. `sections` is omitted here (null, not an empty array) because rendering every summary on the page would be three queries per row; fetch one by id for its content. A row can appear that you did not ask for: a document change schedules a debounced regeneration for any altitude that already has a completed summary, so the list grows and `isStale` flips on its own.' operationId: summaries.list parameters: - name: matterId in: path required: true schema: type: string title: Matterid description: '`mat_` identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from `GET /v1/matters`.' - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: How many rows to return, 1 to 200. Defaults to 50. default: 50 title: Limit description: How many rows to return, 1 to 200. Defaults to 50. - name: offset in: query required: false schema: type: integer minimum: 0 description: 'How many rows to skip before returning any. Combine with `limit` to page: `offset=0`, then `offset=50`, and so on. Offsets are positional, not stable, so a set that changes while you page can show a row twice or not at all.' default: 0 title: Offset description: 'How many rows to skip before returning any. Combine with `limit` to page: `offset=0`, then `offset=50`, and so on. Offsets are positional, not stable, so a set that changes while you page can show a row twice or not at all.' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Page_MatterSummary_' example: data: - id: sum_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 matterId: mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 status: succeeded altitude: value title: Acme / Series B Financing matterType: financing isStale: false docCount: 1 docCountUsed: 1 docCountExcluded: 1 warnings: - value createdAt: '2026-08-19T14:32:10Z' completedAt: '2026-08-19T14:32:10Z' sections: - id: 9f2c8b1e-4a7d-43c9-b6e0-f1a2c3d4e5f6 title: Master Services Agreement position: 0 claims: - id: 3d7a1c05-8e64-4b2f-9a1d-7c5e8f0b2a41 text: Neither party shall be liable for indirect or consequential damages. position: 0 claimType: value eventDate: '2026-08-19' confidence: 0.92 citations: - label: 1 documentId: doc_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 documentName: value quote: in no event shall either party be liable for indirect damages pageStart: 1 pageEnd: 1 sourceAvailable: false pagination: limit: 50 offset: 0 total: 128 hasMore: false '422': description: The request does not match the published schema. `errors` names each rejected field and why. The submitted value is never echoed back. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblem' '401': description: The credential is missing, malformed, unknown, revoked or expired. `type` is `invalid-credential`, or `wrong-product-credential` when a `vq_key_` Data API key was sent to this API. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: The credential does not carry a scope this operation requires (`insufficient-scope`), or the organization's installation is suspended (`installation-inactive`). headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: The resource does not exist, is not this organization's, or is outside this installation's matter allowlist. The three are deliberately indistinguishable, so the status code cannot be used to discover which ids exist in another organization. Each resource has its own `type`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Too many requests for this credential's tier. Honour `Retry-After`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: An unexpected error on our side. The body carries a stable `type` and the request id and nothing else; the cause is in our logs. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: A dependency this request needs is unavailable, so nothing was done. Retryable. Authentication fails closed rather than admitting the request, so this is never a statement about your credential. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' post: tags: - Matter summary summary: Generate a matter summary description: 'Generate a summary of the matter. 202 with an operation to poll. **If an up-to-date summary already exists, nothing is re-run.** The operation points at the existing one and reaches `succeeded` on your first poll, which is one code path rather than a second success shape to branch on. The work did succeed; it succeeded earlier. Two callers asking for the same matter, altitude and document set at once attach to one job. That is separate from `Idempotency-Key`, which makes ONE caller''s retry free. 409 when the matter holds no finished documents, 429 when too many generations are already in flight, 503 when the guard deciding that cannot be reached. None of the three writes anything.' operationId: summaries.generate parameters: - name: matterId in: path required: true schema: type: string title: Matterid description: '`mat_` identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from `GET /v1/matters`.' - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key description: A unique value of your choosing, so a retried launch returns the FIRST operation instead of starting a second billable job. Reusing one with a different body is refused. Retrying with the same key and the same body is free and is the intended way to recover from a timeout. requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/MatterSummaryGenerateRequest' - type: 'null' title: Body example: altitude: executive responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Operation' example: id: op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 type: matrix.run status: succeeded createdAt: '2026-08-19T14:32:10Z' completedAt: '2026-08-19T14:32:10Z' matterId: mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 resource: kind: matrix id: mtx_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 url: https://storage.vaquill.ai/exports/msa-acme-v3-redline.docx?signature=... progress: done: 24 total: 128 unit: cells requestId: req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 '422': description: The request does not match the published schema. `errors` names each rejected field and why. The submitted value is never echoed back. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblem' '401': description: The credential is missing, malformed, unknown, revoked or expired. `type` is `invalid-credential`, or `wrong-product-credential` when a `vq_key_` Data API key was sent to this API. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: The credential does not carry a scope this operation requires (`insufficient-scope`), or the organization's installation is suspended (`installation-inactive`). headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: The resource does not exist, is not this organization's, or is outside this installation's matter allowlist. The three are deliberately indistinguishable, so the status code cannot be used to discover which ids exist in another organization. Each resource has its own `type`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Too many requests for this credential's tier. Honour `Retry-After`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: An unexpected error on our side. The body carries a stable `type` and the request id and nothing else; the cause is in our logs. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: A dependency this request needs is unavailable, so nothing was done. Retryable. Authentication fails closed rather than admitting the request, so this is never a statement about your credential. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' servers: - url: https://api.vaquill.ai/workspace description: Vaquill Legal Workspace API (production) - url: /workspace description: Vaquill Legal Workspace API (relative to the mount) /v1/matters/{matterId}/summaries/{summaryId}: get: tags: - Matter summary summary: Get a matter summary description: 'One summary, section by section, with its citations. Sections hold claims and claims hold the passages behind them, already joined: there is no `sectionId` or `claimId` to reassemble. **Resolve a citation by finding its `quote` in the document''s text**, not by any offset; none is published, because the ones we store index a string this API does not serve. `progress` on the operation moves in a few coarse jumps rather than smoothly: the pipeline writes to the job row only when its stage changes, so `Retry-After` over-waits between stages on a job whose median is five minutes. A `404` covers every reason it is not readable, including a `matter_summaries.id` used in place of the `sum_` id this API publishes.' operationId: summaries.get parameters: - name: matterId in: path required: true schema: type: string title: Matterid description: '`mat_` identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from `GET /v1/matters`.' - name: summaryId in: path required: true schema: type: string title: Summaryid description: '`sum_` identifier of the matter summary. Returned on the operation that generated it.' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MatterSummary' example: id: sum_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 matterId: mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 status: succeeded altitude: value title: Acme / Series B Financing matterType: financing isStale: false docCount: 1 docCountUsed: 1 docCountExcluded: 1 warnings: - value createdAt: '2026-08-19T14:32:10Z' completedAt: '2026-08-19T14:32:10Z' sections: - id: 9f2c8b1e-4a7d-43c9-b6e0-f1a2c3d4e5f6 title: Master Services Agreement position: 0 claims: - id: 3d7a1c05-8e64-4b2f-9a1d-7c5e8f0b2a41 text: Neither party shall be liable for indirect or consequential damages. position: 0 claimType: value eventDate: '2026-08-19' confidence: 0.92 citations: - label: 1 documentId: doc_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 documentName: value quote: in no event shall either party be liable for indirect damages pageStart: 1 pageEnd: 1 sourceAvailable: false '422': description: The request does not match the published schema. `errors` names each rejected field and why. The submitted value is never echoed back. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblem' '401': description: The credential is missing, malformed, unknown, revoked or expired. `type` is `invalid-credential`, or `wrong-product-credential` when a `vq_key_` Data API key was sent to this API. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: The credential does not carry a scope this operation requires (`insufficient-scope`), or the organization's installation is suspended (`installation-inactive`). headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: The resource does not exist, is not this organization's, or is outside this installation's matter allowlist. The three are deliberately indistinguishable, so the status code cannot be used to discover which ids exist in another organization. Each resource has its own `type`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Too many requests for this credential's tier. Honour `Retry-After`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: An unexpected error on our side. The body carries a stable `type` and the request id and nothing else; the cause is in our logs. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: A dependency this request needs is unavailable, so nothing was done. Retryable. Authentication fails closed rather than admitting the request, so this is never a statement about your credential. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' servers: - url: https://api.vaquill.ai/workspace description: Vaquill Legal Workspace API (production) - url: /workspace description: Vaquill Legal Workspace API (relative to the mount) /v1/matters/{matterId}/summaries/{summaryId}/exports: post: tags: - Matter summary summary: Export a matter summary as PDF or DOCX description: 'Render the summary to PDF or DOCX and return the bytes. A POST rather than a GET because the file is rendered per call rather than fetched, and recording that as a creation is what lets an audit answer who took a copy and when. 409 while the summary is still generating: it exists, and there is nothing to render yet.' operationId: summaries.export parameters: - name: matterId in: path required: true schema: type: string title: Matterid description: '`mat_` identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from `GET /v1/matters`.' - name: summaryId in: path required: true schema: type: string title: Summaryid description: '`sum_` identifier of the matter summary. Returned on the operation that generated it.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MatterSummaryExportRequest' example: format: pdf responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MatterSummaryExport' example: format: docx filename: msa-acme-v3.docx sizeBytes: 248193 content: UEsDBBQABgAIAAAAIQ... '422': description: The request does not match the published schema. `errors` names each rejected field and why. The submitted value is never echoed back. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/ValidationProblem' '401': description: The credential is missing, malformed, unknown, revoked or expired. `type` is `invalid-credential`, or `wrong-product-credential` when a `vq_key_` Data API key was sent to this API. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: The credential does not carry a scope this operation requires (`insufficient-scope`), or the organization's installation is suspended (`installation-inactive`). headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 WWW-Authenticate: description: RFC 9110 authentication challenge. schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: The resource does not exist, is not this organization's, or is outside this installation's matter allowlist. The three are deliberately indistinguishable, so the status code cannot be used to discover which ids exist in another organization. Each resource has its own `type`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Too many requests for this credential's tier. Honour `Retry-After`. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: An unexpected error on our side. The body carries a stable `type` and the request id and nothing else; the cause is in our logs. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: A dependency this request needs is unavailable, so nothing was done. Retryable. Authentication fails closed rather than admitting the request, so this is never a statement about your credential. headers: X-Request-ID: description: The id of this request. The same value appears as `requestId` in the body. Quote it when contacting support. schema: type: string examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' servers: - url: https://api.vaquill.ai/workspace description: Vaquill Legal Workspace API (production) - url: /workspace description: Vaquill Legal Workspace API (relative to the mount) components: schemas: MatterSummary: properties: id: type: string title: Id description: '`sum_` identifier. The same id the operation''s resource carries, and the only id this API publishes for a summary.' examples: - sum_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 matterId: type: string title: Matterid description: The `mat_` matter this summary covers. examples: - mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 status: $ref: '#/components/schemas/OperationStatus' description: The generation's status, in the same five values every operation uses. examples: - succeeded altitude: anyOf: - type: string - type: 'null' title: Altitude description: 'How much detail was synthesized. `executive` or `detailed`; read it as an open string, because the column carries no constraint. Null on the one row shape where it is genuinely unknown: `matter_summary_jobs` does not record the altitude, so a job whose summary row is gone has nothing to report and the commoner answer would be an invention.' examples: - executive title: anyOf: - type: string - type: 'null' title: Title description: The title the synthesizer gave the matter. Null until it runs. examples: - Acme / Series B Financing matterType: anyOf: - type: string - type: 'null' title: Mattertype description: What the classifier decided the matter is. examples: - financing isStale: type: boolean title: Isstale description: 'True when the matter''s documents have changed since this summary was built. Computed per request, never stored. A summary can also refresh ITSELF: a document change schedules a debounced regeneration for an altitude that already has a completed summary, so `isStale` can flip between two polls with no call from you.' examples: - false docCount: type: integer title: Doccount description: Documents in the matter right now. examples: - 1 docCountUsed: anyOf: - type: integer - type: 'null' title: Doccountused description: Documents this generation read. examples: - 1 docCountExcluded: anyOf: - type: integer - type: 'null' title: Doccountexcluded description: Documents this generation skipped. examples: - 1 warnings: items: type: string type: array title: Warnings description: What the pipeline wants you to know about this result, if anything. examples: - - value createdAt: type: string format: date-time title: Createdat description: When the generation was requested. examples: - '2026-08-19T14:32:10Z' completedAt: anyOf: - type: string format: date-time - type: 'null' title: Completedat description: When the summary finished, read from the summary itself rather than from the job, which records no completion time. examples: - '2026-08-19T14:32:10Z' sections: anyOf: - items: $ref: '#/components/schemas/MatterSummarySection' type: array - type: 'null' title: Sections description: The rendered narrative. Present only on the by-id read; the list omits it rather than sending an empty array, so `null` here means 'not included in this response' and `[]` means 'nothing was written'. additionalProperties: false type: object required: - id - matterId - status - isStale - docCount - createdAt title: MatterSummary description: One generation of a matter summary, and its content once it has one. MatterSummarySection: properties: id: type: string title: Id description: Stable within this summary. examples: - 9f2c8b1e-4a7d-43c9-b6e0-f1a2c3d4e5f6 title: type: string title: Title description: The section heading. examples: - Master Services Agreement position: type: integer title: Position description: Reading order within the summary. examples: - 0 claims: items: $ref: '#/components/schemas/SummaryClaim' type: array title: Claims description: The section's claims. additionalProperties: false type: object required: - id - title - position title: MatterSummarySection description: One heading of the narrative. MatterSummaryExport: properties: format: type: string title: Format description: The format that was rendered. examples: - docx filename: type: string title: Filename description: A filename derived from the matter's own name. examples: - msa-acme-v3.docx sizeBytes: type: integer title: Sizebytes description: Decoded size, so you can check `content` round-tripped. examples: - 248193 content: type: string title: Content description: The file, base64-encoded. examples: - UEsDBBQABgAIAAAAIQ... additionalProperties: false type: object required: - format - filename - sizeBytes - content title: MatterSummaryExport description: 'A rendered summary, returned as bytes rather than as a signed URL. Same reasoning as the facts and draft exports: the renderer runs on demand and writes no object, so a URL would mean storing client work product first.' OperationStatus: type: string enum: - queued - running - succeeded - failed - cancelled title: OperationStatus description: 'The public five. There is no sixth, and there are no synonyms. Internal vocabularies spell terminal success `completed`, `ready`, `extracted`, `succeeded` and `fresh`; terminal failure `failed` and `error`; queued `pending`, `queued` and `draft`. All of that is collapsed here by `app.workspace_api.adapters.status_map`, which refuses to guess.' Pagination: properties: limit: type: integer title: Limit description: The `limit` that was applied to this request. examples: - 50 offset: type: integer title: Offset description: The `offset` that was applied to this request. examples: - 0 total: type: integer title: Total description: Total rows matching the filter, not the number returned in `data`. Use it to size a job before running it. examples: - 128 hasMore: type: boolean title: Hasmore description: True when rows remain beyond this window. Derived from `offset + len(data) < total`, so a full final page correctly reports `false` rather than sending you after an empty page. examples: - false additionalProperties: false type: object required: - limit - offset - total - hasMore title: Pagination description: 'Where the caller is, and whether there is more. `total` is the count of rows matching the filter, not the count returned, so a caller can size a job before running it.' OperationProgress: properties: done: type: integer minimum: 0.0 title: Done description: How many units are finished. examples: - 24 total: type: integer minimum: 0.0 title: Total description: How many units there are in total. Can legitimately be zero for an empty run. examples: - 128 unit: type: string enum: - cells - steps - documents - files - rows - percent title: Unit description: 'What `done` and `total` are counting. Always read it: a workflow run counts `percent` while a matrix run counts `cells`, so `{done: 43, total: 100}` alone is ambiguous.' examples: - cells additionalProperties: false type: object required: - done - total - unit title: OperationProgress description: 'How far along, and in what units. The unit is not decoration. A workflow run stores only a percentage while a matrix run stores cell counts, so `{done: 43, total: 100}` with no unit reads as 43 of 100 documents and a client builds a wrong estimate from it.' SummaryClaim: properties: id: type: string title: Id description: Stable within this summary. examples: - 3d7a1c05-8e64-4b2f-9a1d-7c5e8f0b2a41 text: type: string title: Text description: The claim, as one sentence. examples: - Neither party shall be liable for indirect or consequential damages. position: type: integer title: Position description: Reading order within the section. examples: - 0 claimType: anyOf: - type: string - type: 'null' title: Claimtype description: 'What kind of assertion this is, for example `general` or `event`. Publisher-controlled and open: read it, do not switch on a closed list.' examples: - obligation eventDate: anyOf: - type: string format: date - type: 'null' title: Eventdate description: The date the claim is about, when it names one. examples: - '2026-08-19' confidence: anyOf: - type: number - type: 'null' title: Confidence description: 0 to 1. examples: - 0.92 citations: items: $ref: '#/components/schemas/SummaryCitation' type: array title: Citations description: Every passage behind this claim. additionalProperties: false type: object required: - id - text - position title: SummaryClaim description: One assertion inside a section, with the passages that support it. ValidationProblem: type: object title: ValidationProblem description: A problem document for a schema rejection. `errors` lists the fields that were refused. The value you submitted is deliberately not echoed, so a validation failure cannot copy your content into an error response or into either side's logs. required: - type - title - status - detail - instance - errors properties: type: type: string format: uri description: The stable identifier for this error, and the one field to branch on. Resolves to a page describing it. examples: - https://vaquill.ai/docs/workspace-api/errors/insufficient-scope title: type: string description: A short human-readable summary. examples: - Insufficient scope status: type: integer description: The HTTP status code, repeated. examples: - 403 detail: type: string description: What went wrong on this specific request. May be reworded at any time. examples: - This credential carries matters:read. This operation needs matters:write. instance: type: string description: The path this problem occurred on. examples: - /workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 requestId: type: string description: The id of this request, identical to the `X-Request-ID` response header. Quote it when contacting support. examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 errors: type: array description: One entry per rejected field. items: type: object required: - location - message - type properties: location: type: string description: Dotted path to the rejected field, for example `body.contentMarkdown`. message: type: string description: Why it was rejected. type: type: string description: The validation rule that failed. additionalProperties: true Operation: properties: id: type: string title: Id description: Public identifier, `op_` followed by 32 hex characters. Poll `GET /v1/operations/{operationId}` with it. examples: - op_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 type: type: string title: Type description: What kind of work this is, for example `matrix.run` or `draft.generate`. examples: - matrix.run status: $ref: '#/components/schemas/OperationStatus' description: 'One of five values: `queued`, `running`, `succeeded`, `failed`, `cancelled`. There is no sixth and there are no synonyms. Stop polling once it is `succeeded`, `failed` or `cancelled`.' examples: - succeeded createdAt: type: string format: date-time title: Createdat description: When the operation was accepted (RFC 3339). examples: - '2026-08-19T14:32:10Z' completedAt: anyOf: - type: string format: date-time - type: 'null' title: Completedat description: When the operation reached a terminal status (RFC 3339). Present if and only if the status is terminal. examples: - '2026-08-19T14:32:10Z' matterId: anyOf: - type: string - type: 'null' title: Matterid description: '`mat_` identifier of the matter this work belongs to, when it belongs to one.' examples: - mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 resource: anyOf: - $ref: '#/components/schemas/OperationResource' - type: 'null' description: What the operation produced. Absent until the underlying job row exists, which an idempotent replay can briefly observe, so treat absence as 'not yet' rather than 'never'. error: anyOf: - $ref: '#/components/schemas/OperationError' - type: 'null' description: Why the work failed. Present only when `status` is `failed`. Partial success is `succeeded` with `progress.done < progress.total`, never an error. progress: anyOf: - $ref: '#/components/schemas/OperationProgress' - type: 'null' description: How far along the work is, when the underlying job reports it. Absent does not mean no progress. requestId: anyOf: - type: string - type: 'null' title: Requestid description: The `X-Request-ID` of the request that created this operation. Quote it in a support ticket. examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 additionalProperties: false type: object required: - id - type - status - createdAt title: Operation description: 'One long-running operation, whatever kind of work it is. Readable for `OPERATION_RETENTION_DAYS` after creation, per AIP-151.' MatterSummaryGenerateRequest: properties: altitude: type: string enum: - executive - detailed title: Altitude description: '`executive` for a short brief, `detailed` for the long form. `detailed` uses the stronger synthesis model; both read the same extracted evidence.' default: executive examples: - executive additionalProperties: false type: object title: MatterSummaryGenerateRequest description: 'What to generate. There is no `force`. On the summary route that flag bypasses the already-fresh short circuit and is a straight cost lever with nothing behind it, because metering and usage caps were cut. A caller that genuinely needs a rebuild changes something the corpus hash can see. There is also no cancel operation anywhere on this capability. The web app''s cancel marks the job and its summary `cancelled` and does NOT revoke the Celery task, so the worker keeps running and moves a cancelled job back to `completed` when it finishes. Publishing that would take an operation terminal and then move it, which the operation contract does not allow, and would sell a customer a control over spend that does not stop the spend.' Page_MatterSummary_: properties: data: items: $ref: '#/components/schemas/MatterSummary' type: array title: Data description: The rows in this window, in the collection's default order. pagination: $ref: '#/components/schemas/Pagination' description: Where this window sits in the full result set. additionalProperties: false type: object required: - data - pagination title: Page[MatterSummary] OperationResource: properties: kind: type: string title: Kind description: What sort of thing was produced, for example `matrix` or `document`. examples: - matrix id: type: string title: Id description: Public identifier of the produced resource, carrying its own type prefix, for example `mtx_` for a matrix. examples: - mtx_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 url: anyOf: - type: string - type: 'null' title: Url description: Path on this API where the resource can be read, RELATIVE to the API root and never absolute. Absent when the resource has no addressable path, which happens for work started outside a matter. Absent means the id is real and there is nowhere to GET it; it is not an error. examples: - https://storage.vaquill.ai/exports/msa-acme-v3-redline.docx?signature=... additionalProperties: false type: object required: - kind - id title: OperationResource description: 'What the operation produced, or is producing. `url` is a path on this API rather than an absolute URL, because the service is mounted today and gets its own hostname later (docs 07.5). A relative path survives that move; a baked-in host does not.' MatterSummaryExportRequest: properties: format: type: string enum: - pdf - docx title: Format description: 'There is no CSV: a summary is a narrative with citations, and flattening it into rows would lose the thing being exported.' examples: - pdf additionalProperties: false type: object required: - format title: MatterSummaryExportRequest OperationError: properties: code: type: string title: Code description: Stable, machine-readable failure code. Branch on this, never on `message`. examples: - EXTRACTION_FAILED message: type: string title: Message description: Human-readable explanation, sanitized of internal paths and stack frames. Wording may change; do not parse it. examples: - The upstream extraction did not finish. additionalProperties: false type: object required: - code - message title: OperationError description: 'Why a failed operation failed, in terms a customer can act on. `code` is stable and machine-readable. `message` is sanitized: the internal job tables store stack traces and file paths in their `error_message` columns, and forwarding those verbatim leaks our internals into a customer''s logs.' SummaryCitation: properties: label: type: integer title: Label description: The bracketed marker this citation carries within its section, numbered from 1 per section. Two sections both start at [1]. examples: - 1 documentId: anyOf: - type: string - type: 'null' title: Documentid description: The `doc_` document this passage came from. examples: - doc_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 documentName: anyOf: - type: string - type: 'null' title: Documentname description: The document's filename when the summary was generated. examples: - msa-acme-v3.docx quote: anyOf: - type: string - type: 'null' title: Quote description: The verbatim passage. Locate this string in the document's text to resolve the citation; there is no offset to trust. examples: - in no event shall either party be liable for indirect damages pageStart: anyOf: - type: integer - type: 'null' title: Pagestart description: First page the quote appears on. examples: - 1 pageEnd: anyOf: - type: integer - type: 'null' title: Pageend description: Last page the quote appears on. examples: - 1 sourceAvailable: type: boolean title: Sourceavailable description: False when the cited document has since been removed from the workspace. The quote is a snapshot and stays accurate; there is simply nothing left to open. examples: - false additionalProperties: false type: object required: - label - sourceAvailable title: SummaryCitation description: One passage behind a claim, snapshotted when the summary was generated. Problem: type: object title: Problem description: An RFC 9457 problem document. Branch on `type`, which is stable; `title` and `detail` are written for people and may be reworded. Some problems carry extra members (`requiredScopes`, `limit`, `expectedVersion`), which is why this object is open. required: - type - title - status - detail - instance properties: type: type: string format: uri description: The stable identifier for this error, and the one field to branch on. Resolves to a page describing it. examples: - https://vaquill.ai/docs/workspace-api/errors/insufficient-scope title: type: string description: A short human-readable summary. examples: - Insufficient scope status: type: integer description: The HTTP status code, repeated. examples: - 403 detail: type: string description: What went wrong on this specific request. May be reworded at any time. examples: - This credential carries matters:read. This operation needs matters:write. instance: type: string description: The path this problem occurred on. examples: - /workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 requestId: type: string description: The id of this request, identical to the `X-Request-ID` response header. Quote it when contacting support. examples: - req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6 additionalProperties: true securitySchemes: WorkspaceAuth: type: http scheme: bearer bearerFormat: vq_ws_* description: 'Workspace credential issued from the automation console at `/automation`. Send it as `Authorization: Bearer vq_ws_...`. This is NOT a Data API key: a `vq_key_` credential is refused here and names the other product in the error.' externalDocs: description: Getting started guide and error reference url: https://vaquill.ai/docs/workspace-api x-refined-from: - vaquill-ai-workspace-openapi.json - vaquill-ai-workspace-openapi.yml