Update the organization
The organizations.update operation: PATCH /api/v1/organizations/{id} in the REST API and the organizations_update tool in the MCP server.
/api/v1/organizations/{id}Renames the organization or changes its slug. Organization slugs are unique across Ownrecord; a new slug
moves the console URLs (/console/{slug}), and old links stop working. API keys keep working.
Needs org:write (organization owners and admins).
At a glance
- REST:
PATCH /api/v1/organizations/{id} - MCP tool:
organizations_update - Operation ID:
organizations.update - Scope: Organization
- Permission:
org:write - Risk tier:
write - Dry run: Supported (send
Ownrecord-Dry-Run: true) - Idempotency:
Idempotency-Keyoptional - Modes: Test and live
- Authentication: API key with the
org:writescope - Since: M1
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | org_… ID |
Body
A JSON object (Content-Type: application/json):
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | |
slug | string | No |
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 | |
createdBy | usr_… ID | |
createdAt | date-time | |
updatedAt | date-time |
Examples
Rename the organization
PATCH /api/v1/organizations/org_01m4tx5nj7ekd958x53w4bntcg
Authorization: Bearer or_test_…
Content-Type: application/json
{
"name": "Acme Group"
}
Response (200):
{
"id": "org_01m4tx5nj7ekd958x53w4bntcg",
"object": "organization",
"slug": "acme",
"name": "Acme Group",
"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
}
},
"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 | Neither name nor slug was sent, or one is malformed. | Fix the fields listed in details.issues and send the request again. |
slug_invalid | 400 | The slug has the wrong format or is a reserved word. | Choose a slug such as acme or acme-app. Reserved words such as api, console and docs can't be used. |
slug_taken | 409 | Another organization already uses this slug. | Choose another slug. Organization and brand slugs are unique across Ownrecord; entity slugs are unique within an organization. |
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.