---
title: "Upload a file"
method: POST
path: "/v1/projects/{project_id}/files"
tags: ["StoredFile"]
---

# Upload a file

`POST /v1/projects/{project_id}/files`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/files`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Uploads a file to be stored by Telerivet.

 After uploading a file, it can be attached to an outgoing message by passing its ID as a `file_id` item in the `media` parameter of project.sendMessage, project.sendBroadcast, or project.sendMulti. This makes it possible to upload a media file once and attach it to many messages, instead of including the file content in every API request.

 The file content is provided inline via the `data` parameter, encoded via Base64, with a maximum decoded file size of 5 MB. Image, video, audio, PDF, and vCard files are supported.

 Files are deduplicated by content: if a file previously uploaded via the API in the same project has the same content and MIME type, the existing stored file is returned instead of creating a duplicate.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `data` string, required: Base64-encoded file content (max 5 MB decoded). Alternatively, a Base64 data URI such as `data:image/jpeg;base64,...`, in which case the `type` parameter may be omitted.
  - `filename` string: Filename of the stored file. If not provided, the filename is generated automatically.
  - `type` string: MIME type of the file, e.g. `image/jpeg`. If `data` is a data URI, the type may be omitted, but must match the MIME type of the data URI if provided.
  - `description` string: Description of the file
  - `vars` object: Custom variables to store with the file

## Response `200`

Successful response

- StoredFile: Represents a file stored in a Telerivet project, such as a media attachment for outgoing messages. Stored files are also automatically created for media attachments for incoming messages. Files can be uploaded via project.uploadFile, then attached to outgoing messages by passing the file ID as a `file_id` item in the `media` parameter when sending a message or broadcast.
  - `id` string: ID of the stored file
  - `filename` string: Filename of the stored file
  - `type` string: MIME type of the file
  - `size` integer: Size of the file in bytes
  - `description` string, nullable: Description of the file
  - `vars` object: Custom variables stored for this stored file. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `category` 'outgoing_media' | 'incoming_media' | 'call_audio' | 'test_recording' | 'script_module' | 'icon': Category of the stored file
  - `source` 'upload' | 'recording' | 'message' | 'api': How the stored file was created
  - `message_id` string, nullable: ID of the message associated with this file, if any. Files associated with a message are deleted automatically when the message is deleted.
  - `sha256` string, nullable: SHA-256 hash of the file content (lowercase hex), if available
  - `time_created` integer: Time the file was created in Telerivet
  - `user_id` string, nullable: ID of the Telerivet user who created the file (if applicable)
  - `url` string: URL where the file content can be downloaded. Note: this URL is temporary and may not be valid for more than 1 day; retrieve the stored file again to get a fresh URL.
  - `thumbnail_url` string, nullable: URL of a thumbnail image for video files, if available. Note: this URL is temporary and may not be valid for more than 1 day.
  - `project_id` string: ID of the project this file belongs to

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)