Skip to content
Facteur for developers

Rename a workspace, or change its slug

PATCH
/v1/workspaces/{slug}
curl --request PATCH \
  --url https://api.facteur.eu/v1/workspaces/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "slug": "example", "tag": "example", "color": "example", "quota": "example" }'

Renaming deliberately leaves the slug alone: it is in somebody’s bookmark and in a team channel, and re-slugging on a typo fix would rot every link. The slug moves only when it is asked for by name.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
slug
required
string

The workspace slug.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Every field optional; sending only what changed is the expected use.

object
name
string
slug

Moves only when asked for by name — a rename leaves it alone.

string
tag
string | null
color
string | null
quota
object | null
Examplegenerated
{
  "name": "example",
  "slug": "example",
  "tag": "example",
  "color": "example",
  "quota": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The workspace as it now stands.

Media typeapplication/json
object
slug
required

How every other route addresses this workspace. The internal id never leaves.

string
name
required
string
createdAt
required
string format: date-time
isDefault
required

The workspace every member of the organization reaches without being added to it.

boolean
tag
string | null
color
string | null
inboxCount
integer
memberCount

Null on the default workspace, which has no member rows because everyone is in it.

integer | null
messagesThisMonth
integer
canManage
boolean
quota

The ceilings in force. monthly.messages always carries the figure being enforced, whether the customer wrote a number or a share of the plan, so an interface renders it without knowing which. percent is present only when a share is how it was written.

object
daily

Messages accepted per day, or null for no daily ceiling.

integer | null
monthly
object
messages

The ceiling being enforced. Null next to a percent means the plan sells no monthly envelope for that share to apply to, so the rule holds nothing back — shown rather than hidden.

integer | null
percent

Present only when the ceiling was written as a share of the plan.

integer
onExceed

What happens to mail past the ceiling.

string
Examplegenerated
{
  "slug": "example",
  "name": "example",
  "createdAt": "2026-04-15T12:00:00Z",
  "isDefault": true,
  "tag": "example",
  "color": "example",
  "inboxCount": 1,
  "memberCount": 1,
  "messagesThisMonth": 1,
  "canManage": true,
  "quota": {
    "daily": 1,
    "monthly": {
      "messages": 1,
      "percent": 1
    },
    "onExceed": "example"
  }
}

400

Section titled “400”

NAME_REQUIRED, NAME_TOO_LONG, INVALID_SLUG, TAG_INVALID, COLOR_INVALID, or INVALID_JSON.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

401

Section titled “401”

No usable credential. UNAUTHENTICATED when none was presented, KEY_UNKNOWN, KEY_REVOKED or KEY_EXPIRED when a key was — kept distinct on purpose, because “mint a new one” and “somebody took this away from you” are different facts to whoever is reading a red pipeline.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

403

Section titled “403”

SCOPE_INSUFFICIENT (the message names the scope this request wanted and the ones the key holds), KEY_CANNOT_REACH (no scope opens this route to a key at all), FORBIDDEN, or one of the stated refusals listed under x-api-key-refusals.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

404

Section titled “404”

WORKSPACE_NOT_FOUND.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}

409

Section titled “409”

SLUG_TAKEN — another workspace in this organization already uses it.

Media typeapplication/json

Every failure has this shape. Branch on error.code; error.message is written for a human and is in French today.

object
error
required
object
code
required

The stable, machine-readable reason.

string
message

A sentence for whoever is reading the failure. Not part of the contract.

string
Example
{
  "error": {
    "code": "SCOPE_INSUFFICIENT"
  }
}