Upload avatar

Uploads the agent's avatar and points the theme at it.

posthttps://api.integrable.cloud/api/agents/{agent_id}/theme/avatar

Authentication: Bearer token
Retries: Idempotency-Key
Body: multipart/form-data
Version: 2026-09-03

widget_theme.avatar_url has been settable since themes existed, with nothing behind it - a tenant could name an image they hosted themselves and had no way to supply one otherwise. Object storage removed that blocker on 2026-08-29; this is the endpoint that was left.

The size cap is enforced while reading, as it is on document upload and for the same reason: await file.read() on an unbounded body buffers the whole thing before any check runs, so one large request can exhaust the container before the limit is consulted.

The file's type is read from its bytes, never from the Content-Type the uploader claims - see app.platform.images. The stored object is served to every visitor of the tenant's website, and an attacker-chosen type there is how an avatar becomes text/html on our own origin.

Path parameters#

agent_idstringrequired

Headers#

Idempotency-Keystring
A unique key of your choosing, so this request can be retried safely. The first request with a given key executes; every replay returns that first response unchanged, with Idempotent-Replay: true set.
Generate one key per action, not per session - reusing a key with a different body is refused with 422 rather than silently replaying the wrong answer. Keys are remembered for 24 hours. A request that failed releases its key, so a retry after fixing the payload runs normally.
Up to 255 characters

Request body#

multipart/form-data · required

Body_upload_avatar_api_agents__agent_id__theme_avatar_post

filefilerequired

Responses#

200OKapplication/json
object
5 response headers
RateLimit-Limit
Requests permitted in the current window.
RateLimit-Remaining
Requests left in the current window. Back off before it reaches 0.
RateLimit-Reset
Seconds until the current window resets.
X-API-Version
The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.
X-Request-ID
Quote this in a support request to identify the call.
422Validation error
The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Request · curl

curl -X POST "https://api.integrable.cloud/api/agents/$AGENT_ID/theme/avatar" \
  -H "Authorization: Bearer $INTEGRABLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@./document.pdf"

Set INTEGRABLE_API_KEY and the path variables first. The TypeScript and Python SDKs take the same fields.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

validation_error · 422 — The payload was well-formed JSON but failed schema validation.
unauthenticated · 401 — The request carried no API key, or one the API could not verify.
forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
idempotency_key_reused · 422 — This `Idempotency-Key` was used before, for a request with a different body.
rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Agents endpoints#

Something unclear or missing? Tell us and we’ll fix it.