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

# Upload and manage filing documents

> Upload files to the filing's Mission Control and add them as scheduled or unscheduled filing items.

Complete the [authentication setup](/guides/managed-filings#authenticate). Use a
write-capable user key with MC and filing edit access. The MC must have
`filing_items` registered. Set `FILING_ID` to the ID of your managed filing.
The shell examples use Bash, curl, and jq.

## Choose the upload location and owner

Read `GET /api/v2/managed-filings/{filingId}`. Set `FILING_SCOPE` to the returned
`scope`, including its `mc:` prefix. Use it to initialize uploads for this filing.

To match the native filing Documents tab, use:

* `targetUri: "@mc/Documents"`: the Documents folder in the selected MC.
* `scope: "mc:<MC UUID or stable slug>"`: selects the MC for `@mc` in v2.
* `ownerType: "records.filings"` and `ownerId: <filing UUID>` on each uploaded file:
  associates the artifact with the filing record.

Use these values for new filing documents instead of a personal Vault folder.
The upload API calls the record relationship `ownerType`/`ownerId`, not
`parentType`. The server derives the artifact's folder `parentId` from
`targetUri`; do not put the filing ID in that field.

The general upload API also supports non-MC destinations. Send `scope` only
for `@mc` destinations. V2 uploads do not use an MC header; completion uses
the destination captured in the upload token.

## Upload a document

Save this filing-specific request as `upload-request.json`:

```bash theme={null}
FILE_SIZE=$(wc -c < form.pdf | tr -d '[:space:]')
cat > upload-request.json <<EOF
{
  "targetUri": "@mc/Documents",
  "scope": "${FILING_SCOPE}",
  "onConflict": "rename",
  "files": [{
    "path": "form.pdf",
    "size": ${FILE_SIZE},
    "mimeType": "application/pdf",
    "type": "file",
    "ownerType": "records.filings",
    "ownerId": "${FILING_ID}"
  }]
}
EOF
```

Follow the shared [Vault upload steps](/guides/vault/upload-files#upload-the-file)
using this request and `form.pdf`:

1. `POST /api/v2/files/uploads`: initialize the upload.
2. PUT the bytes to the returned signed URL.
3. `POST /api/v2/files/uploads/complete`: confirm the upload and save the
   successful result's `artifact.id` and `artifact.name`.

Then add that artifact to a filing item below. The Vault guide covers returned
headers, partial failures, expiry, and retry behavior.

Repeat this flow for related documents such as redlines. Give each new file the
same filing owner. Filing-owned uploads can appear in the native Documents tab
without a schedule assignment. Uploading a file does not create a filing item.

## Add a filing item

Call `POST /api/v2/managed-filings/{filingId}/items` with
`Content-Type: application/json` and the uploaded artifact IDs:

```json theme={null}
{
  "artifactId": "<uploaded form UUID>",
  "scheduleType": "form",
  "scheduleSeqNo": 1,
  "attachments": [
    { "artifactId": "<uploaded redline UUID>", "artifactName": "<completed redline artifact.name>" }
  ]
}
```

Use `artifactId` and `artifactName` from the same successful completion result
(`artifact.id` and `artifact.name`). Do not reuse the requested filename: Vault
may rename `redline.pdf` to `redline (1).pdf` when a file with that name exists.

The `201` response contains the created item. Save its `id` for updates.
Omit `attachments` when there are no related documents. Omit both schedule
fields to add preparation notes or other unscheduled working items.

The artifact's owner identifies its record relationship. The filing item stores
the working document reference and any schedule position. Adding an item is not
a substitute for setting the upload location and owner.

Existing documents may belong to another record, such as a form edition. They
can be referenced without changing their owner if the caller has the required
access. The server checks access to every attached file. Working attachments
follow the file's current content; submission recording pins versions later.

## List filing items

Use `GET /api/v2/managed-filings/{filingId}/items?limit=50`. The response contains
`items` and `nextCursor`. Follow `nextCursor` with the same filing and limit until null.
Item cursors expire after 24 hours.
This lists filing items, not every filing-owned Vault document. Reading an item
does not itself grant permission to read its file bytes.

## Update or remove an item

* `PATCH /api/v2/managed-filings/{filingId}/items/{itemId}`: send a new
  `artifactId` to replace the working file reference. Send both schedule fields
  as null to remove an assignment, or both values to assign a position. Updating
  an item does not change retained submission contents.
* `DELETE /api/v2/managed-filings/{filingId}/items/{itemId}`: remove the item.
  Returns `204`, retains file bytes, and rejects removal when dependencies
  require the item. A repeated delete returns `404`.

Add requests are not idempotent. After a lost response, inspect the item list
before retrying. Updates use last-write-wins semantics; read current values
before editing. These calls neither stage nor submit to SERFF.

Next, [comment on the filing or a document version](/guides/managed-filings/comments).
See [error recovery](/guides/managed-filings#recover-from-errors) for failed requests.


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