Assets
Assets are uploaded images, which you attach to posts and comments (asset_ids) or use as a changelog entry's cover (cover_asset_id). Uploads are re-encoded without their metadata, and an upload that's still attached to nothing after a day is deleted.
The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." Upload an asset#
/ v1/ workspaces/ {workspace_id}/ assetsAn API key with Read and write access
The request body is the image file, up to 10 MB: a PNG, JPEG, GIF or WebP image. The type is recognized from the content (415 unsupported_image otherwise), and the image can be at most 16,384 pixels on a side and 25 megapixels, and a GIF at most 500 frames and 100 megapixels across them (422 image_too_large otherwise). A file of a known type that can't be read returns 422 invalid_image. The image is re-encoded without its metadata. Attach it within a day, with asset_ids on a post or a comment or as a changelog entry's cover_asset_id, or it's deleted.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Headers
Idempotency-KeystringMakes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.
1 to 255 characters
Request body
image/*requiredThe image file itself, as the raw body, with its type in Content-Type.
Responses
- 201CreatedThe uploaded asset object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/assets" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: image/png" \
--data-binary @screenshot.png{
"id": "asset_01h455vb4pex5vsknk084sn02q",
"byte_size": 184320,
"content_type": "image/png" ,
"height": 720,
"url": "https://files.example.com/01h455vb4pex5vsknk084sn02q.png" ,
"width": 1280,
"created_at": "2026-09-28T14:03:12.482Z"
}Retrieve an asset#
/ v1/ workspaces/ {workspace_id}/ assets/ {asset_id}Any API key: Read or Read and write
Returns an uploaded image, attached or not.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_asset_idstringrequiredThe asset's id.
Starts with
asset_
Responses
- 200OKThe asset object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/assets/asset_01h455vb4pex5vsknk084sn02q" {
"id": "asset_01h455vb4pex5vsknk084sn02q",
"byte_size": 184320,
"content_type": "image/png" ,
"height": 720,
"url": "https://files.example.com/01h455vb4pex5vsknk084sn02q.png" ,
"width": 1280,
"created_at": "2026-09-28T14:03:12.482Z"
}The asset object#
Fields
idstringStarts with
asset_byte_sizeintegercontent_typestringOne ofimage/pngimage/jpegimage/gifheightintegerurlstring · URLWhere to fetch the image. When the image isn't public, the URL is signed and works for one to two hours: request the object again for a fresh URL.
widthintegercreated_atstring · date-time
Example
{
"id": "asset_01h455vb4pex5vsknk084sn02q",
"byte_size": 184320,
"content_type": "image/png" ,
"height": 720,
"url": "https://files.example.com/01h455vb4pex5vsknk084sn02q.png" ,
"width": 1280,
"created_at": "2026-09-28T14:03:12.482Z"
}