CSV imports

Start file import

POST /v1/lookup-tables/imports

Starts importing a CSV file of this many bytes into a table, or into a new table when table_id is null, optionally with the whole file's sha256. Needs an API key that can write every field of the table; a new table also needs table settings access to every table. Then send the file in parts with the part upload, from a program: never as tool arguments. With a shell, send the file with the API's part upload (PUT, raw bytes); without one, create an upload request and give the person its link. If another import into the table is unfinished, cancel it first.

Requires lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: create_lookup_import. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
table_id	JSON body	Yes	string (uuid) or null
bytes	JSON body	Yes	integer
sha256	JSON body	No	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
201	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Get file import

GET /v1/lookup-tables/imports/{import_id}

Gets an import this key started: its state, the parts that have arrived, the file's columns, the preview's counts and progress.

Requires lookup_tables:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_lookup_import. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Upload file part

PUT /v1/lookup-tables/imports/{import_id}/parts/{part}

Sends one part of the file as raw bytes (Content-Type: application/octet-stream), numbered from 0, with its exact Content-Length. Every part is part_bytes long except the last, which holds the rest of the file. Sending a part again with the same bytes changes nothing; different bytes are refused. After an interruption, get the import and send the parts not in received_parts. When every part has arrived, check the uploaded file.

Requires lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

Upload the file part through REST from a program, using Content-Type: application/octet-stream and the exact Content-Length. Send raw bytes rather than a JSON body or text generated by an assistant. An assistant without a shell can request a file upload for someone to complete in Neon Deer.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string
part	path	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import_part"	Yes
data.import_id	string	Yes
data.part	integer	Yes
data.received	true	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Check uploaded file

POST /v1/lookup-tables/imports/{import_id}/complete

Says every part of the file has arrived, so the file is read. Get the import until it is inspected.

Requires lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: request_lookup_import_check. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Preview file import

POST /v1/lookup-tables/imports/{import_id}/preview

Chooses how the file's columns fill the table, by the lookup that matches rows, or the new table's name and column types, and checks every row. Get the import until it is previewed, then apply that preview's generation.

Requires lookup_tables:read and lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: prepare_lookup_import. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string
lookup_id	JSON body	No	string (uuid)
columns	JSON body	No	array of object
columns[].column	Within the JSON value	Within this object	integer
columns[].field_id	Within the JSON value	Within this object	string (uuid)
clear_empty_cells	JSON body	No	boolean
new_table	JSON body	No	object
new_table.name	Within the JSON value	Within this object	string
new_table.types	Within the JSON value	Within this object	array of "text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"
new_table.lookup_column	Within the JSON value	Within this object	integer
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Apply file import

POST /v1/lookup-tables/imports/{import_id}/apply

Imports the file as the preview with this generation described it: rows are added and updated, and with clear_empty_cells, values are cleared. If the table changed since, check the file again. Rows already imported stay if the import is canceled. Values it replaces are not kept, so it can't be undone.

Requires lookup_tables:read and lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: start_lookup_import. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string
generation	JSON body	Yes	integer

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Request file upload

POST /v1/lookup-tables/import-upload-requests

For an AI app without a shell: gives a link where a person who manages the organization's lookup tables chooses a CSV file to import into a table, or into a new table when table_id is null. Give the person upload_url; it works until expires_at. Get the upload request until it is uploaded, then get its import (import_id) and preview it. Needs the same access as starting an import.

Requires lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: create_lookup_import_upload_request. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
table_id	JSON body	Yes	string (uuid) or null

Response

HTTP status	Result
201	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import_upload_request"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"waiting", "uploading", "uploaded", "expired"	Yes
data.upload_url	string	Yes
data.expires_at	string	Yes
data.import_id	string or null	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Get file upload request

GET /v1/lookup-tables/import-upload-requests/{upload_request_id}

Gets an upload request this key made: whether the person has sent the file, and the import it started (import_id).

Requires lookup_tables:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_lookup_import_upload_request. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
upload_request_id	path	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import_upload_request"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"waiting", "uploading", "uploaded", "expired"	Yes
data.upload_url	string	Yes
data.expires_at	string	Yes
data.import_id	string or null	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Cancel file import

DELETE /v1/lookup-tables/imports/{import_id}

Stops an import this key started. Rows already imported stay.

Requires lookup_tables:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: cancel_lookup_import. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
import_id	path	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"lookup_import"	Yes
data.id	string	Yes
data.table_id	string or null	Yes
data.state	"uploading", "uploaded", "inspected", "previewed", "applying", "applied", "failed", "canceled", "expired"	Yes
data.working	boolean	Yes
data.problem	string or null	Yes
data.cancel_requested	boolean	Yes
data.parts	integer	Yes
data.part_bytes	integer	Yes
data.received_parts	array of integer	Yes
data.records	integer or null	Yes
data.columns	array of object or null	Yes
data.columns[].column	integer	Yes	Alternative 1.
data.columns[].name	string	Yes	Alternative 1.
data.columns[].suggested_type	"text", "number", "boolean", "date", "timestamp", "email", "phone", "domain", "url", "member", "record"	Yes	Alternative 1.
data.preview	object or null	Yes
data.preview.generation	integer	Yes	Alternative 1.
data.preview.rows	integer	Yes	Alternative 1.
data.preview.creates	integer	Yes	Alternative 1.
data.preview.updates	integer	Yes	Alternative 1.
data.preview.unchanged	integer	Yes	Alternative 1.
data.preview.not_added	integer	Yes	Alternative 1.
data.preview.clear_count	integer	Yes	Alternative 1.
data.preview.error_count	integer	Yes	Alternative 1.
data.preview.table_changed	boolean	Yes	Alternative 1.
data.progress	object	Yes
data.progress.records	integer	Yes
data.progress.total	integer	Yes
data.progress.created	integer	Yes
data.progress.updated	integer	Yes
data.progress.cleared	integer	Yes
data.progress.not_added	integer	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

The public OpenAPI document lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the API Playground to inspect a real response with your connection's access.