# Upload An Image To A Page

`POST /pages/{pageId}/images`

Uploads a JPEG, PNG, GIF, or WebP image, attaches it to the page, and returns stable Markdown for insertion. The maximum image size is 10 MB.
## Authentication

Use one of the following authentication alternatives:

- **API token** (`bearerToken`) : Send a named API token in the Authorization header. Send it in the `Authorization: Bearer <token>` header.
- **Better Auth browser session** (`browserSession`) : Use the Better Auth session cookie from a signed-in browser session. Send it in the `better-auth.session_token` cookie.
## Token permissions

API tokens must include `pages:write`.
## Parameters

- `pageId` (path, required): The UUID of the page.
- `Idempotency-Key` (header, optional): Use the same key to retry the same request. Completed responses are replayed for 24 hours; incomplete reservations expire after 5 minutes.
## Request Body

Required.

### `multipart/form-data`

```text
{
  "file": "string",
  "alt": "string"
}
```
## Responses

### 201

The managed image and Markdown reference.


### `application/json`

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "url": "string",
  "markdown": "string",
  "filename": "string",
  "originalName": "string",
  "mimeType": "image/jpeg",
  "size": 0
}
```

### 403

The API token is missing a required scope: pages:write.


### `application/json`

```json
{
  "error": {
    "code": "string",
    "message": "string"
  }
}
```