> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/files-api.md).

# Files API

Upload, download, and manage the files attached to Records.

The Files API stores the files attached to Records, also called Record Level Attachments. Use it to work with a file's content and metadata, run chunked upload sessions, and get transfer links. Use the [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md) to manage a Record's attachments: reserve a file on the Record, list the attachments, and delete one. Because a Files API delete doesn't update the Record's attachment list, you should delete attachments through the Native Object API. Access to a file follows the [permissions](#authentication-and-permissions) for its Record's Object Type.

To add a file to an existing Record, use both APIs in turn. Reserve the file on the Record with the Native Object API, and keep the file's `id` from the response. Then send the file's content to the Files API at the returned `uploadUrl`. When the upload finishes, the Files API adds the file to the Record's attachment list, so you don't send a separate request to link them. For details, see the [upload steps](#request-and-response-details).

## What you can do

Native Object API paths are relative to `https://native-object.<tenant-id>.my.contextual.io/api/v1`, and Files API paths are relative to the [Files API base URL](#base-url-and-reference).

| Task                                               | API                                                | Request                                                                                                                                                                                               |
| -------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Upload a file                                      | Native Object API, then Files API                  | Start with `POST /$attachments/<type-id>/<record-id>`. See the [upload steps](#request-and-response-details).                                                                                         |
| List a Record's attachments                        | Native Object API                                  | `GET /$attachments/<type-id>/<record-id>`. The response also includes reservations whose upload hasn't finished, so they aren't in the Record's attachment list yet. These items have no `meta.size`. |
| Read or change metadata                            | Files API                                          | Read with `GET /files/<attachment-id>`. To change custom fields, see the [Files API reference](https://files.prod-001.prod.contextual.io/api-docs/).                                                  |
| Download content                                   | Either API                                         | Native Object API: `GET /$attachments/<type-id>/<record-id>/<attachment-id>/content`. Files API: `GET /files/<attachment-id>/content`.                                                                |
| Transfer content without sharing your access token | Files API, or the Native Object API for a download | Request a [transfer link](#transfer-links) for a download or for the chunks of a chunked upload.                                                                                                      |
| Delete an attachment                               | Native Object API                                  | `DELETE /$attachments/<type-id>/<record-id>/<attachment-id>`. Finish other uploads to the Record first.                                                                                               |

`<type-id>` is the Object Type ID, `<record-id>` is the Record's ID, and `<attachment-id>` is the file's `id`.

Call these APIs from backend services and scripts.

{% hint style="warning" %}
**Finish other uploads to the same Record before deleting an attachment.** List the Record's attachments to check for unfinished uploads; an item without `meta.size` hasn't finished uploading. If another upload is pending, deletion can remove the file and then return `400` without updating the Record's attachment `ids`, `count`, and `size`.
{% endhint %}

## Base URL and reference

* **API base URL:** `https://files.prod-001.prod.contextual.io/api/v1`
* **Swagger reference:** [Files API reference](https://files.prod-001.prod.contextual.io/api-docs/)
* **Raw OpenAPI:** [openapi.json](https://files.prod-001.prod.contextual.io/api-docs/openapi.json)

Use the API base URL as written. `prod-001` is part of the shared Files API hostname, not a tenant ID. Because the hostname doesn't identify your tenant, operations under `/api/v1` need the header `x-org-id: <tenant-id>`, except for [transfer links](#transfer-links). Replace `<tenant-id>` with the [tenant ID from your Tenant Workspace URL](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#identify-the-tenant). Without the header, these operations return `400` with the code `organization_required`. Use upload URLs and transfer links exactly as the API returns them.

## Authentication and permissions

Send an access token from a tenant API Key in the `Authorization: Bearer <access-token>` header. To get one, follow [Get an access token](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#get-and-use-an-access-token). [Transfer links](#transfer-links) use a different header.

The Files API has no permission of its own. It checks the key's **Object data & action execution** permission for the Object Type of the file's Record. Set it on the key's [Permissions tab](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/authentication-and-permissions.md#assign-permissions).

| Task                                                                               | Permission for the Record's Object Type |
| ---------------------------------------------------------------------------------- | --------------------------------------- |
| Read metadata, download content, or get a download transfer link                   | **Read**                                |
| Add an attachment, upload content, get an upload transfer link, or change metadata | **Update**                              |
| Complete a chunked upload                                                          | **Read** and **Update**                 |
| Delete an attachment through the Native Object API                                 | **Delete** and **Update**               |

Deleting an attachment requires **Delete** for the Native Object API request and **Update** for the Files API call that removes the file. Both APIs check your token.

## Request and response details

Metadata is JSON. A file has an `id`, a `filename`, and `meta` with its `contentType`, `size`, and any custom fields. `_metaData.ref` identifies the Record by `typeId` and `instanceId`.

To upload a file:

1. Reserve an attachment with the Native Object API. You can send a body such as `{"meta": {"contentType": "application/pdf"}}`. The response has the file's `id` and its `uploadUrl`, shown below as `<upload-url>`.
2. Next, `POST` the file to `<upload-url>` as `multipart/form-data`, with exactly one file. Send your access token and `x-org-id`. A single upload can be up to 100 MB. The Files API then adds the file to the Record's attachment list automatically.

An unused reservation expires, so start the upload soon after you reserve it. A multipart `POST` to the upload URL returns `404` after the reservation expires, and also after the file is uploaded. `GET /files/<attachment-id>` can return `200` for a reservation before its upload, so a `200` doesn't show that the upload finished. To confirm that an upload finished, check that the Record's `_metaData.attachments.ids` includes the file's `id`.

If the response in step 1 includes `resumable`, you can instead upload a file of up to `resumable.maxBytes` in chunks. Send each of these requests with your access token and `x-org-id`:

1. Start an upload session with `POST <upload-url>/uploads`. Send a JSON body with the file's `filename`, `size` in bytes, `contentType`, and `lastModified` in milliseconds since January 1, 1970 (UTC). The response has the session's `id`, shown below as `<session-id>`, and its `chunkSize`.
2. Upload each chunk with `PUT <upload-url>/uploads/<session-id>/chunks/<index>`, where `<index>` starts at `0`. Each chunk is `chunkSize` bytes, except the last one, which can be smaller. Send the bytes as `application/octet-stream`, with their lowercase hex SHA-256 hash in `x-chunk-sha256`. To let another process send the chunks, use an [upload transfer link](#transfer-links).
3. Complete the upload with `POST <upload-url>/uploads/<session-id>/complete`. The Files API then adds the file to the Record's attachment list.

To resume an upload, send the request from step 1 again with the same body. The API returns the active session. To see which chunks the API already has, send `GET <upload-url>/uploads/<session-id>` and read `parts`. Upload only the missing chunks. You can safely send a chunk again with the same bytes. The session expires at the `expiresAt` in its response.

### Transfer links

A transfer link is a short-lived URL plus the headers to send with it. Use a transfer link to let another process download one file or upload the chunks of one session without sharing your application's broader API access token.

For example, your backend can authorize an attachment download and give an export job the returned URL and headers. The job can download that file until the authorization expires, but it cannot use those credentials to manage Records, get new links, or make unrelated API requests.

For uploads, your backend creates the upload session, gives a helper the transfer link to upload chunks, and completes the upload using its own access token. The helper's transfer credentials cannot complete the upload.

If the same trusted backend already holds the access token and transfers the file itself, ordinary authenticated upload and download requests are usually sufficient.

Request a transfer link with your access token:

* **Download:** `POST /files/<attachment-id>/download-intents`, or `POST /$attachments/<type-id>/<record-id>/<attachment-id>/download-intents` on the Native Object API.
* **Upload:** `POST <upload-url>/uploads/<session-id>/transfer-intents`, where `<session-id>` is the `id` of your chunked upload session.

Call the returned `url` with exactly the returned `headers`. They include `Authorization: Transfer <transfer-token>` in place of your Bearer token, and you don't need `x-org-id`. Because each request requires those headers, a transfer link doesn't work as a plain link in a browser. Reuse the link until `expiresAt`, five minutes after it was issued.

* For non-empty downloads, send a `Range` header no larger than the returned `chunkSize`. If the file changes, request a new link.
* For uploads, `PUT` each chunk to the `url`, with `{index}` replaced by the chunk number. Include `Content-Type` and `x-chunk-sha256` as in a chunked upload. Complete the upload with your access token.

Keep links and their headers secret and out of logs. Share them only with a person or process authorized to transfer the file. Anyone who obtains the URL and headers can use the transfer while the link remains valid. Disabling the API Key used to request the link, or changing that key's permissions, does not immediately invalidate the link.

## Example request

This request reads one file's metadata:

```bash
curl "https://files.prod-001.prod.contextual.io/api/v1/files/<attachment-id>" \
  --header "Authorization: Bearer <access-token>" \
  --header "x-org-id: <tenant-id>"
```

Replace `<attachment-id>` with a file's `id`, for example from a Record's attachment list. Replace `<access-token>` with your access token. A successful response has status `200` and the file's metadata.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/files-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
