---
title: "Input mapping load"
method: POST
path: "/v2/storage/workspaces/{workspaceId}/input-mapping-load"
tags: ["Workspaces"]
---

# Input mapping load

`POST /v2/storage/workspaces/{workspaceId}/input-mapping-load`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/workspaces/{workspaceId}/input-mapping-load`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/workspaces/:workspaceId/input-mapping-load/post.ts> (a function with typed inputs; its response is checked against the schema)

Loads tables from Storage into a Workspace using a `keboola/input-mapping` `Configuration\Table` payload (snake_case)
accepted unchanged. This mirrors what component code already produces and removes the need to translate to the SAPI
camelCase `/load` shape.

The endpoint resolves the load type per input item via the canonical `LoadTypeDecider` with priority
**CLONE > VIEW > COPY**. CLONE is gated by the `bq-enable-clone` feature on BigQuery; VIEW on Snowflake is gated by
the `input-mapping-read-only-storage` feature.

Each input item must reference its source via `source` — the full source table id (e.g. `in.c-bucket.mytable`).
`where_column` and `where_values` must be provided together (setting one without the other returns HTTP 400).

**Dry-run** (`dryRun=true`): preflight variant that resolves the load type per input item **without** creating a job.
The dry-run runs the same validations the real load runs — a successful 200 dry-run guarantees the same payload
submitted with `dryRun=false` will not be rejected by validation (modulo source state changing between calls).
It returns HTTP 200 (not 202) with `loadType` (the type `LoadTypeDecider` would pick) and `possibleLoadTypes`
(all types acceptable for the item; useful for driving a UI dropdown) per input item.

This operation is also available scoped to a [Development Branch](#tag/Development-Branches),
at `/branch/{branchId}/workspaces/{workspaceId}/input-mapping-load`. The `dryRun` query
parameter and both response shapes behave identically there.

## Path parameters

- `workspaceId` integer, required

## Query parameters

- `dryRun` boolean

## Headers

- `X-KBC-Backend` object
  - `context` string, nullable

## Request body

- InputMappingLoadRequest
  - `input` object[], required
    - `source` string, required
    - `source_branch_id` integer
    - `destination` string, required
    - `description` string, nullable: Description of the workspace table; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.
    - `days` integer, nullable
    - `changed_since` string, nullable
    - `columns` string[]
    - `column_types` object[]
      - `source` string, required
      - `description` string, nullable: Description of the workspace column; overrides the Storage description. Empty or null inherits it. Ignored for VIEW loads.
      - `type` string
      - `destination` string
      - `length` union
        - string
        - integer
      - `nullable` boolean
      - `convert_empty_values_to_null` boolean
    - `where_column` string
    - `where_values` string[]
    - `where_operator` 'eq' | 'ne'
    - `limit` integer
    - `overwrite` boolean
    - `load_type` 'COPY' | 'CLONE' | 'VIEW' | 'AUTO'
    - `use_view` boolean: Legacy alias for `load_type: VIEW`. Kept for backward compatibility.
    - `keep_internal_timestamp_column` boolean
    - `incremental` boolean
    - `file_type` string
    - `backend` string: Storage backend to evaluate this item against on the workspace-less preview endpoint (e.g. `snowflake`, `bigquery`). Takes precedence over the `backend` query parameter and the project default. Must be one of the project's assigned backends. Ignored by the workspace load endpoint, which derives the backend from the workspace.
  - `preserve` boolean

## Response `200`

Dry-run (`dryRun=true`): the payload was validated exactly as the real load would and the resolved load types per input table are returned. No job is created.

- InputMappingLoadDryRunResponse
  - `dryRun` boolean, required
  - `operationName` string, required
  - `input` object[], required
    - `source` string, required
    - `destination` string, required
    - `loadType` 'COPY' | 'CLONE' | 'VIEW', required
    - `possibleLoadTypes` string[], required

## Other responses

- `202`: Workspace load job enqueued (`dryRun=false`).
- `400`: Invalid request — validation error (`workspace.loadRequestBadInput`), unsupported option, load type not available for the item, duplicate destination, `where_column` without `where_values`, or a deactivated workspace (`workspace.workspaceDeactivated`).
- `403`: Caller does not have access to the requested source table (`workspace.tableAccessDenied`).
- `404`: Workspace (`workspace.workspaceNotFound`) or source table (`workspace.sourceNotFound`) not found.
- `422`: Unsupported workspace backend for the requested load (`workspace.backendNotSupported`).

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)