> ## 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. # Get a form comparison > Not implemented yet: returns 501 until the implementation ships. Read a comparison: queued or running while the agent works, then succeeded with result, inputsUsed, redactedCitationCount and usage, or failed with failure (code, error, retryable). Succeeded and failed never change. result.report is Markdown rendered from the structured fields. Citations to files you can no longer read or download are removed on each read and counted in redactedCitationCount. usage.credits may rise as delayed charges arrive. Free; poll every few seconds. ## OpenAPI ````yaml /openapi.json get /insurance/form-comparisons/{id} 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/{id}: get: tags: - Form comparisons summary: Get a form comparison description: >- Not implemented yet: returns 501 until the implementation ships. Read a comparison: queued or running while the agent works, then succeeded with result, inputsUsed, redactedCitationCount and usage, or failed with failure (code, error, retryable). Succeeded and failed never change. result.report is Markdown rendered from the structured fields. Citations to files you can no longer read or download are removed on each read and counted in redactedCitationCount. usage.credits may rise as delayed charges arrive. Free; poll every few seconds. operationId: getFormComparison parameters: - schema: type: string description: Form comparison UUID returned by createFormComparison. required: true description: Form comparison UUID returned by createFormComparison. name: id in: path responses: '200': description: Current representation for its status. content: application/json: schema: $ref: '#/components/schemas/V2FormComparison' '400': description: 'invalid_request: unknown query parameter.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: 'unauthenticated: valid credentials are required.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: >- feature_not_enabled: the organization does not have form comparisons. forbidden: the credential cannot use form comparisons (app-scoped and delegated credentials cannot). content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: >- not_found: no comparison with this ID in your organization, or it was deleted. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: 'internal_error: unexpected server error.' content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '501': description: >- not_implemented: the contract is published ahead of its implementation. 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: 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 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: >- When the Idempotency-Key binding expires (7 days after acceptance); null without a key. status: type: string enum: - queued description: Accepted; the agent has not started. required: - id - createdAt - idempotencyExpiresAt - 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: >- When the Idempotency-Key binding expires (7 days after acceptance); null without a key. status: type: string enum: - running description: >- The agent is working. A comparison unfinished 30 minutes after launch fails. required: - id - createdAt - idempotencyExpiresAt - 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: >- When the Idempotency-Key binding expires (7 days after acceptance); null without a key. status: type: string enum: - succeeded description: A verified result was accepted; terminal. result: $ref: '#/components/schemas/V2FormComparisonResult' inputsUsed: $ref: '#/components/schemas/V2FormComparisonInputsUsed' redactedCitationCount: type: integer minimum: 0 description: >- Document references removed from this read because you can no longer read or download their file. usage: type: object properties: credits: type: number minimum: 0 description: >- Recorded session usage in credits; may rise as delayed charges arrive. required: - credits description: Current recorded usage. required: - id - createdAt - idempotencyExpiresAt - 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: >- When the Idempotency-Key binding expires (7 days after acceptance); null without a key. status: type: string enum: - failed description: The run ended without an accepted result; terminal. failure: type: object properties: code: type: string description: >- run_failed: could not be launched. execution_timeout: no result within 30 minutes of launch. unable_to_compare: the agent reported that the inputs cannot be compared; error gives its reason. Tolerate future codes. error: type: string description: Human-readable explanation. retryable: type: boolean description: >- Whether a new comparison with the same input (and a new key) may succeed. required: - code - error - retryable required: - id - createdAt - idempotencyExpiresAt - status - failure V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error V2FormComparisonResult: type: object properties: summary: type: object properties: text: type: string findingIds: type: array items: type: string description: IDs of findings 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/V2FormComparisonReference' 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 of findings in result.findings. referenceIds: type: array items: type: string description: IDs of entries in result.references; every ID resolves. required: - annotationId - status - text - findingIds - referenceIds description: One per supplied annotation. report: type: string description: >- Markdown rendered by the server from the fields above; it never reruns interpretation. required: - summary - findings - scenarios - gaps - references - annotationResponses - report description: >- Lists are empty arrays, never null. IDs are stable within this comparison. 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 and request-wide 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: >- sha256: of the pinned version; null for files without version history. name: type: string extractionMethod: type: string nullable: true description: How the text was extracted; null when 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: Directory snapshot used, or the inline values. 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: What this run read, for audit. V2FormComparisonFinding: type: object properties: id: type: string description: Finding ID, stable within this comparison. finding: type: string description: Short title naming what is being compared. comparison: type: string enum: - different - aligned - unresolved description: >- different, aligned or unresolved, scoped to the finding and the 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 of entries in result.references; every ID resolves. required: - variant - text - referenceIds description: >- One position per variant, in request variant order where the agent kept it. interpretation: type: object properties: text: type: string referenceIds: type: array items: type: string description: IDs of entries in result.references; every ID resolves. required: - text - referenceIds description: What the comparison means in practice. gapIds: type: array items: type: string description: IDs of gaps 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: The scenario 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: IDs of this scenario’s propositions the check relies on. status: type: string enum: - met - not_met - undetermined explanation: type: string referenceIds: type: array items: type: string description: IDs of entries in result.references; every ID resolves. required: - expectationId - variant - propositionIds - status - explanation - referenceIds description: One per expectation and variant it applies to. required: - id - question - propositions - expectationChecks V2FormComparisonGap: type: object properties: id: type: string description: Gap ID, stable within this comparison. 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: Findings, scenarios, annotations or inputs the gap affects. required: - id - text - limits - needed - affected V2FormComparisonReference: oneOf: - $ref: '#/components/schemas/V2FormComparisonDocumentReference' - $ref: '#/components/schemas/V2FormComparisonKnowledgeReference' - $ref: '#/components/schemas/V2FormComparisonAnnotationReference' discriminator: propertyName: type mapping: document: '#/components/schemas/V2FormComparisonDocumentReference' knowledge: '#/components/schemas/V2FormComparisonKnowledgeReference' annotation: '#/components/schemas/V2FormComparisonAnnotationReference' V2FormComparisonProposition: type: object properties: id: type: string description: Proposition ID, stable within this comparison. text: type: string description: One proposition split 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 is undetermined, never not_supported. text: type: string referenceIds: type: array items: type: string description: IDs of entries in result.references; every ID resolves. findingIds: type: array items: type: string description: IDs of findings in result.findings. gapIds: type: array items: type: string description: IDs of gaps 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: Input the citation belongs to, keeping its role. scope: type: string enum: - passage - document description: >- passage: page and quote support the statement. document: a "not found in this document" statement about the whole input, with a null page and an empty quote. fileId: type: string description: Cited file UUID. versionId: anyOf: - type: string format: uuid - type: string maxLength: 8192 pattern: ^lv1\.[A-Za-z0-9_.-]+$ description: >- File version pinned when the comparison was accepted: UUID or opaque lv1. token. page: type: integer nullable: true minimum: 1 description: One-based extracted page, or null. quote: type: string description: >- The matched source passage when verified; otherwise an opening excerpt of the cited page, or empty. verified: type: boolean description: >- True when the quote matched the extracted text at the cited page of the pinned version. downloadUrl: type: string description: >- Authenticated API-relative path: /api/v2/files/{fileId}/download?versionId=... webUrl: type: string format: uri description: Effective file viewer for the cited file, at the cited page. required: - id - type - inputId - scope - fileId - versionId - page - quote - verified - downloadUrl - webUrl V2FormComparisonKnowledgeReference: type: object properties: id: type: string type: type: string enum: - knowledge inputId: type: string entryId: type: string description: Full knowledge entry ID, namespace:local-id. required: - id - type - inputId - entryId description: Reasoning context from a knowledge file, not form 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: 'A caller annotation: a claim, not evidence.' 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.