Images

Upload an image through the API, then use it on a page you create or update. An upload doesn't need a page, so you can upload first and create the page that shows it afterwards.

All examples use https://acme.folioso.dev/api/v1; use your organisation's address instead.

Upload an image#

POST /images

Needs the write ability, and a plan that includes image uploads. See the pricing page. Send the image as multipart/form-data, not JSON:

curl https://acme.folioso.dev/api/v1/images \
  -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F "image=@request-flow.png" \
  -F "alt=Request flow"

The response is 201 Created:

{
  "data": {
    "id": 318,
    "url": "https://folioso.dev/storage/images/0b9f4c5e-8d7a-4f1e-9c2b-3a4d5e6f7a8b.webp",
    "width": 1280,
    "height": 720,
    "alt": "Request flow",
    "expiresAt": "2026-10-20T11:15:02+00:00"
  }
}

Uploads are processed exactly as in the app: the file's contents are checked, it's converted to WebP, and animated images are stored as a still. See Images.

Uploading the same file twice makes two separate uploads.

An upload counts towards the organisation's image storage from the moment it's made, while it's still held, so a full organisation refuses the upload itself rather than the page write that uses it.

Use the image on a page#

Put the upload's url in an image on a page you create or update with POST /pages or PATCH /pages/{slug}. In TipTap JSON, it's the image's src:

{
  "type": "image",
  "attrs": { "src": "https://folioso.dev/storage/images/0b9f4c5e-8d7a-4f1e-9c2b-3a4d5e6f7a8b.webp", "alt": "Request flow" }
}

![Request flow](<https://folioso.dev/storage/images/0b9f4c5e-8d7a-4f1e-9c2b-3a4d5e6f7a8b.webp>)

In Markdown, it's the image's address:

![Request flow](https://folioso.dev/storage/images/0b9f4c5e-8d7a-4f1e-9c2b-3a4d5e6f7a8b.webp)

{
  "type": "doc",
  "content": [
    {
      "type": "image",
      "attrs": { "src": "https://folioso.dev/storage/images/0b9f4c5e-8d7a-4f1e-9c2b-3a4d5e6f7a8b.webp", "alt": "Request flow", "title": null }
    }
  ]
}

The alt text on the page is whatever the image node says. The alt you sent with the upload isn't copied onto the page. To set the image's width or alignment, see Block attributes.

When a page write's body names an upload, the upload becomes one of that page's images, exactly like an image added in the editor. It's kept for as long as a page or snapshot uses it, and it counts towards the organisation's image storage. See Uploads.

• The upload must be named in the body you send, as content or markdown. A PATCH that only renames the page doesn't use it.
• Only an upload made with a token for the same organisation as the page can be used. Naming another organisation's upload doesn't move it.
• One upload can be used on several pages. It belongs to the first page whose write names it.
• A write refused with 409 Conflict still makes the upload the page's image, although the page's content doesn't change. Write the page again to use it. If no page ever does, it's deleted like any image that's no longer used. Every other refusal (403, 404, 422) comes before the upload is used, so it stays held as before.

How long an upload is kept#

An upload no page uses is held until its expiresAt, which is one hour after the upload by default. Once that time has passed, a clean-up that runs every 10 minutes deals with it:

• Still unused: it's deleted.
• Used by a page in your organisation, for example one written with a different token: it becomes that page's image, as if the page had named it.
• Used only elsewhere, such as in another organisation's page or in a snapshot: it's kept for as long as that content uses it, and isn't counted towards your storage.

So write the page before expiresAt. An upload can survive for up to about 10 minutes after it, but don't rely on that.

Errors#