> ## Documentation Index > Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Request a form comparison > Compare two to eight versions of insurance wording with citations. The wording of each version is files, a form, or both: form is a Form record edition, catalogForm a form a catalog product records in a state (see getProductAvailabilityForms). Inputs must be readable, downloadable files with extracted text; current versions are pinned. Optional knowledge files are validated automatically. Poll the returned id or use form_comparison.completed / form_comparison.failed webhooks. Runs time out after 1 hour and use session credits. Requires the form comparisons feature and a member with write access. Use Idempotency-Key for safe retries (7 days); without it, each POST starts a run. Maximum: 20 inputs, 50 annotations, 64 KiB. ## OpenAPI ````yaml /openapi.json post /insurance/form-comparisons openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://api.canary.effectiveai.app/api/v2 description: Canary security: - bearerAuth: [] paths: /insurance/form-comparisons: post: tags: - Form comparisons summary: Request a form comparison description: >- Compare two to eight versions of insurance wording with citations. The wording of each version is files, a form, or both: form is a Form record edition, catalogForm a form a catalog product records in a state (see getProductAvailabilityForms). Inputs must be readable, downloadable files with extracted text; current versions are pinned. Optional knowledge files are validated automatically. Poll the returned id or use form_comparison.completed / form_comparison.failed webhooks. Runs time out after 1 hour and use session credits. Requires the form comparisons feature and a member with write access. Use Idempotency-Key for safe retries (7 days); without it, each POST starts a run. Maximum: 20 inputs, 50 annotations, 64 KiB. operationId: createFormComparison parameters: - schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9\-_.:]+$ description: >- Client-chosen key for safe retries: 1-128 letters, digits, -, _, . or :. Use a new random UUID for each intended operation and the same key when retrying it. Do not put customer data or credentials in the key. required: false description: >- Client-chosen key for safe retries: 1-128 letters, digits, -, _, . or :. Use a new random UUID for each intended operation and the same key when retrying it. Do not put customer data or credentials in the key. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2CreateFormComparisonRequest' responses: '200': description: Completed comparison returned by an idempotent retry. headers: Location: required: true schema: type: string description: Poll this path for results. content: application/json: schema: $ref: '#/components/schemas/V2FormComparison' '202': description: Queued or running comparison. headers: Location: required: true schema: type: string description: Poll this path for results. content: application/json: schema: $ref: '#/components/schemas/V2FormComparison' '400': description: 'invalid_request: invalid inputs or key. See details.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: 'unauthenticated: credentials required.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: >- feature_not_enabled, download_restricted, product_access_required, or forbidden: feature, file, a catalog form's product in its state, or write access denied. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: >- not_found: input or form missing/inaccessible, or the retried comparison was deleted. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '409': description: >- idempotency_conflict: key reused with different inputs. input_not_ready: retry after Retry-After. version_unavailable: file version could not be pinned. headers: Retry-After: required: false schema: type: integer minimum: 0 description: Seconds to wait before retrying, for input_not_ready. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '413': description: 'request_too_large: the request exceeds 64 KiB.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: 'unsupported_media_type: use application/json.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '422': description: >- input_unreadable: file has no extracted text; scanned PDFs require OCR before upload. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '429': description: 'cost_control_enforced: a cost-control policy blocks new runs.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: 'internal_error: unexpected server error.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: 'temporarily_unavailable: retry after Retry-After seconds.' headers: Retry-After: required: true schema: type: integer minimum: 0 description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2CreateFormComparisonRequest: type: object properties: variants: type: array items: $ref: '#/components/schemas/V2FormComparisonVariant' minItems: 2 maxItems: 8 description: Two to eight versions to compare, in display order. sharedContext: allOf: - $ref: '#/components/schemas/V2FormComparisonContext' - description: Context for all variants. Conflicts are reported as gaps. knowledge: type: array items: $ref: '#/components/schemas/V2FormComparisonInput' maxItems: 10 description: >- Knowledge files: reasoning context, not policy evidence. Must pass validateFormKnowledge. focus: type: array items: type: string minLength: 1 maxLength: 1000 maxItems: 10 description: >- Questions to focus on. Omit for material similarities and differences. scenarios: type: array items: $ref: '#/components/schemas/V2FormComparisonScenario' maxItems: 10 description: Hypothetical scenarios to assess for each variant. reviewMaterial: type: array items: $ref: '#/components/schemas/V2FormComparisonInput' maxItems: 10 description: Earlier results or reviewer notes to reconcile; not policy evidence. required: - variants additionalProperties: false V2FormComparison: oneOf: - $ref: '#/components/schemas/V2QueuedFormComparison' - $ref: '#/components/schemas/V2RunningFormComparison' - $ref: '#/components/schemas/V2SucceededFormComparison' - $ref: '#/components/schemas/V2FailedFormComparison' discriminator: propertyName: status mapping: queued: '#/components/schemas/V2QueuedFormComparison' running: '#/components/schemas/V2RunningFormComparison' succeeded: '#/components/schemas/V2SucceededFormComparison' failed: '#/components/schemas/V2FailedFormComparison' V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. dataset: type: string enum: - naic - osha description: Dataset needed for dataset_not_enabled. businessCode: type: string description: The rater’s own refusal code, for business_rejection. violations: type: array items: type: object properties: code: type: string description: Authored or built-in constraint code message: type: string description: Authored message for the failed constraint path: type: string description: Input path of the offending value; empty for the request value: nullable: true description: Offending input value, size-bounded by the runtime constraint: type: string description: The constraint the value failed, as text cite: type: string nullable: true description: >- Filing citation of the constraint, when the source cites one required: - code - message - path - value - constraint - cite additionalProperties: false maxItems: 256 description: >- Each input constraint the submission failed, for invalid_inputs and business_rejection. violationsTruncated: type: boolean description: >- True when the rater reported more violations than violations holds. accessUrl: type: string nullable: true format: uri description: >- Where to add the product to your account, for product_access_required. required: - code V2FormComparisonVariant: type: object properties: key: type: string pattern: ^[a-z][a-z0-9_-]{0,39}$ description: >- Unique variant key: lowercase letter, then up to 39 lowercase letters, digits, - or _. example: verus label: type: string minLength: 1 maxLength: 200 description: Display label. documents: type: array items: $ref: '#/components/schemas/V2FormComparisonInput' maxItems: 10 description: >- Forms containing this version of the wording. Required unless form or catalogForm is given; with one, they come before its files. form: $ref: '#/components/schemas/V2FormComparisonFormReference' catalogForm: $ref: '#/components/schemas/V2FormComparisonCatalogFormReference' context: $ref: '#/components/schemas/V2FormComparisonContext' required: - key additionalProperties: false V2FormComparisonContext: type: object properties: product: anyOf: - $ref: '#/components/schemas/V2AnswerProductScope' - $ref: '#/components/schemas/V2FormComparisonInlineProduct' description: >- Directory product { id, state? } or inline description. Adds context, not forms or approval. documents: type: array items: $ref: '#/components/schemas/V2FormComparisonInput' maxItems: 10 description: Supporting documents, such as a base policy or declarations. facts: type: string minLength: 1 maxLength: 4000 description: Relevant facts. additionalProperties: false description: Context for this variant only. V2FormComparisonInput: anyOf: - type: string format: uuid description: File UUID. example: 01a150b0-b6a4-774f-a0e0-ad385dbc5028 - $ref: '#/components/schemas/V2FormComparisonInputObject' description: >- File UUID or an object with an ID and optional label/annotations. Bare UUIDs receive input- IDs in request order. V2FormComparisonScenario: type: object properties: id: type: string pattern: ^[a-z][a-z0-9_-]{0,63}$ description: Scenario ID, unique in the request. example: water-backup facts: type: string minLength: 1 maxLength: 4000 description: Hypothetical facts. question: type: string minLength: 1 maxLength: 1000 description: Question to answer for each variant. expectations: type: array items: type: object properties: id: type: string pattern: ^[a-z][a-z0-9_-]{0,63}$ description: Expectation ID, unique in the request. assertion: type: string minLength: 1 maxLength: 1000 description: Assertion to test. variant: type: string pattern: ^[a-z][a-z0-9_-]{0,39}$ description: Variant key; omit to test all variants. required: - id - assertion additionalProperties: false maxItems: 10 description: Assertions to test separately. required: - id - facts - question additionalProperties: false V2QueuedFormComparison: type: object properties: id: type: string description: Form comparison UUID. createdAt: type: string format: date-time description: When the comparison was accepted. idempotencyExpiresAt: type: string nullable: true format: date-time description: Key expiry (7 days); null without a key. request: $ref: '#/components/schemas/V2FormComparisonSubmittedRequest' status: type: string enum: - queued description: Waiting to start. required: - id - createdAt - idempotencyExpiresAt - request - status V2RunningFormComparison: type: object properties: id: type: string description: Form comparison UUID. createdAt: type: string format: date-time description: When the comparison was accepted. idempotencyExpiresAt: type: string nullable: true format: date-time description: Key expiry (7 days); null without a key. request: $ref: '#/components/schemas/V2FormComparisonSubmittedRequest' status: type: string enum: - running description: In progress; times out after 1 hour. required: - id - createdAt - idempotencyExpiresAt - request - status V2SucceededFormComparison: type: object properties: id: type: string description: Form comparison UUID. createdAt: type: string format: date-time description: When the comparison was accepted. idempotencyExpiresAt: type: string nullable: true format: date-time description: Key expiry (7 days); null without a key. request: $ref: '#/components/schemas/V2FormComparisonSubmittedRequest' status: type: string enum: - succeeded description: Finished with results. result: $ref: '#/components/schemas/V2FormComparisonResult' inputsUsed: $ref: '#/components/schemas/V2FormComparisonInputsUsed' redactedCitationCount: type: integer minimum: 0 description: Citations removed due to lost file access. usage: type: object properties: credits: type: number minimum: 0 description: Credits used; delayed charges may increase this. required: - credits description: Usage to date. required: - id - createdAt - idempotencyExpiresAt - request - status - result - inputsUsed - redactedCitationCount - usage V2FailedFormComparison: type: object properties: id: type: string description: Form comparison UUID. createdAt: type: string format: date-time description: When the comparison was accepted. idempotencyExpiresAt: type: string nullable: true format: date-time description: Key expiry (7 days); null without a key. request: $ref: '#/components/schemas/V2FormComparisonSubmittedRequest' status: type: string enum: - failed description: Finished without results. failure: type: object properties: code: type: string description: >- run_failed, execution_timeout, or unable_to_compare. May include future codes. error: type: string description: Human-readable explanation. retryable: type: boolean description: Whether to retry as a new comparison with a new key. required: - code - error - retryable required: - id - createdAt - idempotencyExpiresAt - request - status - failure V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error V2FormComparisonFormReference: type: object properties: scope: type: string pattern: ^mc:[A-Za-z0-9][A-Za-z0-9-]{0,127}$ description: Authorization scope UUID or stable slug prefixed with mc:. example: mc:verus editionId: type: string format: uuid description: Form edition record ID; normalized to lowercase. example: 01a150b0-b6a4-774f-a0e0-ad385dbc5029 required: - scope - editionId additionalProperties: false description: >- A Form record edition whose files hold this version's wording. Its files are added after the variant's documents, as inputs -form-, and count toward the document limits. Requires read access to the edition and its files. V2FormComparisonCatalogFormReference: type: object properties: productId: type: string minLength: 1 description: >- Catalog product ID, e.g. product_00001AB or bare code 00001AB. Aliases normalize to the full ID. example: product_00001AB state: type: string pattern: ^[A-Z]{2}$ description: Two-letter uppercase state code, e.g. TX. example: TX formNumber: type: string minLength: 1 maxLength: 100 description: >- Form number exactly as getProductAvailabilityForms lists it; letter case and spacing are ignored. example: HO 00 03 edition: type: string nullable: true pattern: ^\d{4}-(0[1-9]|1[0-2])$ description: >- Edition (YYYY-MM) as listed; null for an entry without one. Omit when the form has one edition in the state. example: 2011-05 required: - productId - state - formNumber additionalProperties: false description: >- A form a Market Directory product records in one state, as getProductAvailabilityForms lists it, whose files hold this version's wording. The matching entries' files are added after the variant's documents, as inputs -form-, and count toward the document limits. Requires access to the product in that state. V2AnswerProductScope: type: object properties: id: type: string minLength: 1 description: >- Catalog product ID, e.g. product_00001AB or bare code 00001AB. Aliases normalize to the full ID. example: product_00001AB state: type: string pattern: ^[A-Z]{2}$ description: >- Two-letter uppercase state code, e.g. CA for California. Omit to include all states for this product. example: CA required: - id additionalProperties: false V2FormComparisonInlineProduct: type: object properties: label: type: string minLength: 1 maxLength: 200 description: Product name. description: type: string minLength: 1 maxLength: 4000 description: Product description. jurisdiction: type: string minLength: 1 maxLength: 100 description: Jurisdiction, e.g. TX. effectiveDate: type: string format: date description: ISO date, e.g. 2026-01-01. required: - label additionalProperties: false description: Inline product context. V2FormComparisonInputObject: type: object properties: id: type: string pattern: ^[a-z][a-z0-9_-]{0,63}$ description: >- Unique input ID: lowercase letter, then up to 63 lowercase letters, digits, - or _. example: verus-base fileId: type: string format: uuid description: File UUID. example: 01a150b0-b6a4-774f-a0e0-ad385dbc5028 label: type: string minLength: 1 maxLength: 200 description: Display label. annotations: type: array items: $ref: '#/components/schemas/V2FormComparisonAnnotation' maxItems: 50 description: Reviewer notes; sources stay unchanged. required: - id - fileId additionalProperties: false V2FormComparisonSubmittedRequest: type: object properties: variants: type: array items: type: object properties: key: type: string label: type: string nullable: true documents: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: The wording compared, in order. form: $ref: '#/components/schemas/V2FormComparisonSubmittedForm' catalogForm: $ref: '#/components/schemas/V2FormComparisonSubmittedCatalogForm' context: $ref: '#/components/schemas/V2FormComparisonSubmittedContext' required: - key - label - documents - form - catalogForm - context description: Variants in request order. sharedContext: $ref: '#/components/schemas/V2FormComparisonSubmittedContext' focus: type: array items: type: string description: Focus questions, in request order. scenarios: type: array items: type: object properties: id: type: string facts: type: string question: type: string expectations: type: array items: type: object properties: id: type: string assertion: type: string variant: type: string nullable: true description: Variant key; null for all variants. required: - id - assertion - variant required: - id - facts - question - expectations description: Scenarios, in request order. knowledge: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: Knowledge files, in request order. reviewMaterial: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: Review material, in request order. required: - variants - sharedContext - focus - scenarios - knowledge - reviewMaterial description: Submitted request. Pinned versions appear in inputsUsed. V2FormComparisonResult: type: object properties: summary: type: object properties: text: type: string findingIds: type: array items: type: string description: IDs in result.findings. required: - text - findingIds findings: type: array items: $ref: '#/components/schemas/V2FormComparisonFinding' scenarios: type: array items: $ref: '#/components/schemas/V2FormComparisonScenarioResult' description: One per supplied scenario. gaps: type: array items: $ref: '#/components/schemas/V2FormComparisonGap' references: type: array items: $ref: '#/components/schemas/V2FormComparisonResultReference' annotationResponses: type: array items: type: object properties: annotationId: type: string status: type: string enum: - addressed - needs_context - target_not_found text: type: string findingIds: type: array items: type: string description: IDs in result.findings. referenceIds: type: array items: type: string description: IDs in result.references. required: - annotationId - status - text - findingIds - referenceIds description: One per supplied annotation. report: type: string description: Markdown report of these results. required: - summary - findings - scenarios - gaps - references - annotationResponses - report description: IDs are stable within this comparison. Empty lists are []. V2FormComparisonInputsUsed: type: object properties: items: type: array items: type: object properties: inputId: type: string role: type: string enum: - target - context - knowledge - review_material variant: type: string nullable: true description: Variant key; null for shared inputs. fileId: type: string versionId: anyOf: - type: string format: uuid - type: string maxLength: 8192 pattern: ^lv1\.[A-Za-z0-9_.-]+$ description: 'Pinned version: UUID or lv1. token.' contentSha256: type: string nullable: true description: Pinned SHA-256 hash; null without version history. name: type: string extractionMethod: type: string nullable: true description: Extraction method; null if unknown. required: - inputId - role - variant - fileId - versionId - contentSha256 - name - extractionMethod description: One per input. products: type: array items: type: object properties: variant: type: string nullable: true description: Variant key; null for shared context. product: anyOf: - type: object properties: type: type: string enum: - directory id: type: string name: type: string states: type: array items: type: string required: - type - id - name - states - type: object properties: type: type: string enum: - inline label: type: string description: type: string nullable: true jurisdiction: type: string nullable: true effectiveDate: type: string nullable: true required: - type - label - description - jurisdiction - effectiveDate description: Product context snapshot. required: - variant - product description: Product context per variant. execution: type: object properties: executor: type: string model: type: string nullable: true codeVersion: type: string nullable: true description: Server git SHA; null when unknown. startedAt: type: string nullable: true format: date-time finishedAt: type: string format: date-time required: - executor - model - codeVersion - startedAt - finishedAt required: - items - products - execution description: Inputs and versions used. V2FormComparisonAnnotation: type: object properties: id: type: string pattern: ^[a-z][a-z0-9_-]{0,63}$ description: >- Unique annotation ID: lowercase letter, then up to 63 lowercase letters, digits, - or _. example: note-1 kind: type: string enum: - comment - question - correction default: comment description: Corrections are checked against sources. text: type: string minLength: 1 maxLength: 2000 description: Reviewer note. target: $ref: '#/components/schemas/V2FormComparisonAnnotationTarget' required: - id - text additionalProperties: false V2FormComparisonSubmittedFile: type: object properties: inputId: type: string description: Input ID used in citations and inputsUsed. fileId: type: string description: Input file UUID. label: type: string nullable: true description: Submitted label; null if omitted. name: type: string nullable: true description: Current filename; null if inaccessible. required: - inputId - fileId - label - name V2FormComparisonSubmittedForm: type: object nullable: true properties: scope: type: string description: The scope given in the request, mc:. editionId: type: string description: Form edition record ID. formId: type: string nullable: true description: >- The edition's Form record ID; null when you can no longer read the edition or Form. formNumber: type: string nullable: true description: Form number when the comparison was requested; null as for formId. title: type: string nullable: true description: Form title when the comparison was requested; null as for formId. edition: type: string nullable: true description: Edition when the comparison was requested; null as for formId. documents: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: The edition's files the comparison used, as inputs -form-. required: - scope - editionId - formId - formNumber - title - edition - documents description: The Form record edition given as this variant; null without one. V2FormComparisonSubmittedCatalogForm: type: object nullable: true properties: productId: type: string description: The product ID given in the request. state: type: string description: The state given in the request. formNumber: type: string description: The form number given in the request. productName: type: string nullable: true description: >- Product name when the comparison was requested; null when you no longer have access to the product in this state. edition: type: string nullable: true description: >- Edition (YYYY-MM) the form resolved to; null for an entry without one, or as for productName. title: type: string nullable: true description: >- Form title when the comparison was requested; null if none, or as for productName. formType: type: string nullable: true description: >- Form type when the comparison was requested; null if none, or as for productName. documents: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: The form's files the comparison used, as inputs -form-. required: - productId - state - formNumber - productName - edition - title - formType - documents description: The catalog product form given as this variant; null without one. V2FormComparisonSubmittedContext: type: object properties: facts: type: string nullable: true description: Submitted facts; null if omitted. documents: type: array items: $ref: '#/components/schemas/V2FormComparisonSubmittedFile' description: Context documents, in request order. required: - facts - documents description: Submitted context. V2FormComparisonFinding: type: object properties: id: type: string description: Finding ID. finding: type: string description: What is being compared. comparison: type: string enum: - different - aligned - unresolved description: Comparison based on reviewed evidence. positions: type: array items: type: object properties: variant: type: string description: Variant key from the request. text: type: string referenceIds: type: array items: type: string description: IDs in result.references. required: - variant - text - referenceIds description: Position for each variant. interpretation: type: object properties: text: type: string referenceIds: type: array items: type: string description: IDs in result.references. required: - text - referenceIds description: Practical meaning. gapIds: type: array items: type: string description: IDs in result.gaps. required: - id - finding - comparison - positions - interpretation - gapIds V2FormComparisonScenarioResult: type: object properties: id: type: string description: Scenario ID from the request. question: type: string description: Question from the request. propositions: type: array items: $ref: '#/components/schemas/V2FormComparisonProposition' expectationChecks: type: array items: type: object properties: expectationId: type: string description: Expectation ID from the request. variant: type: string description: Variant key from the request. propositionIds: type: array items: type: string description: Related proposition IDs. status: type: string enum: - met - not_met - undetermined explanation: type: string referenceIds: type: array items: type: string description: IDs in result.references. required: - expectationId - variant - propositionIds - status - explanation - referenceIds description: Check per expectation and applicable variant. required: - id - question - propositions - expectationChecks V2FormComparisonGap: type: object properties: id: type: string description: Gap ID. text: type: string description: What is missing or conflicting. limits: type: string description: What conclusion the gap limits. needed: type: string description: What would resolve it. affected: type: array items: type: object properties: type: type: string enum: - finding - scenario - annotation - input id: type: string required: - type - id description: Affected findings, scenarios, annotations, or inputs. required: - id - text - limits - needed - affected V2FormComparisonResultReference: oneOf: - $ref: '#/components/schemas/V2FormComparisonDocumentReference' - $ref: '#/components/schemas/V2FormComparisonRelatedDocumentReference' - $ref: '#/components/schemas/V2FormComparisonKnowledgeReference' - $ref: '#/components/schemas/V2FormComparisonAnnotationReference' discriminator: propertyName: type mapping: document: '#/components/schemas/V2FormComparisonDocumentReference' related_document: '#/components/schemas/V2FormComparisonRelatedDocumentReference' knowledge: '#/components/schemas/V2FormComparisonKnowledgeReference' annotation: '#/components/schemas/V2FormComparisonAnnotationReference' V2FormComparisonAnnotationTarget: anyOf: - type: object properties: page: type: integer minimum: 1 description: One-based page of the document. quote: $ref: '#/components/schemas/V2FormComparisonQuoteSelector' additionalProperties: false description: A place in a document or review material, by page, quote or both. anyOf: - required: - page - required: - quote - type: object properties: entryId: type: string minLength: 1 maxLength: 200 description: Full knowledge entry ID, namespace:local-id. required: - entryId additionalProperties: false description: An entry of a knowledge file. - type: object properties: findingId: type: string minLength: 1 maxLength: 64 description: A finding ID in a saved earlier comparison. required: - findingId additionalProperties: false description: A finding of review material. description: Omit for the whole input. Unmatched targets return target_not_found. V2FormComparisonProposition: type: object properties: id: type: string description: Proposition ID. text: type: string description: One claim from the scenario question. assessments: type: array items: type: object properties: variant: type: string description: Variant key from the request. status: type: string enum: - supported - not_supported - conditional - undetermined description: Missing evidence means undetermined. text: type: string referenceIds: type: array items: type: string description: IDs in result.references. findingIds: type: array items: type: string description: IDs in result.findings. gapIds: type: array items: type: string description: IDs in result.gaps. required: - variant - status - text - referenceIds - findingIds - gapIds description: One assessment per variant. required: - id - text - assessments V2FormComparisonDocumentReference: type: object properties: id: type: string type: type: string enum: - document inputId: type: string description: Cited input ID. scope: type: string enum: - passage - document description: >- passage: cites text. document: reports an absence; page is null and quote is empty. fileId: type: string description: Cited file UUID. versionId: anyOf: - type: string format: uuid - type: string maxLength: 8192 pattern: ^lv1\.[A-Za-z0-9_.-]+$ description: 'Pinned file version: UUID or lv1. token.' page: type: integer nullable: true minimum: 1 description: One-based extracted page, or null. quote: type: string description: Matched passage if verified; otherwise a page excerpt or empty. verified: type: boolean description: Whether the quote matches the pinned page text. downloadUrl: type: string description: Authenticated download path for the pinned version. webUrl: type: string format: uri description: Link to the cited page in the file viewer. required: - id - type - inputId - scope - fileId - versionId - page - quote - verified - downloadUrl - webUrl V2FormComparisonRelatedDocumentReference: type: object properties: id: type: string type: type: string enum: - related_document variant: type: string nullable: true description: >- Variant whose context this is, or null when it bears on every variant. note: type: string description: Why the document is relevant and where it came from. fileId: type: string description: Cited file UUID. name: type: string description: The file's current name. versionId: type: string nullable: true description: >- File version read when the comparison was accepted (UUID or lv1. token), or null when it could not be read. page: type: integer nullable: true minimum: 1 description: One-based extracted page, or null. quote: type: string description: Matched passage if verified; otherwise empty. verified: type: boolean description: Whether the quote matches the page text. downloadUrl: type: string description: Authenticated download path for the version read. webUrl: type: string format: uri description: Link to the cited page in the file viewer. required: - id - type - variant - note - fileId - name - versionId - page - quote - verified - downloadUrl - webUrl description: >- A document the agent found beyond the inputs, such as a rule manual or base policy of a variant's product, cited for context. Never a variant's own wording. V2FormComparisonKnowledgeReference: type: object properties: id: type: string type: type: string enum: - knowledge inputId: type: string entryId: type: string description: 'Knowledge ID: namespace:local-id.' required: - id - type - inputId - entryId description: Knowledge context, not policy evidence. V2FormComparisonAnnotationReference: type: object properties: id: type: string type: type: string enum: - annotation inputId: type: string annotationId: type: string required: - id - type - inputId - annotationId description: Reviewer claim, not evidence. V2FormComparisonQuoteSelector: type: object properties: exact: type: string minLength: 1 maxLength: 2000 description: Exact passage to annotate. prefix: type: string minLength: 1 maxLength: 200 description: Text before the passage. suffix: type: string minLength: 1 maxLength: 200 description: Text after the passage. required: - exact additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.