> ## Documentation Index
> Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload files

> Prepare a file upload, send bytes to storage, and confirm the stored file.

Use [connection setup](/guides/index#connect-once) for authentication and request
conventions. Use a write-capable user key with access to the destination.
The example uploads a local PDF named `form.pdf`.

## Choose the destination

* `personal://Documents`: your personal Documents folder.
* `team://Documents`: the team's Documents folder, subject to your access.
* `@mc/Documents`: the Documents folder in an authorized scope. Include `scope: "mc:<UUID or stable slug>"`.

Send `scope` only for `@mc` destinations, in the request body. For
`artifact://` writes, use a storage root ID plus a relative path, not an ordinary
folder ID. Alternatively, provide `sessionId` instead of `targetUri` to upload
to a session folder.

Location and record ownership are separate. To create a record-owned document,
include `ownerType` and `ownerId` on each file. For filings, use the
[filing destination and ownership example](/guides/managed-filings/manage-documents#upload-a-document)
then continue at [Upload the file](#upload-the-file).

## Prepare the request

Initialize an upload to your team's Documents folder. Replace `12345` with the
file's actual byte count. For a filing document, use the linked filing-specific
request instead.

```http theme={null}
POST /api/v2/files/uploads
Content-Type: application/json

{
  "targetUri": "team://Documents",
  "onConflict": "rename",
  "files": [{
    "path": "form.pdf",
    "size": 12345,
    "mimeType": "application/pdf",
    "type": "file"
  }]
}
```

The response contains `targetUri` and `files[]` with `path`, `signedUrl`,
optional `headers`, `expiresAt`, and `uploadToken`. `rename` preserves an
existing file with the same name; it does not replace that file or its version.
If you choose `onConflict: "fail"`, inspect `conflicts[]`: those files are
excluded from the PUT instructions.

## Upload the file

Send the PDF bytes to `files[0].signedUrl`, using exactly the returned
`files[0].headers`. The body is the raw file, not JSON or multipart form data:

```http theme={null}
PUT {signedUrl}

<raw bytes of form.pdf>
```

Do not send the Effective bearer credential to storage. Continue only after
the PUT succeeds.

Complete the upload using `files[0].uploadToken` from initialization:

```http theme={null}
POST /api/v2/files/uploads/complete
Content-Type: application/json

{
  "confirmations": [{ "uploadToken": "<uploadToken from initialization>" }]
}
```

Check every `results[].success`, even when HTTP status is `200`. A successful
result contains `uri` and `artifact` (the stored file details). Save `artifact.id`
to reference the file and `artifact.name` for its stored name, which may differ
from the requested name.

A failed result contains `error.code` and `error.message`. For example,
`NOT_FOUND` means the uploaded file was not found; `EXPIRED` means the token
expired. Do not use a failed upload as a file reference. The token carries the
owner fields from initialization; do not resend them or `scope` in the completion body.

Both API calls accept batches of up to 100 files and JSON bodies up to 1 MiB.
File bytes go in the PUT, not the JSON. Complete before the token expires after
one hour, and use the signed URL before its returned `expiresAt`.
Neither initialization nor completion is idempotent. After a lost response,
inspect the destination folder before retrying: repeating completion can
create another version. Completion schedules indexing; it does not wait for
searchable text.

Upload completion creates or updates the stored file. It does not create
application records such as filing items. To add a completed file to a filing,
continue with [Add a filing item](/guides/managed-filings/manage-documents#add-a-filing-item).

See the full [initialization](/api-reference/files/prepare-file-uploads) and
[completion](/api-reference/files/confirm-uploaded-files) API references for schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.