Skip to main content
POST
Import file through agent workflow

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

project_id
string
required
file_id
string
required

Body

application/json
instructions
string | null

Optional guidance for the import (e.g. how to interpret columns).

chat_id
string | null

Existing conversation to run the import in; a new one starts when omitted.

title
string | null

Optional title for the import conversation.

Response

Server-Sent Events stream of agent activity.

Each event is a UTF-8 line prefixed with event:, id:, or data: per the SSE spec. The data: payload is a JSON object with the shape {"type": <event_type>, "sequence": <int>, "data": <object>}.

Event types emitted by the agent:

  • status — high-level progress; data.message (queued/running text) or data.summary (short status line). When the conversation was busy and the message was queued (request field on_busy: "queue"), the first event is status with data.message: "queued" (or "held" if a Stop has already paused the queue), data.queuedMessageId, data.position, data.behindMessageId, data.held, and data.revision; the reply then streams once the queued turn dispatches. A held queue does not run until it is resumed.
  • queue.updated — the waiting message's queue state changed; data.position, data.held, data.revision, data.queuedMessageId. held: true means a Stop paused the queue: the message will not run until the queue is resumed (POST .../queue/resume). revision only moves forward; ignore any snapshot older than one you hold.
  • tool.started — agent invoked a tool; data.id, data.name
  • tool.input — tool input arguments; data.id, data.name, data.input
  • tool.completed — tool finished; data.id
  • message.delta — incremental assistant text; data.text (append in order)
  • done — terminal event; data.messageId, data.content (final assistant message), data.status (complete / error / cancelled)
  • error — terminal error; data.code, data.message. A queued message may end with code: "queue_wait_timeout" after 30 minutes of waiting — the message is still queued and can be observed again via the queue endpoints.

Resumability: when the connection drops before done, the same stream can be resumed via GET /v1/projects/{project_id}/conversations/{chat_id}/messages/{message_id}/events. Before a queued message has bound an assistant message id, reconnect by re-sending with the same idempotency_key, or poll GET /v1/projects/{project_id}/conversations/{chat_id}/queue/{queued_message_id}.