--- title: "Upload a file to a project" method: POST path: "/api/v1/file/upload/{ownerId}/{userId}/{projectId}/{connectionId}/{parentId}" tags: ["Files"] --- # Upload a file to a project `POST /api/v1/file/upload/{ownerId}/{userId}/{projectId}/{connectionId}/{parentId}` ## Request - Base URL: `https://davinci-app.com` - URL: `https://davinci-app.com/api/v1/file/upload/{ownerId}/{userId}/{projectId}/{connectionId}/{parentId}` - Auth: HTTP bearer Sends a file to the machine holding your project and attaches it under `parentId` in the parts tree. Send this to `dataPlane.url`, not to the control-plane host, with `Authorization: Bearer {dataPlane.token}`. Supply the session's own `dataPlane.connectionId` as `connectionId`; the upload is applied through the session's live connection, so any other value is rejected. Bodies up to 2 GB are accepted and streamed rather than buffered. Word and PowerPoint files become an editable Davinci document or slide deck by default. Set `officeImport` to `pdf` to bring them in as a PDF instead, or `keepAsReference` to attach the original file unconverted. Older .doc and .ppt files are attached as they are unless `officeImport` is `pdf`. ## Request body `multipart/form-data` - UploadFileRequest - `file` string, binary, required - `objectName` string: Display name for the created object. Defaults to the filename. - `keepAsArchive` boolean: 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. - `officeImport` 'native' | 'pdf': How a Word (.docx) or PowerPoint (.pptx, .pptm, .ppsx, .ppsm, .potx, .potm) file comes in. `native`, the default, converts it into an editable Davinci document or slide deck. `pdf` converts it to a PDF first, which then becomes a PDF reference with a page image per page, as an uploaded PDF does. Older .doc and .ppt files can only be converted to PDFs: `pdf` converts them, and otherwise they are attached as references. Other file types ignore it. When it is omitted and a Word file cannot be converted, the file is attached as a reference instead. When it is set and the conversion fails, the upload fails: `422` when the file cannot be converted, `503` or `504` when the converter is unavailable or too slow. - `keepAsReference` boolean: Attach the file exactly as uploaded, as one reference, without converting it: for example the original Word or PowerPoint file rather than a document, slides or a PDF. Takes precedence over `officeImport`. ## Response `200` The file was stored and attached. - UploadFileResponse: 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, a Word file a document with its tables and pictures, a PowerPoint file a slide deck with its pictures and tables, 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 ## Other responses - `400`: `officeImport` is neither `native` nor `pdf`. Error code is `INVALID_OFFICE_IMPORT`. - `401`: The grant is missing, unknown, expired, or revoked. These are one response so a rejected request cannot be used to learn which grants exist. Refresh the session to get a new grant, or create a new session if that also fails. - `403`: The grant does not carry `documents:write` on this project. - `409`: The project moved to another machine. Error code is `PROJECT_MOVED`. Retry the request: the next one resolves to the machine holding it now, at the same URL. - `413`: The file exceeds the maximum upload size. - `422`: The Word or PowerPoint file could not be converted as `officeImport` asked. Error code is `OFFICE_CONVERSION_FAILED` or `WORD_IMPORT_FAILED`. - `429`: Request rate exceeded, either globally or for this key. - `500`: Unexpected server error. - `503`: The converter `officeImport` needs is unavailable. Error code is `OFFICE_CONVERSION_UNAVAILABLE` or `WORD_IMPORT_UNAVAILABLE`. - `504`: The conversion `officeImport` asked for did not finish in time. Error code is `OFFICE_CONVERSION_TIMED_OUT`. ## Changes - **2026-11-04** (v2) `279218ca2e8d`: 6 info - added the new optional request property `keepAsReference` - added the new optional request property `officeImport` - added the non-success response with the status `400` - added the non-success response with the status `422` - …2 more - **2026-09-15** (v2) `67c8b8616dbb`: 6 info - the `success` response property const value `false` was added for the status `401` - the `success` response property const value `false` was added for the status `403` - the `success` response property const value `false` was added for the status `409` - the `success` response property const value `false` was added for the status `413` - …2 more - **2026-09-15** (v2) `48948af37797`: 1 info - endpoint added [Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v1/file/upload/:ownerId/:userId/:projectId/:connectionId/:parentId/post.md) --- [API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)