openapi: 3.1.0
info:
  title: Datamint API
  summary: Production web data ingestion, anti-bot bypass, and zero-code schema extraction.
  description: >-
    Datamint provides high-reliability web crawling and structured extraction infrastructure
    designed specifically for autonomous AI agents, LLM pipelines, and automated research workflows.
    It automatically handles Chrome 133 TLS/JA4 fingerprinting, residential proxy rotation,
    CAPTCHA click-solving, and JSON Schema validation.
  version: 1.0.0
  termsOfService: https://datamint.xyz/legal/terms
  contact:
    name: Datamint Engineering & Support
    url: https://datamint.xyz/contact
    email: support@datamint.xyz
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.datamint.xyz
    description: Production Extraction Engine
  - url: https://datamint.xyz/api
    description: Datamint Frontend Proxy & Account API
security:
  - BearerAuth: []
paths:
  /v1/mint:
    post:
      summary: Mint a web page
      description: >-
        Synchronous single-page retrieval. Returns noise-free Markdown with navigation, scripts,
        and boilerplate stripped, or validated JSON if a schema is provided. Automatically ladders
        through transport tiers (Fast TLS -> Headless Browser -> Stealth Armor) based on target anti-bot countermeasures.
      operationId: mintPage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintRequest'
      responses:
        '200':
          description: Extraction completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: Insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Extraction engine unreachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/extract:
    post:
      summary: Extract structured schema
      description: >-
        Zero-code extraction into strict typed JSON conforming to either a pre-mapped canonical schema
        or an inline JSON Schema object.
      operationId: extractSchema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractRequest'
      responses:
        '200':
          description: Structured data extracted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractResponse'
        '400':
          description: Invalid schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized.
        '402':
          description: Insufficient credits.
  /v1/crawl:
    post:
      summary: Start asynchronous crawl
      description: Launches an asynchronous multi-page frontier crawl starting from a seed URL.
      operationId: startCrawl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrawlRequest'
      responses:
        '202':
          description: Crawl job accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlAcceptedResponse'
        '400':
          description: Invalid boundaries.
        '402':
          description: Insufficient credits.
    get:
      summary: Poll crawl status & items
      description: Inspects real-time progress of an in-flight or completed crawl job.
      operationId: getCrawlStatus
      parameters:
        - name: crawl_id
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Crawl status and extracted items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlStatusResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key (mint_live_... or mint_test_...)
  schemas:
    MintRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        js:
          type: boolean
          default: false
        stealth:
          type: boolean
          default: false
        schema:
          oneOf:
            - type: string
            - type: object
            - type: boolean
        no_cache:
          type: boolean
          default: false
        wait_for_selector:
          type: string
        timeout:
          type: integer
          default: 30
    MintResponse:
      type: object
      properties:
        markdown:
          type: string
        data:
          type: object
        status:
          type: integer
        _mint_meta:
          type: object
          properties:
            tier_used:
              type: string
            credits_billed:
              type: integer
            latency_ms:
              type: integer
            confidence:
              type: number
    ExtractRequest:
      type: object
      required:
        - url
        - schema
      properties:
        url:
          type: string
          format: uri
        schema:
          oneOf:
            - type: string
            - type: object
        js:
          type: boolean
          default: false
        stealth:
          type: boolean
          default: false
        no_cache:
          type: boolean
          default: false
    ExtractResponse:
      type: object
      properties:
        data:
          type: object
        status:
          type: integer
        _mint_meta:
          type: object
    CrawlRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        max_depth:
          type: integer
          default: 2
        max_pages:
          type: integer
          default: 25
        path_include:
          type: string
        path_exclude:
          type: string
        stealth:
          type: boolean
        schema:
          type: string
        webhook_url:
          type: string
          format: uri
    CrawlAcceptedResponse:
      type: object
      properties:
        crawl_id:
          type: string
        status:
          type: string
        url:
          type: string
        max_pages:
          type: integer
        created_at:
          type: string
    CrawlStatusResponse:
      type: object
      properties:
        crawl_id:
          type: string
        status:
          type: string
        pages_completed:
          type: integer
        pages_failed:
          type: integer
        credits_used:
          type: integer
        items:
          type: array
          items:
            type: object
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            required:
              type: integer
            balance:
              type: integer