openapi: 3.0.0
info:
  title: Databox API
  version: v1
  description: >
    The Databox API allows you to integrate Databox with external systems,
    automate data ingestion,

    and extend platform functionality. It follows REST conventions with
    resource-oriented URLs,

    JSON request/response bodies, and standard HTTP methods/status codes.
servers:
  - url: https://api.databox.com
    description: Production server
tags:
  - name: Accounts
    description: Access account details, configuration, and associated resources.
  - name: Auth
    description: Authentication and API key validation operations.
  - name: Data Sources
    description: Create and delete data sources; list datasets for a data source.
  - name: Datasets
    description: >-
      Create, ingest into, purge, and delete datasets; list and inspect
      ingestions.
paths:
  /v1/accounts:
    get:
      tags:
        - Accounts
      summary: List accounts
      description: >-
        Retrieves all accounts accessible to the user associated with the API
        key.
      operationId: Accounts_GetAccounts
      security:
        - x-api-key: []
      responses:
        '200':
          $ref: '#/components/responses/200_Accounts_GetAccounts'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/accounts/{accountId}/data-sources:
    get:
      tags:
        - Accounts
      summary: List data sources
      description: >
        Retrieves the list of ingestible data sources available for the
        specified account.  

        Only data sources that can accept ingested data and be created via the
        API are included.
      operationId: Accounts_GetDataSources
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.accountId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_Accounts_GetDataSources'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/accounts/timezones:
    get:
      tags:
        - Accounts
      summary: List time zones
      description: >-
        Retrieves the list of all timezones supported by Databox, including
        their UTC offsets and IANA identifiers.
      operationId: Accounts_GetTimezones
      security:
        - x-api-key: []
      responses:
        '200':
          $ref: '#/components/responses/200_Accounts_GetTimezones'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/auth/validate-key:
    get:
      tags:
        - Auth
      summary: Validate an API key
      description: >
        Validates the API key supplied in the `x-api-key` header.


        Use this endpoint as a setup/health check. Integration partners can call
        it to confirm

        a customer's key before enabling data ingestion or completing account
        linking.

        - **200 OK:** Key is valid.

        - **401 Unauthorized:** Key is missing or invalid (standard error
        envelope).
      operationId: Auth_ValidateApiKey
      security:
        - x-api-key: []
      responses:
        '200':
          $ref: '#/components/responses/200_Auth_GetValidation'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/data-sources:
    post:
      tags:
        - Data Sources
      summary: Create a data source
      description: >
        Creates an ingestion data source (a container for one or more datasets).


        If `accountId` is provided, the data source is created in that account;

        otherwise, it is created in the account associated with the API key.


        Requires a valid `x-api-key` with permission to create data sources in
        the target account.
      operationId: DataSources_PostCreate
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Header.ContentType.required'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
              properties:
                accountId:
                  $ref: '#/components/schemas/accountId'
                title:
                  $ref: '#/components/schemas/title.dataSource'
                timezone:
                  $ref: '#/components/schemas/timezone'
      responses:
        '200':
          $ref: '#/components/responses/200_DataSources_PostCreate'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/data-sources/{dataSourceId}:
    delete:
      tags:
        - Data Sources
      summary: Delete a data source
      description: >
        Permanently deletes the specified ingestion data source
        (`dataSourceId`).


        Deleting a data source also deletes all datasets it contains (and their
        data). **This action is irreversible.**


        Requires a valid `x-api-key` with permission to manage data sources in
        the target account.
      operationId: DataSources_Delete
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.dataSourceId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_DataSources_Delete'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
        '403':
          $ref: '#/components/responses/403_General'
  /v1/data-sources/{dataSourceId}/datasets:
    get:
      tags:
        - Data Sources
      summary: List datasets
      description: >-
        Retrieves all datasets that belong to the specified data source
        (`dataSourceId`).
      operationId: DataSources_GetDatasets
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.dataSourceId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_DataSources_GetDatasets'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets:
    post:
      tags:
        - Datasets
      summary: Create a dataset
      operationId: Datasets_PostCreate
      description: >
        Creates a new dataset within the specified data source. A dataset acts
        as a container for ingested data and can later be populated with rows.
        Once created, the dataset can be used for reporting, visualizations, and
        transformations within the platform.


        Notes:
          - Requires a valid `x-api-key` with permission to manage datasets in the target account.
          - Each dataset must belong to an existing data source; it cannot exist independently.
          - The dataset is created empty; data is added afterward through ingestion events.
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Header.ContentType.required'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  $ref: '#/components/schemas/title.dataset'
                dataSourceId:
                  $ref: '#/components/schemas/dataSourceId'
                primaryKeys:
                  $ref: '#/components/schemas/primaryKeys'
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_PostCreate'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets/{datasetId}:
    delete:
      tags:
        - Datasets
      summary: Delete a dataset
      description: >
        Deletes the specified dataset. This action permanently removes all
        associated data and **cannot be reversed**.
      operationId: Datasets_Delete
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.datasetId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_Delete'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets/{datasetId}/purge:
    post:
      tags:
        - Datasets
      summary: Purge a dataset
      description: >
        Purges the specified dataset by removing all rows of data it contains.
        The dataset itself remains intact and can continue to receive new
        ingestions.


        **This operation is irreversible — once purged, the deleted data cannot
        be restored.**
      operationId: Datasets_PostPurge
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.datasetId.required'
        - $ref: '#/components/parameters/Header.ContentType.required'
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_PostPurge'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets/{datasetId}/data:
    post:
      tags:
        - Datasets
      summary: Create an ingestion
      description: >
        Adds a batch of data records to the specified dataset through an
        ingestion event.  


        You can include up to **100 records** per ingestion event.


        The returned `ingestionId` values can be used with the corresponding
        [ingestion details endpoint](datasets_getingestion) to retrieve more
        information the ingestion event.
      operationId: Datasets_PostCreateIngestion
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.datasetId.required'
        - $ref: '#/components/parameters/Header.ContentType.required'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/records'
            examples:
              basic:
                $ref: >-
                  #/components/examples/Request.Datasets_PostCreateIngestion.records
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_PostCreateIngestion'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets/{datasetId}/ingestions:
    get:
      tags:
        - Datasets
      summary: List ingestions
      description: >
        Retrieves a list of ingestions events that have been created for the
        specified dataset. 


        The returned `ingestionId` values can be used with the corresponding
        [ingestion details endpoint](datasets_getingestion) to retrieve more
        information about a specific ingestion event.
      operationId: Datasets_GetListIngestions
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.datasetId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_GetIngestions'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
  /v1/datasets/{datasetId}/ingestions/{ingestionId}:
    get:
      tags:
        - Datasets
      summary: Retrieve an ingestion
      description: >-
        Retrieves detailed information for an ingestion event, allowing you to
        check processing progress and outcomes.
      operationId: Datasets_GetIngestion
      security:
        - x-api-key: []
      parameters:
        - $ref: '#/components/parameters/Path.datasetId.required'
        - $ref: '#/components/parameters/Path.ingestionId.required'
      responses:
        '200':
          $ref: '#/components/responses/200_Datasets_GetIngestion'
        '400':
          $ref: '#/components/responses/400_General'
        '401':
          $ref: '#/components/responses/401_General'
