Databook batch - create API

openapi: 3.2.0
info:
  title: DatabookAI REST batch - create API
  summary: Integrate DatabookAI's intelligence into your applications with a simple, reliable, and secure REST API.
  description: '## Introduction

    The DatabookAI REST API lets you integrate DatabookAI''s intelligence directly into your own applications and workflows. Browse the available operations, grouped by resource, in the **Endpoints** section below.


    The API uses standard HTTP methods, predictable resource-oriented URLs, and JSON-encoded request and response bodies. Every response, including errors, returns JSON.


    ## Getting started

    1. Obtain API access. Access is provisioned by Databook support, who issue the credentials your application uses to authenticate.

    2. Send your first request. Include your access token in the `Authorization` header (see **Authentication**) and the required identity headers on every call.

    3. Handle the response. Successful calls return a `2xx` status with a JSON body; failures return a JSON error object with a consistent shape (see **Errors**).


    ### Prerequisites

    - An active Databook account.

    - API access provisioned by Databook support.


    ## Authentication

    All requests must be authenticated with a bearer token issued by Databook support. Pass the token in the `Authorization` header:


    ```

    Authorization: Bearer

    ```


    Requests must also include the following identity headers so the API can resolve the calling user and tenant:


    | Header | Description |

    | --- | --- |

    | `databook-user-id` | Identifier of the user the request is made on behalf of. |

    | `databook-tenant-id` | Identifier of the tenant (organization) the request belongs to. |


    Requests that are missing or presenting an invalid token receive a `401 Invalid authentication` response. Tokens that lack the required permissions receive a `401` as well. Keep your token secret. Do not embed it in client-side code or commit it to source control.


    ## Requests and responses

    - All request and response bodies are JSON, except file uploads (for example, the batch job endpoint), which use `multipart/form-data`.

    - Send `Content-Type: application/json` for endpoints that accept a JSON body.

    - Timestamps are UTC and IDs are strings unless otherwise noted in the schema.


    ## Errors

    The API uses conventional HTTP status codes to indicate the outcome of a request. Codes in the `2xx` range indicate success, `4xx` codes indicate a problem with the request (for example, a missing parameter or invalid token), and `5xx` codes indicate an error on Databook''s side.


    Every error response shares the same shape: an `error` object containing a machine-readable `type` and a human-readable `message`. Some responses also include a `reference_id` you can share with Databook support to help investigate the issue.


    ```json

    {

    "error": {

    "type": "invalid_request",

    "message": "Invalid request"

    },

    "reference_id": "b1f2c3d4-..."

    }

    ```


    | Status | Error type | Meaning |

    | --- | --- | --- |

    | `400` | `invalid_request` | The request was malformed or failed validation. |

    | `401` | `invalid_authentication_error` | The access token is missing, invalid, or lacks the required permissions. |

    | `404` | `resource_not_found_error` | The requested resource does not exist. |

    | `429` | `rate_limit_error` | Too many requests. Slow down and retry after a short delay. |

    | `500` | `internal_server_error` | An unexpected error occurred on Databook''s side. |

    | `503` | `server_side_overload_error` | The service is temporarily overloaded or the request exceeded the time limit. Retry later. |


    ## Rate limits

    The API enforces rate limits to keep the service reliable for everyone. When you exceed a limit, requests return `429 rate_limit_error`. Build retries with exponential backoff into your integration to handle these responses gracefully.


    ## Timeouts

    The maximum duration for any single API call is 180 seconds. Requests that exceed this limit return a `503 server_side_overload_error`. For long-running workloads, prefer the batch endpoints, which process work asynchronously.


    ## Legal

    Privacy Policy


    Terms and Conditions


    API Terms


    Security Trust Center


    Databook


    ## Endpoints'
  version: 0.6.0
servers:
- url: https://api.databook.com
tags:
- name: batch - create
  x-displayName: Batch - Create
