Files
Uploads and downloads.
POST /attachments
Upload one file to attach to a message
Scope: messages:write, or the broad write. Idempotency-Key is required.
multipart/form-data with one file (the field name attachment is also accepted). At most 50 MiB. Every file is virus checked: one that fails is refused; one the scanner cannot check yet is stored and held back, and downloads answer 409 attachment_scan_pending until it clears. The id is staged for 24 hours; pass it as attachment_id when sending a message.
Parameters
| Name | Where | Description |
|---|---|---|
Idempotency-Key required | header | Makes a retry safe. Required on every POST. Must match ^[A-Za-z0-9_.-]{1,64}$. |
Request body
Send as multipart/form-data, not JSON.
| Field | Type | Description |
|---|---|---|
file required | string | One file. |
Example request
curl -X POST "https://www.seoclerk.com/api/v1/attachments" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY" \
-H "Idempotency-Key: uploadattachment-1" \
-F "[email protected]"Response 201
| Field | Type | Description |
|---|---|---|
id | integer | |
filename | string | |
size | integer | Bytes. |
content_type | string | |
expires_at | timestamp | Attach it to a message before then (24 hours). |
{
"data": {
"id": 1024,
"filename": "string",
"size": 1,
"content_type": "string",
"expires_at": "2026-10-10T14:03:22Z"
},
"meta": {
"request_id": "9f2c4e1ab07d3351"
}
}Errors
GET /attachments/{id}
Download an attachment
Scope: messages:read, or the broad read. The sender or recipient of a message carrying it, or the uploader while it is still staged; anyone else gets 404. Answers the file itself, not the JSON envelope, with Cache-Control: private, no-store.
Parameters
| Name | Where | Description |
|---|---|---|
id required | path | At least 1. |
Example request
curl "https://www.seoclerk.com/api/v1/attachments/1024" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY"Response 200
The file itself, not JSON.
Errors
POST /images
Upload an image or video
Scope: requests:write or listings:write, or the broad write. Idempotency-Key is required.
multipart/form-data with one file: a JPEG, PNG or GIF image, or a video (MP4, MOV and the other types the website's uploader takes), checked as that uploader checks it. A video is parked with the still ffmpeg takes from it and converted to MP4 when a listing is saved. An upload no job or listing takes is cleared within the day.
Parameters
| Name | Where | Description |
|---|---|---|
Idempotency-Key required | header | Makes a retry safe. Required on every POST. Must match ^[A-Za-z0-9_.-]{1,64}$. |
Request body
Send as multipart/form-data, not JSON.
| Field | Type | Description |
|---|---|---|
file required | string | One file. |
Example request
curl -X POST "https://www.seoclerk.com/api/v1/images" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY" \
-H "Idempotency-Key: uploadimage-1" \
-F "[email protected]"Response 201
| Field | Type | Description |
|---|---|---|
id | string | Pass in a job's images or a listing's media. The same bytes always get the same id. |
type | string | image, or video (parked with the still ffmpeg takes from it, converted to MP4 when a listing is saved). |
{
"data": {
"id": "string",
"type": "image"
},
"meta": {
"request_id": "9f2c4e1ab07d3351"
}
}