> ## 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. # Search filings > Search filing documents with structured metadata filters, or omit query for advanced metadata browsing. Text queries default to recent filings (2018+ and undated); metadata-only browsing defaults to all dates. Text results are a bounded candidate window, not complete catalog coverage. Default ordering is submission date descending. Repeat the semantic request with nextCursor; tokens are bound to query, caller scope and page size and expire 24 hours after the first page. Each page reruns the live query: index, ranking and metadata changes can cause repeats or omissions. No exact total is computed. Body limit: 64 KiB. Evidence versionId is null when the indexed version is unknown; it must not be inferred from current file metadata. ## OpenAPI ````yaml /openapi.json post /filings/search 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://canary.effectiveai.app/api/v2 description: Canary security: - bearerAuth: [] paths: /filings/search: post: tags: - Filings summary: Search filings description: >- Search filing documents with structured metadata filters, or omit query for advanced metadata browsing. Text queries default to recent filings (2018+ and undated); metadata-only browsing defaults to all dates. Text results are a bounded candidate window, not complete catalog coverage. Default ordering is submission date descending. Repeat the semantic request with nextCursor; tokens are bound to query, caller scope and page size and expire 24 hours after the first page. Each page reruns the live query: index, ranking and metadata changes can cause repeats or omissions. No exact total is computed. Body limit: 64 KiB. Evidence versionId is null when the indexed version is unknown; it must not be inferred from current file metadata. operationId: searchFilings requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2FilingSearchRequest' responses: '200': description: Matching filings and optional evidence. content: application/json: schema: $ref: '#/components/schemas/V2FilingSearchResponse' '400': description: Invalid request or cursor; restart traversal for invalid_cursor. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: The caller cannot view filings. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '413': description: Request exceeds 64 KiB. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: Use application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: Unexpected search failure. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: >- Search dependency unavailable or timed out. Respect Retry-After (seconds); narrow expensive queries before retrying. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2FilingSearchRequest: type: object properties: query: type: string minLength: 1 maxLength: 4000 description: >- Keyword search over filing documents. Omit for metadata-only browsing. Quoted phrases without a narrowing metadata filter fall back to keyword search, matching API v1. filters: type: array items: $ref: '#/components/schemas/V2FilingFilter' maxItems: 50 description: >- Filters combine with AND. Values in an in/containsAny filter combine with OR. Dates are inclusive. TOI, SubTOI, outcome and filing type use normalized values. sort: type: array items: type: object properties: field: type: string enum: - relevance - submissionDate - dispositionDate - stateStatusChangedDate - companyName - state - trackingNumber direction: type: string enum: - asc - desc required: - field - direction additionalProperties: false minItems: 1 maxItems: 3 description: >- Default: submissionDate descending, matching API v1. Specify relevance descending for relevance ordering. Metadata sorting of text results applies within the retrieved candidate window. includePassages: type: boolean description: >- Request matching text passages. Omit to use the configured default; false skips passages but may still return matching document IDs and names. True uses a bounded window of 100 candidate documents; false or omitted permits up to 1,200. Passages and page numbers may be unavailable. Has no effect when browsing without a query. dataScope: type: string enum: - recent - historical - all description: >- Text queries default to recent (2018+ and undated); metadata-only requests default to all. limit: type: integer minimum: 1 maximum: 200 default: 50 cursor: type: string minLength: 1 maxLength: 128 additionalProperties: false V2FilingSearchResponse: type: object properties: filings: type: array items: allOf: - $ref: '#/components/schemas/V2FilingSummary' - type: object properties: businessType: type: string nullable: true description: type: string nullable: true normalizedOutcome: type: string nullable: true filingTypeNormalized: type: string nullable: true stateStatusChangedDate: type: string nullable: true format: date matches: type: array items: type: object properties: fileId: type: string format: uuid versionId: type: string nullable: true description: >- Null: the search backend does not establish the immutable version used for this evidence. Never assume current download bytes match the passage. name: type: string nullable: true passages: type: array items: type: object properties: text: type: string pageStart: type: number nullable: true pageEnd: type: number nullable: true required: - text - pageStart - pageEnd required: - fileId - versionId - name - passages description: >- Present for text queries; passages depend on includePassages and the configured default. Only matches for this filing are included. required: - businessType - description - normalizedOutcome - filingTypeNormalized - stateStatusChangedDate nextCursor: type: string nullable: true description: >- Null when the available result window is exhausted; text search may have additional corpus matches. exhaustive: type: boolean description: >- False for bounded text search; true for metadata browsing. No exact corpus total is computed. required: - filings - nextCursor - exhaustive 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. required: - code V2FilingFilter: anyOf: - type: object properties: field: type: string enum: - state operator: type: string enum: - eq value: type: string pattern: ^[a-zA-Z]{2}$ description: Two-letter US state or territory code. required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - state operator: type: string enum: - in values: type: array items: type: string pattern: ^[a-zA-Z]{2}$ description: Two-letter US state or territory code. minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - companyName operator: type: string enum: - eq value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - companyName operator: type: string enum: - in values: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - groupId operator: type: string enum: - eq value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - businessType operator: type: string enum: - eq value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - businessType operator: type: string enum: - in values: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - productName operator: type: string enum: - eq value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - productName operator: type: string enum: - in values: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - toiCode operator: type: string enum: - eq value: type: string pattern: ^\d{2}\.\d$ description: Normalized TOI code, for example 04.0. required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - toiCode operator: type: string enum: - in values: type: array items: type: string pattern: ^\d{2}\.\d$ description: Normalized TOI code, for example 04.0. minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - subToiCode operator: type: string enum: - eq value: type: string pattern: ^\d{2}\.\d{4}$ description: Normalized SubTOI code, for example 04.0000. required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - subToiCode operator: type: string enum: - in values: type: array items: type: string pattern: ^\d{2}\.\d{4}$ description: Normalized SubTOI code, for example 04.0000. minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - normalizedOutcome operator: type: string enum: - eq value: type: string enum: - APPROVED - FILED - ACKNOWLEDGED - INFORMATIONAL - REJECTED - WITHDRAWN - PENDING - UNKNOWN required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - normalizedOutcome operator: type: string enum: - in values: type: array items: type: string enum: - APPROVED - FILED - ACKNOWLEDGED - INFORMATIONAL - REJECTED - WITHDRAWN - PENDING - UNKNOWN minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - filingTypeNormalized operator: type: string enum: - eq value: type: string enum: - FORM - RATE - RULE - RATE_RULE - FORM_RATE - FORM_RULE - FORM_RATE_RULE - ENDORSEMENT - LOSS_COST - ADVERTISING - CERTIFICATION - CONTRACT - CONSENT_TO_RATE - DEVIATIONS - INFORMATIONAL - NEW_PROGRAM - REPORT - SERVICE_CONTRACT - UNDERWRITING_GUIDE - ANNUAL_FORMS_LIST - MANUSCRIPT - POLICY_FORM - PREDICTIVE_MODEL - ORGANIZATION_ADOPTION - OTHER required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - filingTypeNormalized operator: type: string enum: - in values: type: array items: type: string enum: - FORM - RATE - RULE - RATE_RULE - FORM_RATE - FORM_RULE - FORM_RATE_RULE - ENDORSEMENT - LOSS_COST - ADVERTISING - CERTIFICATION - CONTRACT - CONSENT_TO_RATE - DEVIATIONS - INFORMATIONAL - NEW_PROGRAM - REPORT - SERVICE_CONTRACT - UNDERWRITING_GUIDE - ANNUAL_FORMS_LIST - MANUSCRIPT - POLICY_FORM - PREDICTIVE_MODEL - ORGANIZATION_ADOPTION - OTHER minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - trackingNumber operator: type: string enum: - eq value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - trackingNumber operator: type: string enum: - in values: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - companyName - productName operator: type: string enum: - contains value: type: string minLength: 1 maxLength: 500 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - carrierIds operator: type: string enum: - containsAny - notContainsAny values: type: array items: type: string minLength: 1 maxLength: 500 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - submissionDate - dispositionDate - stateStatusChangedDate operator: type: string enum: - eq - gte - lte value: type: string format: date required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - submissionDate - dispositionDate - stateStatusChangedDate operator: type: string enum: - between from: type: string format: date to: type: string format: date required: - field - operator - from - to additionalProperties: false V2FilingSummary: type: object properties: id: type: string format: uuid source: type: string sourceReference: type: string state: type: string companyName: type: string nullable: true carrierIds: type: array nullable: true items: type: string groupId: type: string nullable: true productName: type: string nullable: true typeOfInsurance: type: string nullable: true subTypeOfInsurance: type: string nullable: true toiCode: type: string nullable: true subToiCode: type: string nullable: true filingType: type: string nullable: true sourceStatus: type: string nullable: true submissionDate: type: string nullable: true format: date dispositionDate: type: string nullable: true format: date required: - id - source - sourceReference - state - companyName - carrierIds - groupId - productName - typeOfInsurance - subTypeOfInsurance - toiCode - subToiCode - filingType - sourceStatus - submissionDate - dispositionDate V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error 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.