# media
## Upload media as attachment
`POST` `https://mastodon.example/api/v1/media`
Creates an attachment to be used with a new status.\
\
**Returns:** Attachment\
**OAuth:** User token + `write:media`\
**Version history:**\
0.0.0 - added\
2.3.0 - add `focus` parameter
#### Headers
| Name | Type | Description |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \ |
#### Request Body
| Name | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------- |
| file | object | The file to be attached, using multipart form data. |
| description | string | A plain-text description of the media, for accessibility purposes. |
| focus | string | Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0 |
{% tabs %}
{% tab title="200 Attachment created successfully. Note that the Attachment will be created even if the file is not understood correctly." %}
{% tabs %}
{% tab title="file correct" %}
```javascript
{
"id": "22348641",
"type": "image",
"url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/cebc6d51be03e509.jpeg",
"preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/cebc6d51be03e509.jpeg",
"remote_url": null,
"text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ",
"meta": {
"focus": {
"x": -0.69,
"y": 0.42
},
"original": {
"width": 640,
"height": 480,
"size": "640x480",
"aspect": 1.3333333333333333
},
"small": {
"width": 461,
"height": 346,
"size": "461x346",
"aspect": 1.3323699421965318
}
},
"description": "test uploaded via api",
"blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}
```
{% endtab %}
{% tab title="file not correct" %}
```javascript
{
"id": "22348456",
"type": "unknown",
"url": "https://mastodon.social/files/original/missing.png",
"preview_url": "https://mastodon.social/files/small/missing.png",
"remote_url": null,
"text_url": "https://mastodon.social/media/Ao2nvQoQNHROpKgEyoA",
"meta": {
"focus": {
"x": -0.69,
"y": 0.42
}
},
"description": "test uploaded via api",
"blurhash": null
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="401 Invalid or missing Authorization header" %}
```javascript
{
"error": "The access token is invalid"
}
```
{% endtab %}
{% tab title="422 File or file type is unsupported or invalid" %}
```javascript
{
"error": "Validation failed: File content type is invalid, File is invalid"
}
```
{% endtab %}
{% endtabs %}
## Update attachment
`PUT` `https://mastodon.example/api/v1/media/:id`
Update an Attachment, before it is attached to a status and posted.\
\
**Returns:** Attachment\
**OAuth:** User token + `write:media`\
**Version history:**\
0.0.0 - added
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------------------------- |
| :id | string | The id of the Attachment entity to be updated |
#### Headers
| Name | Type | Description |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \ |
#### Request Body
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------- |
| file | object | The file to be attached, using multipart form data. |
| description | string | A plain-text description of the media, for accessibility purposes. |
| focus | string | Two floating points (x,y), comma-delimited ranging from -1.0 to 1.0 |
{% tabs %}
{% tab title="200 " %}
```javascript
{
"id": "22348641",
"type": "image",
"url": "https://files.mastodon.social/media_attachments/files/022/348/641/original/e96382f26c72a29c.jpeg",
"preview_url": "https://files.mastodon.social/media_attachments/files/022/348/641/small/e96382f26c72a29c.jpeg",
"remote_url": null,
"text_url": "https://mastodon.social/media/4Zj6ewxzzzDi0g8JnZQ",
"meta": {
"focus": {
"x": -0.42,
"y": 0.69
},
"original": {
"width": 640,
"height": 480,
"size": "640x480",
"aspect": 1.3333333333333333
},
"small": {
"width": 461,
"height": 346,
"size": "461x346",
"aspect": 1.3323699421965318
}
},
"description": "test uploaded via api, but updated",
"blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
}
```
{% endtab %}
{% tab title="401 Invalid or missing Authorization header" %}
```javascript
{
"error": "The access token is invalid"
}
```
{% endtab %}
{% tab title="404 Attachment does not exist, is deleted, or was not created by you" %}
```javascript
{
"error": "Record not found"
}
```
{% endtab %}
{% tab title="422 File or file type is unsupported or invalid" %}
```javascript
{
"error": "Validation failed: File content type is invalid, File is invalid"
}
```
{% endtab %}
{% endtabs %}
## Focal points
Server-side preview images are never cropped, to support a variety of apps and user interfaces. Therefore, the cropping must be done by those apps. To crop intelligently, focal points can be used to ensure a certain section of the image is always within the cropped viewport. [See this guide on how focal points are defined.](https://github.com/jonom/jquery-focuspoint#1-calculate-your-images-focus-point) In summary, floating points range from -1.0 to 1.0, left-to-right or bottom-to-top. (0,0) is the center of the image. (0.5, 0.5) would be in the center of the upper-right quadrant. (-0.5, -0.5) would be in the center of the lower-left quadrant. For reference, thumbnails in the Mastodon frontend are most commonly 16:9.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://mastodon.gitbook.io/mastodon/methods/statuses/media.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.