Files HTTP API
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 supplies the credentials and entities.
List currently visible attachments in a conversation
Section titled “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
Section titled “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.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/conversations/${id}/attachments" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Upload a file into existing authorized history
Section titled “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. |
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
Section titled “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
Stage a private file for up to 24 hours
Section titled “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.
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
Section titled “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
Download a currently visible attachment
Section titled “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
Section titled “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
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/attachments/${id}" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"