Skip to main content
POST
cURL

Authorizations

Authorization
string
header
default:dav_gr_your_grant
required

A session's data-plane grant, from dataPlane.token. Valid only on the data-plane host, only for the one project its session opened, and only for minutes.

A grant is not an API key and the two are not interchangeable: presenting a grant to a control-plane operation is rejected, and an API key is not accepted on the data plane. The separation is deliberate — a grant is meant to be cheap to lose, so it reaches one project, does no more than the key that minted it, and is revoked when its session closes.

Path Parameters

ownerId
string
required

Id of the account or organization that owns the project, from the project's ownerId.

Minimum string length: 1
userId
string
required

Acting user id. Ignored for authorization — the acting identity comes from the grant, so this cannot be used to act as someone else.

Minimum string length: 1
projectId
string
required

Project id, compound as {projectId}--{branchName}. Must be the project the session opened.

Minimum string length: 1
connectionId
string
required

The session's dataPlane.connectionId, which is headless-{sessionId}. Send what the session gave you and this is the only value you will ever need.

What the server actually requires is the headless- prefix, and the difference matters in one place: a Code object addresses the data plane with headless-exec-{executionId}, because an execution holds a grant rather than a session. The prefix is what makes the upload be applied through a client, so the reference joins the parts tree instead of the bytes landing in storage with nothing pointing at them. An id naming no live connection is served by an ephemeral one.

Pattern: ^headless-
parentId
string
required

Id of the parts-tree object the file is attached under.

Minimum string length: 1

Body

multipart/form-data
file
file
required
objectName
string

Display name for the created object. Defaults to the filename.

keepAsArchive
boolean
default:false

Preserve a ZIP or 7z upload as one archive reference instead of extracting it immediately. Set this when the archive will be passed to session.extract_archive() later.

Response

The file was stored and attached.

The objects the upload created, keyed by id.

One file does not always mean one object. A STEP assembly becomes a tree, a PDF becomes a document plus a page image per page, and a source file becomes a code object — so the answer is a map rather than a single record. A plain file that needs no conversion yields exactly one entry.

object
object
required