fastcrw-com Extract API

openapi: 3.2.0
info:
  title: CRW REST Extract API
  version: 0.39.1
  description: Firecrawl-compatible web scraping, crawling, mapping, search, and extraction API. Hosted at https://api.fastcrw.com; self-host with `docker run -p 3000:3000 ghcr.io/fastcrw/crw:latest`.
  license:
    name: AGPL-3.0
    url: https://opensource.org/licenses/AGPL-3.0
  contact:
    url: https://github.com/fastcrw/crw
servers:
- url: https://api.fastcrw.com
  description: Hosted (requires Bearer token)
- url: http://localhost:3000
  description: Self-hosted (no auth by default)
security:
- bearerAuth: []
- {}
tags:
- name: Extract
  description: Structured JSON extraction via scrape + jsonOptions
paths:
  /v1/extract:
    post:
      tags:
      - Extract
      summary: Start an async multi-URL structured extraction job
      description: 'Native extraction. Returns a fixed-cardinality per-URL array via GET /v1/extract/{id}. At least one of `prompt` or `schema` is required. SDK async starters send `Prefer: respond-async` for managed/self-hosted parity.'
      operationId: extractStart
      parameters:
      - name: Prefer
        in: header
        required: false
        schema:
          type: string
          enum:
          - respond-async
        description: Request the canonical async lifecycle across managed and self-hosted deployments.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
      responses:
        '200':
          description: Extract job accepted; poll with /v1/extract/{id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v1/extract/{id}:
    get:
      tags:
      - Extract
      summary: Get extract job status and per-URL results
      operationId: extractStatus
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Extract job id returned by POST /v1/extract
      responses:
        '200':
          description: Job status + per-URL extraction results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Extract
      summary: Cancel an extract job
      description: Idempotent. Processing becomes cancelling while a claimed URL settles, then cancelled. Completed, failed, and cancelled states are immutable.
      operationId: extractCancel
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Extract job id returned by POST /v1/extract
      responses:
        '200':
          description: Canonical job status + ordered per-URL results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Basis:
      type: object
      required:
      - basisVersion
      - field
      - value
      - status
      - citations
      description: Per-field extraction evidence. Emitted only for top-level scalar schema properties, and only when the request set basis:true. citations is empty exactly when status is 'unsupported' or 'notFound'; value is null exactly when status is 'notFound'.
      properties:
        basisVersion:
          type: integer
        field:
          type: string
        value:
          description: The schema-validated value; null when status is 'notFound'. Never rewritten to the model's claim.
        status:
          $ref: '#/components/schemas/FieldStatus'
        confidence:
          type: string
          enum:
          - low
          - medium
          - high
        citations:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceCitation'
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message
        errorCode:
          type: string
          description: Machine-readable error code (see docs/error-codes.md)
    ExtractUrlResult:
      type: object
      required:
      - url
      - status
      properties:
        url:
          type: string
        status:
          type: string
          enum:
          - processing
          - completed
          - failed
          - cancelled
        data:
          type: object
          additionalProperties: true
          description: Extracted JSON object (present when status is completed). Untouched cancelled slots omit data, error, usage, and basis.
        error:
          type: string
        llmUsage:
          type: object
          additionalProperties: true
          description: Per-URL LLM token usage (provider/model/input/output tokens).
        basis:
          type: array
          items:
            $ref: '#/components/schemas/Basis'
          description: Per-field evidence for this URL; present only when the request set basis:true.
        basisWarnings:
          type: array
          items:
            $ref: '#/components/schemas/BasisWarning'
        llmInputHash:
          type: string
          description: '''sha256:''-prefixed hash of the canonical text sent to the extraction LLM.'
    ExtractRequest:
      type: object
      required:
      - urls
      description: At least one of `prompt` or `schema` must be present.
      properties:
        urls:
          type: array
          items:
            type: string
            format: uri
          description: URLs to extract from (1..crawler.max_extract_urls).
        prompt:
          type: string
          description: Free-text extraction objective.
        schema:
          type: object
          additionalProperties: true
          description: JSON Schema constraining the extracted output.
        llmApiKey:
          type: string
          description: BYOK LLM API key.
        llmProvider:
          type: string
        llmModel:
          type: string
        basis:
          type: boolean
          description: 'Return per-field evidence: each result carries a ''basis'' array, one entry per top-level scalar schema property. Requires ''schema''. Reported by GET /v1/capabilities (extract.perFieldAttribution).'
    ExtractAccepted:
      type: object
      required:
      - success
      - id
      - status
      - urls
      properties:
        success:
          type: boolean
        id:
          type: string
        status:
          type: string
          enum:
          - processing
        urls:
          type: integer
          description: Count of URLs enqueued for fetch (preflight-failed URLs appear in results, not here).
    EvidenceCitation:
      type: object
      required:
      - url
      - sourceHash
      - sourceTextKind
      description: A citation backing an extracted value. Every field is server-produced; never a model-supplied url, hash or excerpt.
      properties:
        url:
          type: string
          description: The document the engine fetched.
        title:
          type: string
        excerpt:
          type: string
          description: Verbatim span from the canonical source text. Absent when the span could not be established (status 'unverified').
        sourceHash:
          type: string
          description: '''sha256:<hex>'' of the exact text sent to the model.'
        sourceTextKind:
          type: string
          description: Which text sourceHash covers. 'llmInput' for extraction basis (the truncated markdown sent to the model).
    ExtractStatus:
      type: object
      required:
      - success
      - id
      - status
      - results
      - expiresAt
      - creditsUsed
      - tokensUsed
      properties:
        success:
          type: boolean
        id:
          type: string
        status:
          type: string
          enum:
          - processing
          - cancelling
          - completed
          - failed
          - cancelled
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExtractUrlResult'
          description: Fixed-cardinality per-URL slots in original request order. Pending slots are processing; untouched terminal slots are cancelled.
        error:
          type: string
          description: Job-level error, set only when every URL failed.
        expiresAt:
          type: string
          format: date-time
        creditsUsed:
          type: integer
        tokensUsed:
          type: integer
    FieldStatus:
      type: string
      enum:
      - supported
      - unverified
      - unsupported
      - notFound
      description: 'How well an extracted field is attributed to its source. Honest: a field whose attribution could not be verified is ''unverified''/''unsupported'' rather than given a fabricated citation.'
    BasisWarning:
      type: object
      required:
      - field
      - code
      description: A coded reason a field's attribution was downgraded. Closed, crw-owned code set; never upstream text.
      properties:
        field:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Hosted only. Get a key at https://fastcrw.com/register.