---
title: "Upload a Pages reference image"
method: POST
path: "/api/pages/{siteId}/assets"
tags: ["pages"]
---

# Upload a Pages reference image

`POST /api/pages/{siteId}/assets`

## Request

- Base URL: `https://app.goosybear.ai`
- URL: `https://app.goosybear.ai/api/pages/{siteId}/assets`
- Auth: HTTP bearer

Uploads one reference image to the canonical board for a site in the resolved workspace. This REST-only endpoint has no MCP-tool equivalent. The request cannot select a tenant or a board, and `workspace` SELECTS among the workspaces the key's holder already reaches — it never widens a key.

## Path parameters

- `siteId` string, uuid, required

## Query parameters

- `workspace` string

## Response `200`

The image was stored and attached to the site's board.

- object
  - `ok` true, required
  - `data` object, required
    - `boardItemId` string, uuid, required
    - `storageObjectId` string, uuid, required
    - `displayName` string, required

## Other responses

- `400`: The site id or multipart request was invalid, or the file failed the image upload limits.
- `401`: No bearer credential, or one that did not resolve.
- `403`: Programmatic access is unavailable to this holder, the named workspace is outside the key's scope, or the holder lacks the operator role or `pages.manage` there. `workspace_ambiguous` and `workspace_unreachable` also answer here, and the slugs this key may pass are appended to `error.message`.
- `404`: The site or its canonical board is not in the API key's workspace.
- `429`: The API key is over its rate limit. Wait for `Retry-After` before retrying.
- `500`: An unexpected server or storage error occurred while handling the upload.

---

[API](https://skmtc.dev/goosybear/apis/goosy-bear-api.md) · [All operations](https://skmtc.dev/goosybear/apis/goosy-bear-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goosybear/apis/goosy-bear-api/revisions/6d82fb124064?raw)