openapi: 3.1.0
info:
  title: Workspace Imports API
  description: |
    API to programmatically trigger an existing workspace-scoped
    import in Bloomreach Engagement.
  version: "2.1"

servers:
  - url: https://api.bloomreach.com
    description: Bloomreach API

security:
  - basicAuth: []

tags:
  - name: Imports
    description: Operations for working with existing imports.

paths:
  /data/v2/workspaces/{workspaceId}/imports/{import_id}/start:
    post:
      summary: Start import
      operationId: startWorkspaceImport
      tags:
        - Imports
      description: |
        Trigger the run of an existing workspace-scoped import programmatically.

        The following types of imports can be triggered: [URL](https://documentation.bloomreach.com/data-hub/docs/url-imports), [File storage
        (GCS, S3, SFTP)](https://documentation.bloomreach.com/data-hub/docs/file-storage-imports), [Data warehouse](https://documentation.bloomreach.com/data-hub/docs/data-warehouse-imports).

        If you're using a URL or File storage (GCS, SFTP) import, you can
        override its original path or URL. When overridden, the path
        applies only to this specific run and does not modify the import
        definition.

        Use this endpoint with a [**workspace** API key](https://documentation.bloomreach.com/data-hub/reference/data-hub-api-prerequisites) (issued in
        Workspace settings → Access management → API). The
        `{workspaceId}` in the path must match the workspace the API key
        was issued for.

        ### Authorization
        - **Access type:** Private access (workspace API key)
        - **Permission required:** Imports → Allow trigger imports

        ### Limitations
        - Cannot trigger **Copy & paste** or **File upload** imports.
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ImportId'
      requestBody:
        $ref: '#/components/requestBodies/StartImportBody'
      responses:
        '200':
          $ref: '#/components/responses/Started'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic authentication using an API Key ID and API Secret.
        For this workspace-scoped endpoint, use a workspace API key.

        `Authorization: Basic <base64(APIKeyID:APISecret)>`

        The API key must have the **Imports → Allow trigger imports**
        permission enabled in Workspace settings → Access management →
        API.

  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      description: |
        The ID of your Bloomreach Engagement workspace. Must match the
        workspace the API key was issued for; otherwise the request is
        rejected with HTTP 403.
      schema:
        type: string
        example: "12345678-1234-1234-1234-123456789abc"
    ImportId:
      name: import_id
      in: path
      required: true
      description: The ID of an existing import in the workspace.
      schema:
        type: string
        example: "5f8a3b2e1c9d4e6f7a8b9c0d"

  requestBodies:
    StartImportBody:
      required: false
      description: |
        Optional body to override the source path or skip the
        connection-test step. The body may be omitted entirely.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StartImportRequest'
          examples:
            overridePath:
              summary: Override the source path for this run
              value:
                path: "https://example.com/data.csv"
                test_connection: true
            skipConnectionTest:
              summary: Run without testing the source connection
              value:
                test_connection: false

  responses:
    Started:
      description: Import triggered successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponse'
          examples:
            success:
              value:
                success: true
    BadRequest:
      description: |
        Bad request — the request was malformed, contained invalid
        parameters, or the underlying import service rejected the run
        (for example, an invalid override path).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            globalError:
              summary: Validation or restriction error
              value:
                success: false
                errors:
                  _global:
                    - "BadRequest: The browser (or proxy) sent a request that this server could not understand."
            passthroughError:
              summary: Error returned by the import service
              value:
                error: "bad path"
    Unauthorized:
      description: |
        Authentication is missing or invalid. Provide HTTP Basic
        credentials with a valid API Key ID and Secret.
      headers:
        WWW-Authenticate:
          description: 'Basic realm="Login Required"'
          schema:
            type: string
    Forbidden:
      description: |
        The API key lacks the **Imports → Allow trigger imports**
        permission, or the `workspaceId` in the path does not match the
        workspace the API key was issued for.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            noPermission:
              value:
                success: false
                errors:
                  _global:
                    - "No permission to allow trigger imports. Check Workspace settings -> Access management -> API -> Imports -> Allow trigger imports."
    NotFound:
      description: |
        No import with the given `import_id` exists in the addressed
        workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundErrorResponse'
          examples:
            notFound:
              value:
                success: false
                errors:
                  code: "NotFoundError"
                  message: "The requested resource was not found."

  schemas:
    StartImportRequest:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          description: |
            URL, GCS, or SFTP path that overrides the import's configured
            source. The override applies only to this run — it does not
            modify the import definition. Only applicable for URL and
            Filestorage (GCS, SFTP) imports.
          example: "https://example.com/data.csv"
        test_connection:
          type: boolean
          description: |
            When `true` (default), the API tests the import-source
            connection before starting the run. Set to `false` to skip
            the check — useful for sources that may otherwise time out.
            With the check skipped, the import can still fail later if
            the source is unreachable.
          default: true

    SuccessResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          example: true

    ErrorResponse:
      type: object
      description: |
        Error response. Most errors use the `success` + `errors._global`
        shape; some failures returned by the underlying import service
        are surfaced verbatim and use the alternative `error` shape.
      properties:
        success:
          type: boolean
          example: false
        errors:
          type: object
          description: Map of error categories to error messages.
          properties:
            _global:
              type: array
              description: Errors not tied to a specific field.
              items:
                type: string
        error:
          type: string
          description: |
            Single error message returned by the underlying import
            service for some failure modes.

    NotFoundErrorResponse:
      type: object
      required:
        - success
        - errors
      properties:
        success:
          type: boolean
          example: false
        errors:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: "NotFoundError"
            message:
              type: string
              example: "The requested resource was not found."