Skip to main content
POST
Create a metadata import

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

collection_id
string<uuid>
required

The ID of the metadata collection

Body

application/json
name
string
required

Display name for the import

Required string length: 1 - 255
connector_id
string<uuid>
required

Data connector to list files from. Supported types: google-drive, dropbox, zoom, gong, recall, grain, iconik.

filters
object[]

Listing passes; empty (the default) means one unfiltered pass

Maximum array length: 20
default_mode
enum<string>
default:append

Mode used when a run does not specify one. append imports new files and retries previously-failed ones; refresh re-imports everything the filters match.

Available options:
append,
refresh
delete_missing
boolean
default:false

On refresh runs, remove files this import previously brought in that the source no longer returns. Only files imported by this import are ever removed — manually-added files and other imports are untouched.

rate_limit
integer

Upstream list requests per second. Defaults to a per-connector safe rate (e.g. gong 2, zoom 6, google-drive/dropbox 8) and is clamped to a per-connector ceiling (gong 3, iconik 12, zoom/grain/recall 10, google-drive/dropbox 20) sized to keep the whole account inside each provider's published rate budget.

Required range: 1 <= x <= 50
start
boolean
default:true

Trigger the first run immediately. false saves the definition only.

max_files
integer

Stop each run after processing this many files from the listing. A capped run stops listing at the limit and never runs the delete-missing sweep — a truncated listing is incomplete by definition, so nothing is removed based on it.

Required range: 1 <= x <= 1000000
include_thumbnails
boolean
default:false

Copy connector poster images as default thumbnails for imported files, for sources that provide one (Grain and iconik today). Off by default: iconik posters need one rate-limited API lookup per file, which materially slows large imports.

Response

The created import, with latest_run reflecting the immediately-triggered first run when applicable

A saved bulk metadata import: which connector to list, how to filter it, and how runs behave. Definitions are immutable — delete and recreate to change one.

object
enum<string>
Available options:
metadata_import
id
string<uuid>
collection_id
string<uuid>
connector_id
string<uuid>
name
string
filters
object[]

Listing passes; an empty array means one unfiltered pass. Overlapping passes are deduplicated on import.

default_mode
enum<string>

Mode used when a run does not specify one

Available options:
append,
refresh
delete_missing
boolean

Default delete-missing behavior for refresh runs

rate_limit
integer | null

Upstream list requests per second; null means the per-connector safe default. Clamped to a per-connector ceiling at run time.

created_at
number

Unix timestamp in milliseconds

latest_run
object | null

Most recent run, or null when the import has never run

max_files
integer | null

Per-run ceiling on files processed from the listing; null means unbounded

include_thumbnails
boolean

Whether runs copy connector poster images as default thumbnails for imported files (Grain and iconik today)