paths:
  /v1/batch/job:
    post:
      tags:
      - batch - create
      summary: Create job
      operationId: create_job_v1_batch_job_post
      security:
      - HTTPBearer: []
      parameters:
      - name: databook-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-User-Id
      - name: databook-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-Tenant-Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_job_v1_batch_job_post'
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
              - file
              title: Body_create_job_v1_batch_job_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobByIdResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidRequest'
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidAuthentication'
        '404':
          description: Requested resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRequestedResourceNotFound'
        '429':
          description: Rate limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRateLimitReached'
        '500':
          description: Unexpected error on server side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInternalServer'
        '503':
          description: Server side overload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyServerSideOverload'
  /v1/batch/job/input-csv-template:
    get:
      tags:
      - batch - create
      summary: Get input CSV template
      operationId: get_job_input_csv_template_v1_batch_job_input_csv_template_get
      security:
      - HTTPBearer: []
      parameters:
      - name: databook-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-User-Id
      - name: databook-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobInputCsvTemplateResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidRequest'
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidAuthentication'
        '404':
          description: Requested resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRequestedResourceNotFound'
        '429':
          description: Rate limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRateLimitReached'
        '500':
          description: Unexpected error on server side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInternalServer'
        '503':
          description: Server side overload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyServerSideOverload'
  /v1/insights:
    get:
      tags:
      - batch - create
      summary: List insights
      operationId: list_insights_v1_insights_get
      security:
      - HTTPBearer: []
      parameters:
      - name: databook-user-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-User-Id
      - name: databook-tenant-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Databook-Tenant-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInsightResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidRequest'
        '401':
          description: Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInvalidAuthentication'
        '404':
          description: Requested resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRequestedResourceNotFound'
        '429':
          description: Rate limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyRateLimitReached'
        '500':
          description: Unexpected error on server side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyInternalServer'
        '503':
          description: Server side overload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBodyServerSideOverload'
components:
  schemas:
    ErrorResponseBodyErrorObjectRequestedResourceNotFound:
      properties:
        type:
          type: string
          const: resource_not_found_error
          title: Type
        message:
          type: string
          title: Message
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectRequestedResourceNotFound
    ErrorResponseBodyErrorObjectRateLimitReached:
      properties:
        type:
          type: string
          const: rate_limit_error
          title: Type
        message:
          type: string
          title: Message
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectRateLimitReached
    ErrorResponseBodyServerSideOverload:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectServerSideOverload'
      type: object
      required:
      - error
      title: ErrorResponseBodyServerSideOverload
    ErrorResponseBodyRequestedResourceNotFound:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectRequestedResourceNotFound'
      type: object
      required:
      - error
      title: ErrorResponseBodyRequestedResourceNotFound
    ErrorResponseBodyErrorObjectServerSideOverload:
      properties:
        type:
          type: string
          const: server_side_overload_error
          title: Type
        message:
          type: string
          title: Message
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectServerSideOverload
    ListInsightElement:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        version:
          type: integer
          title: Version
        description:
          type: string
          title: Description
        category:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
      type: object
      required:
      - id
      - name
      - version
      - description
      title: ListInsightElement
    GetJobInputCsvTemplateResponse:
      properties:
        job_input_csv_template_url:
          type: string
          title: Job Input Csv Template Url
      type: object
      required:
      - job_input_csv_template_url
      title: GetJobInputCsvTemplateResponse
    ErrorResponseBodyErrorObjectInternalServer:
      properties:
        type:
          type: string
          const: internal_server_error
          title: Type
        message:
          type: string
          title: Message
        reference_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Id
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectInternalServer
    ErrorResponseBodyErrorObjectInvalidRequest:
      properties:
        type:
          type: string
          const: invalid_request
          title: Type
        message:
          type: string
          title: Message
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectInvalidRequest
    ErrorResponseBodyErrorObjectInvalidAuthentication:
      properties:
        type:
          type: string
          const: invalid_authentication_error
          title: Type
        message:
          type: string
          title: Message
      type: object
      required:
      - type
      - message
      title: ErrorResponseBodyErrorObjectInvalidAuthentication
    ListInsightResponse:
      properties:
        result:
          items:
            $ref: '#/components/schemas/ListInsightElement'
          type: array
          title: Result
      type: object
      required:
      - result
      title: ListInsightResponse
    GetJobByIdResponse:
      properties:
        id:
          type: string
          title: Id
        state:
          type: string
          title: State
        stopped_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Stopped Reason
        created_at:
          type: string
          title: Created At
        started_running_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started Running At
        stopped_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Stopped At
      type: object
      required:
      - id
      - state
      - created_at
      title: GetJobByIdResponse
    ErrorResponseBodyRateLimitReached:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectRateLimitReached'
      type: object
      required:
      - error
      title: ErrorResponseBodyRateLimitReached
    Body_create_job_v1_batch_job_post:
      properties:
        file:
          type: string
          contentMediaType: application/octet-stream
          title: File
      type: object
      required:
      - file
      title: Body_create_job_v1_batch_job_post
    ErrorResponseBodyInvalidAuthentication:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectInvalidAuthentication'
      type: object
      required:
      - error
      title: ErrorResponseBodyInvalidAuthentication
    ErrorResponseBodyInvalidRequest:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectInvalidRequest'
      type: object
      required:
      - error
      title: ErrorResponseBodyInvalidRequest
    ErrorResponseBodyInternalServer:
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseBodyErrorObjectInternalServer'
      type: object
      required:
      - error
      title: ErrorResponseBodyInternalServer
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Databook
  source: https://api.databook.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)