Skip to main content
POST
Preview. This endpoint is available to organisations in the Wordsmith MCP and files pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.
Turns an upload into a file and returns it. The response’s id is the file’s file_id, which the other files endpoints and Attach Files take. An upload takes three calls:
  1. Call Upload URL. It returns upload_url and job_id.
  2. PUT the file’s bytes to upload_url, with a Content-Type header equal to the content_type you sent.
  3. Call this endpoint with the job_id as upload_id.
The file lands in your private space. Only the user who created the upload can complete it, and only while they may still upload files. Completing is safe to retry. Completing the same upload again returns the same file, for up to an hour. Two concurrent requests also get the same file: the second waits up to 10 seconds for the first to finish. If the first is still running after that, the second gets 409 upload_completion_in_progress; retry it. If Wordsmith has not received the bytes yet, the response is 400 upload_not_received and the upload stays open. PUT the bytes, then complete again. An upload is used once. After you complete it, attach the file by its file_id, not the job_id. A job_id already used as an upload_job_id attachment cannot be completed.

​
Authentication

Send an API key, or an OAuth access token with the files:write scope, as a bearer token in the Authorization header. A token without the scope gets 403 with "error": "insufficient_scope".

​
Path parameters

​
string (uuid)
required
The job_id that Upload URL returned.

​
Response

Returns 200 with the file.
​
string (uuid)
The file’s id: the file_id other endpoints take.
​
string | null
The file’s name.
​
string | null
The file’s MIME type.
​
integer | null
Size in bytes.
​
string | null
When the file was created. ISO 8601 UTC.

​
Errors

See Errors for the error format.