openapi: 3.0.3
info:
  title: Import.io Crawlrun API
  description: 'The Import.io API (v2.0) provides programmatic access to create, manage, and run

    web data extractors, retrieve crawl run results, and manage reports. Everything

    available in the Import.io UI can be accomplished via the API, including

    scheduling extractions, managing data pipelines, and exporting data in JSON,

    CSV, or Excel formats. Authenticated extraction is supported for data behind

    login screens.


    Authentication is performed by passing your API key as the `_apikey` query

    parameter on every request. You can find your API key in the Import.io

    dashboard under User Settings.

    '
  version: '2.0'
  contact:
    name: Import.io Support
    url: https://help.import.io/
  license:
    name: Proprietary
    url: https://www.import.io/terms-of-use/
servers:
- url: https://api.import.io
  description: Production API
security:
- apiKeyAuth: []
tags:
- name: Crawlrun
  description: Retrieve crawl run executions and their result files.
paths:
  /crawlruns/:
    get:
      tags:
      - Crawlrun
      summary: List crawl runs
      description: List recent crawl runs with optional filters and pagination.
      operationId: listCrawlruns
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          description: Array of crawl runs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Crawlrun'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /crawlruns/{crawlrunId}:
    get:
      tags:
      - Crawlrun
      summary: Get crawl run
      description: Retrieve information about a specific crawl run.
      operationId: getCrawlrun
      parameters:
      - $ref: '#/components/parameters/CrawlrunId'
      - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Crawl run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Crawlrun'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /crawlruns/{crawlrunId}/{fileType}:
    get:
      tags:
      - Crawlrun
      summary: Get crawl run results file
      description: Download the result file for a crawl run in the requested format.
      operationId: getCrawlrunFile
      parameters:
      - $ref: '#/components/parameters/CrawlrunId'
      - name: fileType
        in: path
        required: true
        description: The file type to download.
        schema:
          type: string
          enum:
          - csv
          - xlsx
          - log
          - sample
          - json
          - files
      - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Result file
          content:
            text/csv: {}
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
            application/json: {}
            application/x-ndjson: {}
            text/plain: {}
            application/zip: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: Internal error code.
        message:
          type: string
          description: Human-readable error description.
        error:
          type: string
          description: Deprecated error string.
          deprecated: true
    Meta:
      type: object
      description: Common metadata included on most resources.
      properties:
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
        ownerId:
          type: string
          format: uuid
        creatorId:
          type: string
          format: uuid
        editorId:
          type: string
          format: uuid
    Crawlrun:
      type: object
      properties:
        guid:
          type: string
          format: uuid
        extractorId:
          type: string
          format: uuid
        state:
          type: string
          enum:
          - PENDING
          - STARTED
          - FINISHED
          - FAILED
          - CANCELLED
        startedAt:
          type: string
          format: date-time
        stoppedAt:
          type: string
          format: date-time
        totalUrlCount:
          type: integer
        successUrlCount:
          type: integer
        failedUrlCount:
          type: integer
        rowCount:
          type: integer
        screenCaptureCount:
          type: integer
        htmlExtractionCount:
          type: integer
        files:
          type: object
          additionalProperties: true
        webhooks:
          type: array
          items:
            type: object
            additionalProperties: true
        _meta:
          $ref: '#/components/schemas/Meta'
  parameters:
    SortDirection:
      name: _sortDirection
      in: query
      required: false
      description: Sort direction.
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    ApiKey:
      name: _apikey
      in: query
      required: true
      description: Your Import.io API key.
      schema:
        type: string
    CrawlrunId:
      name: crawlrunId
      in: path
      required: true
      description: Unique identifier of the crawl run.
      schema:
        type: string
        format: uuid
    Sort:
      name: _sort
      in: query
      required: false
      description: Field to sort by, e.g. `meta_created_at`.
      schema:
        type: string
    PerPage:
      name: _perpage
      in: query
      required: false
      description: Number of items to return per page.
      schema:
        type: integer
    Page:
      name: _page
      in: query
      required: false
      description: Page number to return (default 1).
      schema:
        type: integer
        default: 1
  responses:
    Unauthorized:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: _apikey
      description: API key obtained from the Import.io dashboard User Settings.