> ## Documentation Index > Fetch the complete documentation index at: https://docs.flightlinehq.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Review > Create a review and ingest its documents in one call. Accepts either ``multipart/form-data`` (file uploads) or ``application/json`` (documents referenced by signed source URL). Send an optional ``Idempotency-Key`` header to make the create safely retryable: resending the SAME request with the SAME key returns the ORIGINAL review (HTTP 200) instead of creating a duplicate (which would re-run the expensive pipeline). Keys are scoped to the caller's org. ## OpenAPI ````yaml /api-reference/openapi.json post /reviews openapi: 3.1.0 info: description: >- Submit loan packages for automated quality-control review and retrieve results. Authenticate every request with your organization's API key: `Authorization: Bearer `. title: Flightline Public API version: '2026-05-30' servers: - url: https://api.flightlinehq.com/v1 security: [] paths: /reviews: post: tags: - reviews summary: Create Review description: |- Create a review and ingest its documents in one call. Accepts either ``multipart/form-data`` (file uploads) or ``application/json`` (documents referenced by signed source URL). Send an optional ``Idempotency-Key`` header to make the create safely retryable: resending the SAME request with the SAME key returns the ORIGINAL review (HTTP 200) instead of creating a duplicate (which would re-run the expensive pipeline). Keys are scoped to the caller's org. operationId: create_review_reviews_post parameters: - description: >- Optional. A unique key (at most 255 characters) you choose for this create request. Resending the same request with the same key returns the ORIGINAL review (HTTP 200) instead of creating a duplicate, so the review pipeline runs exactly once. Keys are scoped to your organization. Distinct from 'reference_id', which rejects a duplicate with 409 rather than replaying. in: header name: Idempotency-Key required: false schema: anyOf: - type: string - type: 'null' description: >- Optional. A unique key (at most 255 characters) you choose for this create request. Resending the same request with the same key returns the ORIGINAL review (HTTP 200) instead of creating a duplicate, so the review pipeline runs exactly once. Keys are scoped to your organization. Distinct from 'reference_id', which rejects a duplicate with 409 rather than replaying. title: Idempotency-Key - in: header name: authorization required: false schema: anyOf: - type: string - type: 'null' title: Authorization - in: header name: X-Api-Key required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: content: application/json: example: documents: - content_type: application/zip filename: full-case.zip url: https://files.example.com/signed/full-case.zip?sig=abc123 label: Smith refinance metadata: branch: austin loan_officer: jsmith reference_id: LN-2026-04-8812 review_type: mortgage_v1 schema: $defs: DocumentSource: additionalProperties: false description: A case package or document to ingest by signed source URL. example: content_type: application/zip filename: full-case.zip url: https://files.example.com/signed/full-case.zip?sig=abc123 properties: content_type: description: >- MIME type of the package or document. Archives may be application/zip, application/x-tar, or gzip tarballs; individual documents may be PDF or common image types. examples: - application/zip maxLength: 255 minLength: 1 title: Content Type type: string filename: description: >- Original file name. Use a full case archive (.zip, .tar, .tar.gz, .tgz) or an individual PDF/image document. examples: - full-case.zip maxLength: 500 minLength: 1 title: Filename type: string url: description: >- Signed, time-limited HTTPS URL Flightline will fetch the file from. Internal, private, loopback, and metadata hosts are rejected; redirects are not followed. examples: - >- https://files.example.com/signed/full-case.zip?sig=abc123 maxLength: 4000 minLength: 1 title: Url type: string required: - filename - url - content_type title: DocumentSource type: object additionalProperties: false description: >- JSON body for ``POST /reviews`` (signed-source-URL variant). The multipart/form-data variant carries the same logical fields as form parts plus the file uploads; see ``reviews.create_review``. example: documents: - content_type: application/zip filename: full-case.zip url: https://files.example.com/signed/full-case.zip?sig=abc123 label: Smith refinance metadata: branch: austin loan_officer: jsmith reference_id: LN-2026-04-8812 review_type: mortgage_v1 properties: documents: description: Case packages or documents to ingest by signed source URL. items: 21122603-179e-4eb4-8f93-5eb52b07318c title: Documents type: array label: anyOf: - maxLength: 500 type: string - type: 'null' description: Optional human-readable label shown in the dashboard. examples: - Smith refinance title: Label metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Optional flat string->string metadata echoed back on reads. examples: - branch: austin loan_officer: jsmith title: Metadata reference_id: anyOf: - maxLength: 255 type: string - type: 'null' description: >- Your external identifier for this loan package (idempotency key). examples: - LN-2026-04-8812 title: Reference Id review_type: default: mortgage_v1 description: Review template to run (maps to an internal schema). examples: - mortgage_v1 maxLength: 100 minLength: 1 title: Review Type type: string title: CreateReviewRequest type: object multipart/form-data: encoding: documents: contentType: >- application/zip, application/x-tar, application/gzip, application/pdf, image/* schema: properties: documents: description: >- One or more case-package archives or documents. Archives may be .zip, .tar, .tar.gz, or .tgz; individual documents may be PDF or common image files. items: format: binary type: string type: array label: description: Optional human-readable label. type: string metadata: description: >- Optional flat string->string metadata, encoded as a JSON object string. type: string reference_id: description: Your external identifier (idempotency key). type: string review_type: default: mortgage_v1 description: Review template to run. type: string required: - documents type: object description: >- Create a review with either direct case-package uploads (multipart/form-data) or case packages referenced by signed source URL (application/json). required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ReviewResource' description: Successful Response '400': content: application/json: example: error: code: document_required message: At least one document is required. schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: >- No documents, malformed metadata, or an unsupported package/document. '401': content: application/json: example: error: code: missing_api_key message: 'Missing API key. Send ''Authorization: Bearer ''.' schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: Missing, invalid, or revoked API key. '409': content: application/json: example: error: code: duplicate_reference_id message: A review with reference_id 'LN-2026-04-8812' already exists. schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: >- A review with this reference_id already exists, or all documents are duplicates. '413': content: application/json: example: error: code: document_too_large message: 'File too large: full-case.zip' schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: A single document exceeds the size limit. '422': content: application/json: example: error: code: invalid_request message: 'Invalid request body. Check field(s): documents.0.url.' schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: >- Too many documents, aggregate size exceeded, or an invalid request body. '429': content: application/json: example: error: code: rate_limited message: Rate limit exceeded. Retry with exponential backoff. schema: properties: error: properties: code: description: Stable, machine-readable error code (branch on this). type: string message: description: >- Human-readable, safe explanation (do not branch on this). type: string required: - code - message type: object required: - error type: object description: Rate limit exceeded. components: schemas: ReviewResource: additionalProperties: false description: |- A review, as seen by the customer. Returned by ``POST /reviews`` (201) and ``GET /reviews/{id}``. example: created_at: '2026-05-30T17:00:00Z' document_count: 3 label: Smith refinance reference_id: LN-2026-04-8812 report_available: false review_id: 9b2c1f3a-4d5e-6789-abcd-ef0123456789 review_type: mortgage_v1 sandbox: false status: processing updated_at: '2026-05-30T17:00:05Z' properties: created_at: format: date-time title: Created At type: string document_count: default: 0 description: Number of documents ingested. title: Document Count type: integer label: anyOf: - type: string - type: 'null' title: Label reference_id: anyOf: - type: string - type: 'null' title: Reference Id report_available: default: false description: True once the report is released and retrievable. title: Report Available type: boolean review_id: description: Flightline's identifier for this review. format: uuid title: Review Id type: string review_type: title: Review Type type: string sandbox: default: false description: >- True for sandbox (test-mode) reviews: canned results, no real analysis. title: Sandbox type: boolean status: $ref: '#/components/schemas/PublicReviewStatus' updated_at: format: date-time title: Updated At type: string required: - review_id - status - review_type - created_at - updated_at title: ReviewResource type: object PublicReviewStatus: description: >- Customer-facing review lifecycle. A deliberately coarse projection of the internal ``CaseStatus``. Internal states that are not meaningful to a customer (e.g. the admin-release gate ``pending_review``, the publication-blocker state) collapse to ``processing`` so we never surface internal workflow detail or verdict-adjacent signal before the publication gate passes. enum: - queued - awaiting_documents - processing - completed - failed title: PublicReviewStatus type: string ````