---
title: "Upload a file"
method: POST
path: "/v1/{appId}/files"
tags: ["Files"]
---

# Upload a file

`POST /v1/{appId}/files`

## Request

- Base URL: `https://api.talkjs.com`
- URL: `https://api.talkjs.com/v1/{appId}/files`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
- TypeScript: <https://skmtc.dev/talkjs/apis/talkjs-api/docs/v1/:appId/files/post.ts> (a function with typed inputs; its response is checked against the schema)

Uploads a file—such as an image, video, audio file, or document—to the TalkJS servers, so that you can attach the file to a message.

You can only send content of the type `multipart/form-data` to this endpoint, not a JSON payload.

For information on how upload a file over HTTP, check the docs of your favorite HTTP client. For example: 
  - [JavaScript](https://stackoverflow.com/a/40826943/103395)
  - [Python (Requests)](https://requests.readthedocs.io/en/latest/user/quickstart/#post-a-multipart-encoded-file)
  - [PHP](http://code.stephenmorley.org/php/sending-files-using-curl/)
  - [Ruby (RestClient)](https://github.com/rest-client/rest-client#multipart)

When uploading a file, you'll receive an `attachmentToken` in response to your request. To send a message with the uploaded file as an attachment, use the 'Send a message' resource and include the `attachmentToken` when sending the message.  

### Troubleshooting

If you get a 400 Bad Request response, try the following:

- Check if your code is explicitly setting a `Content-type: multipart/form-data` header. If so, **remove it**. Most HTTP libraries autogenerate this header when uploading files, and they will usually set the header to something like `Content-Type: multipart/form-data; boundary=a3eb698cd620e766f278e52886c572edcb0e4a97`. TalkJS requires the boundary to parse the data.
- Make sure that the file you're trying to upload has a `filename` directive set. Many HTTP libraries do this automatically, or allow you to set it explicitly. Setting a filename directive causes the library to generate a header, such as `Content-Disposition: form-data; file="This is a txt file."; filename="sample.txt"` inside the HTTP body. Many HTTP libraries allow you to give an uploaded file a filename.

If you get a 500 Server Error response, reach out through [live support chat](https://talkjs.com/?chat).

## Path parameters

- `appId` string, required

## Request body `multipart/form-data`

- UploadFile: Details of a file to upload
  - `file` string, binary, required: File data to upload
  - `filename` string, required: Name of the file to upload

## Response `200`

File uploaded successfully.

- AttachmentToken: Attachment token
  - `attachmentToken` string: Attachment token. Use this token to identify a file to attach to a message. To obtain an attachment token, first upload the file with the 'Upload a file' resource.

## Other responses

- `400`: Bad request
- `401`: Authorization information is missing or invalid.
- `404`: Resource not found
- `429`: Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/talkjs/apis/talkjs-api.md) - [All operations](https://skmtc.dev/talkjs/apis/talkjs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talkjs/apis/talkjs-api/revisions/9d4acc9cfa43?raw)