Render or retrieve the agent symbol as a PNG

GET/api/agent-avatars/{version}/{palette}/{file}
No API key
Veyra Docs TeamUpdated Version 1 · History

Render or retrieve the agent symbol as a PNG.

On-demand PNG of the agent symbol (a figure on a rounded tile in one of eight hues, or muted gray before an agent exists) for Slack, the mobile app and e-mail; no agent or organization lookup. The pose sets the status mark: working, thinking, listening and loading draw the running ring, sleepy the paused dot, confused the error dot. Size is the logical edge in pixels and scale the density. Background defaults to transparent; veyra-dark supplies the opaque Veyra Intelligence dark-mode background for Slack exports. Theme defaults to light; dark draws the dark theme's tile and ink, for images shown in the console's dark mode. Successful URLs are immutable for one year and return a content-derived ETag. Cache entries regenerate after deletion.

Authorization

No API key is needed: the token or id in the path, or the request's own signature, authenticates the call. How keys work.

Path parameters

versionstringRequiredThe version's id.one of: "veyra-v1"
palettestringRequiredThe version's id.one of: "blue", "green", "purple", "orange", "teal", "pink", "amber", "red", "muted"
filestringRequiredThe palette's id.one of: "rest.png", "idle.png", "listening.png", "thinking.png", "working.png", "success.png", "confused.png", "sleepy.png", "loading.png"

Query parameters

sizestringOptionalone of: "16", "20", "24", "32", "40", "48", "64", "96", "128", "256", "512"
scalestringOptionalone of: "1", "2"
backgroundstringOptionalone of: "transparent", "veyra-dark"
themestringOptionalone of: "light", "dark"

Responses

200PNG image; Cache-Control: public, max-age=31536000, immutable; ETag: SHA-256 of PNG bytesThe request worked; the body holds the result.
304If-None-Match matches the cached content ETag
400Bad requestThe request is malformed or failed validation. details names each field that failed.
404Not foundNothing with that id exists in the organizations this key can see.
429Cold-render admission limit for this client; Cache-Control: no-store; Retry-After in seconds. Cached images remain available.Too many requests; wait for Retry-After seconds.
503Retryable rendering/storage failure; Cache-Control: no-store; Retry-After: 5A dependency is unavailable; retry with backoff.

Errors return {"error": "..."}, often with a code and details. See errors and limits.

Agents