/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Upload Avatar

Upload Avatar

Upload a profile picture.

POST/v1/auth/profile/avatarTry it
Session token

Uploads a new profile picture and sets it on your account. The previous uploaded picture is deleted.

Note

Requires a session JWT — a dashboard session or an stx login token. API keys are rejected with 401. Any plan.

Request Body

Send the image either way:

•
multipart/form-data with the image in a field named file (avatar is also accepted).
•
A raw body with Content-Type: image/png, image/jpeg, image/gif or image/webp.

PNG, JPEG, GIF and WebP are accepted, up to 2 MB. The type is read from the file's bytes, not its name or Content-Type. SVG is refused.

Serving avatars

avatarUrl points at a public endpoint, GET /v1/auth/avatars/{userId}/{file}. It needs no credential — the random file name is what makes the URL hard to guess — so you can use it directly in an <img> tag. Responses are cached for a year (Cache-Control: public, max-age=31536000, immutable) and served with X-Content-Type-Options: nosniff and Content-Security-Policy: default-src 'none'; sandbox. A new upload gets a new URL. An unknown or deleted file returns 404 not_found, and 503 storage_unavailable when avatar storage is unavailable.

Error Responses

400 Bad Request

bad_request — no image was sent: a multipart body without a file field, or a body that is neither multipart nor image/*:

json
{
"error": {
"code": "bad_request",
"message": "Send the image as multipart/form-data (field \"file\") or as a raw image body.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

401 Unauthorized

unauthorized for a missing, invalid or expired token (or an API key); session_revoked when the session has been signed out.

413 Payload Too Large

avatar_too_large — the image is over 2 MB. details.maxBytes is the limit:

json
{
"error": {
"code": "avatar_too_large",
"message": "Use an image of 2 MB or less.",
"details": { "maxBytes": 2097152, "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

A request body far over the limit is refused before it is read, with the same code and details.maxBytes.

415 Unsupported Media Type

unsupported_image — the file is not a PNG, JPEG, GIF or WebP image:

json
{
"error": {
"code": "unsupported_image",
"message": "Upload a PNG, JPEG, GIF or WebP image.",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

503 Service Unavailable

storage_unavailable — avatar storage is not available right now ("Avatar uploads are not available right now."). Try again later.

Was this page helpful? Yes No
Request
cURLcURL (raw body)JavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/auth/profile/avatar \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-F "file=@avatar.png"
Responseapplication/json
201Created
{
"data": {
"avatarUrl": "https://api.syntext.dev/v1/auth/avatars/0b7e4c2d-9a1f-4d3e-8c56-2f1a7b9e0d48/5a9e3c71-2b4d-4f8a-9c06-e1d7b3a2f584.png",
"profile": {
"id": "0b7e4c2d-9a1f-4d3e-8c56-2f1a7b9e0d48",
"email": "jane@example.com",
"name": "Jane Doe",
"avatarUrl": "https://api.syntext.dev/v1/auth/avatars/0b7e4c2d-9a1f-4d3e-8c56-2f1a7b9e0d48/5a9e3c71-2b4d-4f8a-9c06-e1d7b3a2f584.png",
"githubUsername": "janedoe",
"emailVerified": true,
"createdAt": "2026-03-02T10:15:00.000Z"
}
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext