Owlbound
Browse the docs

Reference · 6 operations

Tables: imports and exports

Last updated from API version 2026-10-06 at (live spec, refreshed hourly). openapi.json

Imports

tables.imports.create

Import an uploaded CSV file into the table (runs in the background).

post/api/v1/tables/{id}/imports
Scope
write
Credits
Free
Idempotency-Key
optional
Rate weight
5 requests

Upload the file first (POST .../imports/upload-url), preview it (POST .../imports/preview), then start the import with the same fileId. mapping (the preview's suggestion when omitted) maps file columns to table columns, creating new ones (create) before any row is written. dedupe sets each row's dedupe key (email, linkedin, domain or the column value) and onConflict (updateEmpty by default, overwrite, skip) applies to rows whose key exists.

The import runs in batches (500 or 1,000 rows, depending on the workspace); each batch commits its rows and its place in the file together, so an interrupted import resumes where it stopped and never writes a row twice. Poll GET .../imports/{importId} for progress and per-row errors (the first 500 are kept). With an Idempotency-Key, a repeat returns the same import. Free. Limits: 20 MB per file, 250,000 rows.

Parameters

  • idpathstringrequired

    The table id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body (required) · application/json

TableImportCreateRequest

  • fileIdstringrequired
    0
  • uploadIdstring

    From imports/upload-url (required on the file's first use).

    0
  • mappingarray of TableImportMappingEntry
    0
  • dedupeTableImportDedupe
    0
  • onConflictstring
    skipupdateEmptyoverwrite
  • encodingstring
    utf-8utf-16leutf-16bewindows-1252
  • delimiterstring
    ,;tab|
  • hasHeaderboolean
    0

Responses

200
OK.
Show schema

TableImportResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/imports" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "<fileId>"
}'

tables.imports.uploadUrl

Register a CSV upload and get a one-hour upload URL.

post/api/v1/tables/{id}/imports/upload-url
Scope
write
Credits
Free
Idempotency-Key
optional

Send the file's size (bytes, at most 20 MB) and type. POST the file body to uploadUrl with the returned headers (they carry a one-time upload token); the upload must be exactly bytes long. The JSON answer's storageId is the fileId. Preview and import it with fileId (and uploadId): only this API key (or dashboard user) in this workspace can. Registrations not used within 24 hours are deleted with their file; imported files 7 days after first use.

Parameters

  • idpathstringrequired

    The table id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body (required) · application/json

TableImportUploadUrlRequest

  • bytesintegerrequired

    The file's size; the upload must match it.

    min 1max 20971520
  • contentTypestring
    text/csvtext/plaintext/tab-separated-valuesapplication/csvapplication/vnd.ms-excelapplication/octet-streamdefault "text/csv"
  • fileNamestring
    0

Responses

200
OK.
Show schema

TableImportUploadUrlResponse

  • dataobjectrequired
    0
    + Show child fields
    • uploadIdstringrequired

      Pass it with fileId to preview and import.

      0
    • uploadUrlstringrequired
      0
    • methodstringrequired
      0
    • headersobjectrequired

      Send these headers with the upload (they tie the file to this registration).

      0
    • maxBytesintegerrequired
      0
    • expiresAtintegerrequired
      0
    • fileIdFieldstringrequired

      The field of the upload's JSON answer to pass as fileId.

      0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/imports/upload-url" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "bytes": 1
}'

tables.imports.preview

Preview an uploaded CSV: format, suggested mapping, sample rows, dedupe stats.

post/api/v1/tables/{id}/imports/preview
Scope
write
Credits
Free
Idempotency-Key
optional

Reads the first megabyte of the file. Detects the encoding (UTF-8, UTF-16 with a BOM, else Windows-1252) and the separator (, ; tab |), unless given; infers a type per column; suggests a mapping onto the table's columns (or new columns); coerces the first rows (sampleRows, default 20) with per-cell errors; and, with dedupe, counts rows without a key, duplicates within the sample and keys that already exist in the table. Writes nothing (the file is claimed for the workspace).

Parameters

  • idpathstringrequired

    The table id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body (required) · application/json

TableImportPreviewRequest

  • fileIdstringrequired
    0
  • uploadIdstring

    From imports/upload-url (required on the file's first use).

    0
  • mappingarray of TableImportMappingEntry
    0
  • dedupeTableImportDedupe
    0
  • sampleRowsinteger
    min 1max 100
  • encodingstring
    utf-8utf-16leutf-16bewindows-1252
  • delimiterstring
    ,;tab|
  • hasHeaderboolean
    0

Responses

200
OK.
Show schema

TableImportPreviewResponse

  • dataobjectrequired
    0
    + Show child fields
    • fileIdstringrequired
      0
    • tableIdstringrequired
      0
    • bytesintegerrequired
      0
    • encodingstringrequired
      0
    • delimiterstringrequired
      0
    • hasHeaderbooleanrequired
      0
    • headersarray of objectrequired
      0
      + Show child fields
      • indexinteger
        0
      • namestring
        0
      • inferredTypestring
        0
      • samplearray of string
        0
    • mappingarray of objectrequired
      0
      + Show child fields
      • sourceinteger
        0
      • headerstring
        0
      • columnKeystring
        0
      • createobject
        0
    • rowsarray of objectrequired
      0
      + Show child fields
      • rowinteger
        0
      • cellsobject
        0
      • errorsarray of object
        0
    • totalsobjectrequired
      0
      + Show child fields
      • sampledRowsinteger
        0
      • validRowsinteger
        0
      • invalidRowsinteger
        0
      • estimatedRowsinteger
        0
      • exactboolean
        0
    • dedupeobject | nullrequired
      0
      + Show child fields
      • onstring
        0
      • columnKeystring
        0
      • rowsWithKeyinteger
        0
      • rowsWithoutKeyinteger
        0
      • duplicatesInFileinteger
        0
      • existingMatchesinteger | null
        0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/imports/preview" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "<fileId>"
}'

tables.imports.get

An import's status, progress, counts and row errors.

get/api/v1/tables/{id}/imports/{importId}
Scope
write
Credits
Free
Idempotency-Key
Not used

Parameters

  • idpathstringrequired

    The table id.

  • importIdpathstringrequired

    The import id.

Responses

200
OK.
Show schema

TableImportResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/tables/$ID/imports/$IMPORT_ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Exports

tables.exports.create

Export the table, a view or a filtered selection as CSV, JSON Lines or JSON.

post/api/v1/tables/{id}/exports
Scope
write
Credits
Free
Idempotency-Key
required
Rate weight
5 requests

Runs in the background. viewId applies a saved view (its filter, sorts, column order and hidden columns); filter and sort override it; columns picks column keys in order. Poll GET .../exports/{exportId}: when status is done, downloadUrl serves the file for 24 hours (then expired). CSV is UTF-8 with a BOM, a header of column names, and text cells starting with =, +, - or @ (also after leading spaces) prefixed with '.

Metered as data.export (18 credits) once per export: held when the export is created (402 INSUFFICIENT_CREDITS if the wallet cannot cover it), charged when the file is ready, released if the export fails. credits.charged on the export reports it. Idempotency-Key required. Limits: 50,000 rows (250,000 on some workspaces; 422 LIMIT_EXCEEDED at create, nothing held). While the workspace's tables are being upgraded: 409 TABLE_MIGRATING (retry later).

Parameters

  • idpathstringrequired

    The table id.

  • Idempotency-Keyheaderstring

    1 to 255 printable ASCII characters, scoped to the API key (a rotated key shares its predecessor's keys) and kept 24 h. Accepted on every POST, PATCH and DELETE (ignored on GET); required from v1 keys where the operation says x-owlbound-idempotent: required (missing: 400 VALIDATION_ERROR, param: Idempotency-Key). Same key and body after completion: the stored response is replayed with Idempotent-Replayed: true. Results over 64 KB are not stored; their replay is 409 IDEMPOTENCY_RESULT_UNAVAILABLE with details.originalRequestId (check state with a GET). Same key while the first request runs: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Same key, other body or operation: 422 IDEMPOTENCY_KEY_REUSED. A request that ended 5xx may be retried with the same key. 4xx results are stored and replayed too: a 402 INSUFFICIENT_CREDITS replays even after a top-up, so use a new Idempotency-Key after adding credits.

    min length 1max length 255

Request body (required) · application/json

TableExportCreateRequest

  • formatstring
    csvjsonljsondefault "csv"
  • viewIdstring
    0
  • filterany

    A filter tree (the filter language).

    0
  • sortany

    Up to 3 sort keys.

    0
  • columnsarray of string
    0

Responses

200
OK.
Show schema

TableExportResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 402 Not enough credits (INSUFFICIENT_CREDITS). With an Idempotency-Key this result is stored and replayed: after adding credits, retry with a new Idempotency-Key. · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 409 IDEMPOTENCY_IN_PROGRESS (the first request with this key is still running; `Retry-After` is the lease left, at most 60 s) or IDEMPOTENCY_RESULT_UNAVAILABLE (the original result was too large to store; `details.originalRequestId`). · 422 IDEMPOTENCY_KEY_REUSED (the key was used with another body or operation), or an action that cannot run · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/tables/$ID/exports" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "format": "csv",
  "viewId": "<viewId>"
}'

