Set the organization's image

Uploads the organization's image, shown wherever its initials show today: the organization switcher, the console's home and the organization's pages. Send the image base64-encoded in content: a square PNG, JPEG or WebP image of at most 512 KB and 1024 × 1024 pixels. The type is read from the bytes; SVG and GIF are refused. The console crops and resizes the image to 256 × 256 in the browser before it uploads it, which also removes metadata such as the location a photo was taken.

The image is private: it is served at its avatar.url (/media/{fileId}/{sha256}.{ext}) only to the organization's members and Ownrecord staff. Uploading the same image again changes nothing. Needs org:write (organization owners and admins). Dry-run it to check an image without storing it.

At a glance

REST: PUT /api/v1/organizations/{id}/avatar
MCP tool: organizations_avatar_set
Operation ID: organizations.avatar.set
Scope: Organization
Permission: org:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the org:write scope
Since: M13

Request

Path parameters

Field	Type	Description
`id`	`org_…` ID

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`content`	string	Yes	The image's bytes, base64-encoded: a square PNG, JPEG or WebP image of at most 512 KB and 1024 × 1024 pixels (256 × 256 is what the console uploads).

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`org_…` ID
`object`	`"organization"`
`slug`	string
`name`	string
`country`	string
`status`	one of `active`, `restricted`, `suspended`, `closing`, `closed`
`isPlatform`	boolean
`supportAccess`	one of `off`, `on_request`, `always_read`
`requireMfa`	boolean
`entitlements`	object
`plan`	object
`plan.status`	one of `trialing`, `active`, `past_due`, `unpaid`, `canceled`, `none`
`plan.override`	object or null
`avatar`	object or null
`createdBy`	`usr_…` ID
`createdAt`	date-time
`updatedAt`	date-time

Examples

Upload the organization's image

HTTP

PUT /api/v1/organizations/org_01m4tx5nj7ekd958x53w4bntcg/avatar
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}

Response (200):

JSON

{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "active",
  "isPlatform": false,
  "supportAccess": "on_request",
  "requireMfa": false,
  "entitlements": {
    "livemode": true,
    "entities.max": 2,
    "brands.max": 3,
    "members.max": 10,
    "jurisdictions.registered.max": 10,
    "subscriptions.enabled": true,
    "usage_billing.enabled": true,
    "einvoicing.enabled": true,
    "processors.secondary": false,
    "custom_domains.max": 2,
    "api.rate_limit_rps": 100,
    "audit.retention_days": 90,
    "support.level": "email",
    "filing.reports": "full",
    "sso.enabled": false,
    "assistant.enabled": true,
    "assistant.messages_per_month": 1000
  },
  "plan": {
    "status": "none",
    "override": {
      "reason": "Temporary Growth entitlements until platform billing (M12)",
      "expiresAt": null
    }
  },
  "avatar": {
    "fileId": "file_01m4tx5nj8emwbyf7y9vcf47yc",
    "url": "/media/file_01m4tx5nj8emwbyf7y9vcf47yc/63ef318d96b5d0d0ceba6e04a4e622b1158335cdc67c49e27839132c6f655058.png"
  },
  "createdBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`content` isn't base64, or is far larger than an image may be (`param` names the field).	Fix the fields listed in `details.issues` and send the request again.
`image_type_unsupported`	400	The file isn't a still PNG, JPEG or WebP image (read from its bytes): SVG, GIF and animations are refused.	Export the image as PNG, JPEG or WebP (a still image, not an animation) and upload it again. The type is read from the file's bytes, not from its name.
`image_too_large`	400	The image is larger than 512 KB.	Resize or compress the image to at most 512 KB. Avatars and icons are shown at 256 × 256 pixels and logos within 600 × 200, so a small file loses nothing.
`image_dimensions`	400	The image is wider or taller than 1024 pixels, or not square (avatars and icons), or a logo outside 1:1 to 4:1.	Use a square image of at most 1024 × 1024 pixels for avatars and icons, and a logo between square and four times as wide as it is tall, at most 1024 pixels a side.
`upstream_timeout`	502	The file store didn't answer in time; nothing was recorded. Retry.	Retry the request with the same Idempotency-Key after a short wait.
`resource_not_found`	404	The ID isn't the organization of the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The organization changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change this organization's settings.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Upload the organization's image#

Errors#