# Files HTTP API

Inputs, results, permissions and errors for the files endpoints.

Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. `REPLACE_WITH_RETURNED_ID` values refer to IDs obtained through setup or prior operations. [Headless setup](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="get-api-v1-conversations-id-attachments"></a>

## List currently visible attachments in a conversation

`GET /api/v1/conversations/{id}/attachments`

List currently visible attachments in a conversation.

**Authorization:** Authenticated uploader or currently authorized conversation participant, subject to history visibility.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

Array of Attachment metadata.

Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.

Response media type: `application/json`. Array result.

[Attachment](https://beepgrid.com/docs/reference/models/#attachment)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/conversations/${id}/attachments" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-conversations-id-attachments"></a>

## Upload a file into existing authorized history

`POST /api/v1/conversations/{id}/attachments`

Upload a file into existing authorized history.

**Authorization:** Authenticated uploader or currently authorized conversation participant, subject to history visibility.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `multipart/form-data`.

| Field | Type | Usage |
| --- | --- | --- |
| `file` (required) | `string` | Multipart form field containing one file; 1 byte through 5 MiB for HTTP/SDK uploads. format="binary". |

### Result and recovery

Attachment metadata; multipart/form-data with one file field, bounded to 5 MiB.

Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.

Response media type: `application/json`. [Attachment](https://beepgrid.com/docs/reference/models/#attachment)


<a id="post-api-v1-attachments"></a>

## Stage a private file for up to 24 hours

`POST /api/v1/attachments`

Stage a private file for up to 24 hours. Only its uploader can read it until a keyed communication atomically claims attachment_ids. Maximum five files per message, 5 MiB each. An abandoned draft expires; upload itself has no automatic retry contract.

**Authorization:** Authenticated uploader or currently authorized conversation participant, subject to history visibility.


### Input

Content-Type: `multipart/form-data`.

| Field | Type | Usage |
| --- | --- | --- |
| `file` (required) | `string` | Multipart form field containing one file; 1 byte through 5 MiB for HTTP/SDK uploads. format="binary". |

### Result and recovery

Attachment metadata with its private draft ID or authorized conversation association. The response is not the file bytes.

Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.

Response media type: `application/json`. [Attachment](https://beepgrid.com/docs/reference/models/#attachment)


<a id="get-api-v1-attachments-id"></a>

## Download a currently visible attachment

`GET /api/v1/attachments/{id}`

Download a currently visible attachment.

**Authorization:** Authenticated uploader or currently authorized conversation participant, subject to history visibility.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

Raw file bytes with media type and download filename, not a JSON envelope.

Empty/oversized files are rejected. An already claimed or expired staged ID cannot be bound again. Removed members cannot bypass history checks with a known ID.

Response media type: `application/octet-stream`. `string`. See the operation-specific result contract.


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/attachments/${id}" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```