tables.exports.get

An export's status and, when done, its download link (24 h).

get/api/v1/tables/{id}/exports/{exportId}
Scope
read
Credits
Free
Idempotency-Key
Not used

Parameters

  • idpathstringrequired

    The table id.

  • exportIdpathstringrequired

    The export id.

Responses

200
OK.
Show schema

TableExportResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/tables/$ID/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Models on this page

Shared objects the operations above link to. Clients must ignore fields they do not know.

TableImportMappingEntryobject

One file column: to an existing column (columnKey), to a new one (create), or skip.

  • sourceintegerrequired

    0-based column of the file.

    min 0
  • columnKeystring
    0
  • createobject
    0
    + Show child fields
    • namestring
      0
    • typestring
      textnumberbooleanselectmulti_selectdateurlemailphonejson
    • keystring
      0
  • skipboolean
    0
TableImportDedupeobject
  • onstringrequired
    emaillinkedindomaincolumn
  • columnKeystringrequired

    A mapped column whose (normalized) value is the row's dedupe key.

    0
TableImportobject
  • idstringrequired
    0
  • tableIdstringrequired
    0
  • statusstringrequired
    queuedrunningdonefailed
  • fileIdstringrequired
    0
  • optionsobjectrequired
    0
  • progressobjectrequired
    0
    + Show child fields
    • bytesReadinteger
      0
    • bytesTotalinteger
      0
    • percentinteger
      0
  • rowsSeenintegerrequired
    0
  • insertedintegerrequired
    0
  • updatedintegerrequired
    0
  • skippedDuplicateintegerrequired

    Rows whose dedupe key already existed and that changed nothing.

    0
  • rejectedintegerrequired
    0
  • errorsarray of TableImportRowErrorrequired
    0
  • errorsTruncatedbooleanrequired
    0
  • failurestring | nullrequired
    0
  • createdAtintegerrequired
    0
  • updatedAtintegerrequired
    0
  • finishedAtinteger | nullrequired
    0
TableImportRowErrorobject
  • rowintegerrequired

    Line of the file (the header is line 1).

    0
  • codestringrequired
    0
  • messagestringrequired
    0
  • columnKeystring
    0
ResponseMetaobject

Metadata on every success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMeta

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
  • dryRunboolean

    True only on a dry-run response (action operations).

    0
CreditsMetaobject
  • usednumberrequired

    Credits charged by this request. Reads are free.

    0
  • balancenumber
    0
  • estimatednumber

    Dry run only (action operations).

    0
  • availablenumber

    Dry run only (action operations).

    0
  • reservationIdstring | null

    Async operations only; the job settles this reservation.

    0
PageMetaobject

Cursor pagination. hasMore is the only end signal; pages may be short.

  • nextCursorstring | nullrequired
    0
  • hasMorebooleanrequired
    0
  • limitintegerrequired
    min 1max 200
TableExportobject
  • idstringrequired
    0
  • tableIdstringrequired
    0
  • viewIdstring | nullrequired
    0
  • formatstringrequired
    csvjsonljson
  • statusstringrequired
    queuedrunningdonefailedexpired
  • filterany
    0
  • sortsarray of any
    0
  • columnsarray of string | null
    0
  • rowCountinteger | nullrequired
    0
  • bytesinteger | nullrequired
    0
  • fileNamestring | nullrequired
    0
  • downloadUrlstring | nullrequired
    0
  • expiresAtinteger | nullrequired
    0
  • failurestring | nullrequired
    0
  • creditsobject
    0
    + Show child fields
    • reservedboolean
      0
    • chargednumber
      0
  • createdAtintegerrequired
    0
  • finishedAtinteger | nullrequired
    0

← All operations