# stensul-image-upload-session

> The upload path for local images: files the user has, pastes or attaches. Mints a single-use browser upload link, or a small uploader script on hosts with a shell.

Source: https://stensul.com/developers/reference/stensul-image-upload-session/ · From the live server's tool list, 2026-09-28

- Scope: `images:write`
- Access: write

Links are valid for about 15 minutes and scoped to one email. Images are never base64-encoded into a tool call.

## Inputs

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | "start" \| "check" | yes | `start` mints the upload; `check` fetches the filenames after the user uploaded. |
| `email_id` | string | yes | The email the images belong to. |
| `mode` | "link" \| "script" | no | `link` (default, works on every host) or `script` (hosts with a shell, Python 3 and internet). |
| `count` | integer 1–5 | no | How many images the upload accepts (default 1). |
| `labels` | string[] (≤5) | no | Per-slot labels shown on the upload page, for example `"Hero banner (top)"`. |
| `upload_id` | string | no | `check` only: the id returned by `start`. |

## Example request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stensul-image-upload-session",
    "arguments": {
      "action": "start",
      "email_id": "64f0c0ffee0000000000abcd",
      "count": 1,
      "labels": [
        "Hero banner (top)"
      ]
    }
  }
}
```

## Response

`start` (link mode): an upload link to give the user and an `upload_id`. `check`: the uploaded filenames.

## Errors

| Status | Message | Cause | Fix |
| --- | --- | --- | --- |
| 401 | Authentication expired or missing | The session's authorization expired. | Sign in again when the host prompts. On a 401 or 403, the server's instructions tell the model to re-check sign-in first. |
| 403 | Insufficient OAuth scope (403): The token lacks the required scope | The API connection doesn't have the scope this tool needs. | An admin adds the scope to the API connection. Then sign in again: adding a scope revokes existing tokens. |
| 403 | API error (403): Action is unauthorized. | The signed-in user's role lacks the permission, for example `edit_campaign`. | Grant the permission to the user's role in Admin > Users & Roles. It works for other users on the same connection. |