Skip to content
Swingback, home

API reference

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):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

Upload an asset#

POST/v1/workspaces/{workspace_id}/assets

An 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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

Headers

  • Idempotency-Keystring

    Makes 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/*required

The image file itself, as the raw body, with its type in Content-Type.

Responses

  • 201
    CreatedThe uploaded asset object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST "$SWINGBACK_API/assets" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @screenshot.png
Response · 201 Created
{
  "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#

GET/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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • asset_idstringrequired

    The asset's id.

    Starts with asset_

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/assets/asset_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "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

  • idstring

    Starts with asset_

  • byte_sizeinteger
  • content_typestring
    One ofimage/pngimage/jpegimage/gif
  • heightinteger
  • urlstring · URL

    Where 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.

  • widthinteger
  • created_atstring · date-time

Example

The asset object
{
  "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"
}

Search pages, sections and code: a setting, an event, a method.