components:
  securitySchemes:
    x-api-key:
      type: apiKey
      description: API key for authentication
      name: x-api-key
      in: header
  parameters:
    Header.ContentType.required:
      name: Content-Type
      in: header
      description: Must be set to `application/json`
      required: true
      schema:
        type: string
    Path.accountId.required:
      name: accountId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/accountId'
    Path.datasetId.required:
      name: datasetId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/datasetId'
    Path.dataSourceId.required:
      name: dataSourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/dataSourceId'
    Path.ingestionId.required:
      name: ingestionId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ingestionId'
  responses:
    200_Accounts_GetAccounts:
      description: >-
        Successful response containing the accounts accessible to the
        authenticated user.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - type: object
                properties:
                  accounts:
                    type: array
                    description: List of accounts.
                    items:
                      $ref: '#/components/schemas/Account'
    200_Accounts_GetDataSources:
      description: >-
        Successful response containing the list of ingestible data sources
        available for the account.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - type: object
                properties:
                  dataSources:
                    type: array
                    description: List of ingestible data sources.
                    items:
                      $ref: '#/components/schemas/DataSource'
    200_Accounts_GetTimezones:
      description: Successful response containing the list of supported time zones.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - type: object
                properties:
                  timezones:
                    type: array
                    description: >-
                      List of supported time zones with their UTC offsets and
                      IANA identifiers.
                    items:
                      $ref: '#/components/schemas/Timezone'
    200_Auth_GetValidation:
      description: Successful response confirming the provided API key is valid.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
    200_Datasets_Delete:
      description: >-
        Successful response indicating that the data source and all contained
        datasets were permanently deleted.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/message'
          examples:
            basic:
              $ref: '#/components/examples/Response.200_Datasets_Delete.message'
    200_Datasets_GetIngestion:
      description: >-
        Successful response containing detailed information about the requested
        ingestion event.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/Ingestion'
    200_Datasets_GetIngestions:
      description: >-
        Successful response containing a list of ingestion events for the
        specified dataset.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/Ingestion.list'
    200_Datasets_PostCreate:
      description: Successful response containing the newly created dataset.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/Dataset'
    200_Datasets_PostCreateIngestion:
      description: >-
        Successful response containing confirmation that the ingestion request
        was accepted.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/Ingestion.create'
    200_Datasets_PostPurge:
      description: Successful response indicating that the dataset has been purged.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/message'
          examples:
            basic:
              $ref: '#/components/examples/Response.200_Datasets_PostPurge.message'
    200_DataSources_GetDatasets:
      description: >
        Successful response containing a list of all datasets associated with
        the given data source.  

        If the data source has no datasets, the response will return an empty
        array.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - type: object
                properties:
                  datasets:
                    type: array
                    description: List of datasets and their metadata.
                    items:
                      $ref: '#/components/schemas/Dataset'
    200_DataSources_PostCreate:
      description: Successful response containing the newly created data source.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.processing'
              - $ref: '#/components/schemas/DataSource'
    200_DataSources_Delete:
      description: >-
        Successful response indicating that the data source and all contained
        datasets were permanently deleted.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.success'
              - $ref: '#/components/schemas/message'
          examples:
            message:
              $ref: '#/components/examples/Response.DataSources_Delete.message'
    400_General:
      description: Error response indicating one or more request parameters are invalid.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.error'
              - $ref: '#/components/schemas/errors'
    401_General:
      description: Error response indicating that the API key is missing or invalid.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.error'
              - $ref: '#/components/schemas/errors'
          examples:
            basic:
              $ref: '#/components/examples/Response.Errors.401'
    403_General:
      description: >-
        Error response indicating that the user associated with the API key is
        not authorized to perform this action on the specified resource.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/requestId'
              - $ref: '#/components/schemas/status.error'
              - $ref: '#/components/schemas/errors'
          examples:
            basic:
              $ref: '#/components/examples/Response.Errors.403'
  schemas:
    accountId:
      type: integer
      format: int64
      description: Unique identifier for the Databox account.
      example: 123456
    datasetId:
      type: string
      format: uuid
      description: Unique identifier for the dataset.
      example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
    dataSourceId:
      type: integer
      format: int64
      description: Unique identifier for the data source.
      example: 4754489
    errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/errors.item'
    errors.item:
      type: object
      description: >-
        Detailed information about a specific error that occurred while
        processing a request.
      properties:
        code:
          type: string
          nullable: true
          description: A machine-readable error code that identifies the type of error.
          example: invalid_input
        message:
          type: string
          description: A human-readable message explaining the error.
          example: The provided parameter is invalid.
        field:
          type: string
          description: >-
            The name of the request field associated with the error, if
            applicable.
          example: datasetId
        type:
          type: string
          description: >-
            The category or context of the error, such as validation or
            permission.
          example: validation
    ingestion.list:
      type: object
      description: List of ingestion events.
      properties:
        ingestionId:
          $ref: '#/components/schemas/ingestionId'
        timestamp:
          type: string
          example: '2025-10-01T12:00:00.000000Z'
        status:
          type: string
          description: Indicates the status of the ingestion event.
          example: success
    ingestionId:
      type: string
      format: uuid
      description: Unique identifier for the ingestion event.
      example: 8bfba187-84f4-41e2-9dd3-bee4bb884205
    message:
      type: object
      properties:
        message:
          type: string
          description: >-
            Human-readable message describing the outcome of the request (for
            display/logging; not intended for programmatic parsing).
          example: Resource deleted successfully
    metrics:
      type: object
      description: >-
        Metrics summarizing dataset characteristics and the outcome of the
        ingestion event
      additionalProperties: false
      properties:
        datasetMetrics:
          type: object
          description: Metrics describing the current state of the dataset.
          additionalProperties: false
          properties:
            columnsCount:
              type: integer
              description: Number of columns in the dataset.
              example: 20
            datasetSizeMB:
              type: number
              format: double
              description: Current size of the dataset in megabytes.
              example: 12.3456789
            totalDatasetRecordsCount:
              type: integer
              description: Total number of records stored in the dataset.
              example: 500000
        ingestionMetrics:
          type: object
          description: Metrics describing the result of the ingestion.
          additionalProperties: false
          properties:
            appendedRecordsCount:
              type: integer
              description: Number of records successfully appended to the dataset.
              example: 100
            receivedRecordsCount:
              type: integer
              description: Total number of records received in the ingestion request.
              example: 100
            rejectedRecordsCount:
              type: integer
              description: Number of records rejected due to errors or validation issues.
              example: 0
            overwrittenRecordsCount:
              type: integer
              description: Number of records that were overwritten in the dataset.
              example: 0
    primaryKeys:
      type: array
      description: >
        Array of column names that uniquely identify rows in the dataset.  

        if the dataset has no unique columns or identifiers, this field can be
        omitted (`null`).
      nullable: true
      items:
        type: string
        nullable: true
        example: invoice_id
    records:
      type: object
      description: Container for one or more records to ingest.
      properties:
        records:
          type: array
          description: >-
            Aray of arbitrary key-value pairs representing a single event, item,
            or row.
          items:
            $ref: '#/components/schemas/records.item'
      required:
        - records
    records.item:
      type: object
      description: Arbitrary key-value pairs representing a single event, item, or row.
      additionalProperties: true
    requestId:
      type: object
      properties:
        requestId:
          type: string
          description: Unique identifier for the request.
          example: b0eac937-c25c-47a5-bb7e-552f6b860458
    status.error:
      type: object
      properties:
        status:
          type: string
          description: Indicates the status of the request.
          example: error
    status.processing:
      type: object
      properties:
        status:
          type: string
          description: Indicates the status of the request.
          example: processing
    status.success:
      type: object
      properties:
        status:
          type: string
          description: Indicates the status of the request.
          example: success
    timezone:
      type: string
      description: >-
        IANA time zone string indicating the data source time zone used for data
        visualization.
      example: UTC
    title.dataset:
      type: string
      description: Human-readable name of the dataset. May be empty but not null.
      example: Transactions
    title.dataSource:
      type: string
      description: Human-readable name of the data source. May be empty but not null.
      example: ERP System
    Account:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
          format: int64
          description: Account ID.
          example: 123456
        name:
          type: string
          description: Name of the account.
          example: Acme Corp
        accountType:
          type: string
          description: Type of account.
          enum:
            - organization
            - agency
            - client
    Dataset:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: Unique identifier for the dataset.
          format: uuid
          example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
        title:
          type: string
          description: Human-readable name of the dataset. May be empty but not null.
          nullable: true
          example: Transactions
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the data source was created.
          example: '2025-10-01T12:00:00.000000Z'
    DataSource:
      type: object
      additionalProperties: false
      description: Represents a data source that can be used to create and manage datasets.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the data source.
          example: 4754489
        title:
          type: string
          description: Human-readable name of the data source. May be empty but not null.
          example: ERP System
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the data source was created.
          example: '2025-10-01T12:00:00.000000Z'
        timezone:
          type: string
          description: >-
            IANA time zone string indicating the data source time zone used for
            data visualization.
          example: UTC
        key:
          type: string
          description: Internal identifier for the data source. Defaults to `"ingestion"`.
          example: ingestion
    Ingestion:
      type: object
      description: List of ingestion events.
      properties:
        ingestionId:
          $ref: '#/components/schemas/ingestionId'
        timestamp:
          type: string
          example: '2025-10-01T12:00:00.000000Z'
        metrics:
          type: object
          $ref: '#/components/schemas/metrics'
    Ingestion.create:
      type: object
      additionalProperties: false
      properties:
        ingestionId:
          type: string
          description: Unique identifier for the ingestion event.
          format: uuid
          example: 8bfba187-84f4-41e2-9dd3-bee4bb884205
        message:
          type: string
          description: >-
            Human-readable message describing the outcome of the request (for
            display/logging; not intended for programmatic parsing).
          format: date-time
          example: Data ingestion request accepted
    Ingestion.list:
      type: object
      additionalProperties: false
      properties:
        ingestions:
          type: array
          description: List of ingestion events.
          items:
            $ref: '#/components/schemas/ingestion.list'
    Timezone:
      type: object
      additionalProperties: false
      properties:
        offset:
          type: string
          description: UTC offset in ±HH:MM format.
          example: GMT+2
        timezone:
          type: string
          description: IANA identifier for the time zone.
          example: Europe/Ljubljana
  examples:
    Request.Datasets_PostCreateIngestion.records:
      value:
        records:
          - transactionId: '9826'
            occurredAt: '2025-10-01T12:00:00.000000Z'
            amount: 42.5
            tags:
              - promo
              - returning
    Response.200_Datasets_Delete.message:
      value:
        requestId: b0eac937-c25c-47a5-bb7e-552f6b860458
        status: success
        message: Dataset deleted successfully
    Response.200_Datasets_PostPurge.message:
      value:
        requestId: b0eac937-c25c-47a5-bb7e-552f6b860458
        status: success
        message: Dataset purged successfully
    Response.DataSources_Delete.message:
      value:
        requestId: b0eac937-c25c-47a5-bb7e-552f6b860458
        status: success
        message: Data source deleted successfully
    Response.Errors.401:
      value:
        requestId: b0eac937-c25c-47a5-bb7e-552f6b860458
        status: error
        errors:
          - code: invalid_api_key
            message: An error occurred while validating the API key
            field: x-api-key
            type: validation
    Response.Errors.403:
      value:
        requestId: b0eac937-c25c-47a5-bb7e-552f6b860458
        status: error
        errors:
          - code: forbidden
            message: You don't have permission to access this resource.
            field: ''
            type: permission
