EaserixDocs
DevelopersAPI referenceTasksTeams

How a team's board behaves

The settings Tasks owns for one team. A sub-resource rather than fields on the team itself, because the two halves have different owners: the identity platform owns the team (its name, its members, whether it exists) and Tasks owns only how its board behaves. Readable by anyone who can see the team — a client needs the estimate scale to render an estimate field at all, and someone who cannot change a setting still has to see the board it describes. Changing them is the gated half.

View as Markdown
GET
/v1/teams/{id}/settings
AuthorizationBearer <token>

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/teams/497f6eca-6276-4993-bfeb-53cbbbba6f08/settings"
{  "settings": {    "teamId": "a4ede8ba-7c0a-4485-8763-cbd9b282fbec",    "key": "string",    "defaultStateId": "54d2ba72-736d-413b-9931-1704e6f34fa9",    "defaultPriority": 0,    "defaultAssignee": "none",    "estimateScale": "none",    "retentionDays": 1,    "cyclesEnabled": true,    "cycleWeeks": 1,    "cycleStartDay": 1,    "cycleUpcoming": 0,    "cycleCooldownDays": 0,    "cycleRollover": true  }}

List the workspace's teams (read-only — auth owns the entity)

The teams of the caller's active workspace that the CALLER IS IN — the teams named by the teams[] claim in their token, not every team the workspace has. Callers holding org.data.read_all (owner, admin) get the whole workspace instead, so leadership is never locked out. Personal workspaces are never narrowed: they have one member and one tasks-local container. May be EMPTY, and an empty list is not an error: it means the caller is in no team yet. Clients must render that as its own state rather than as "no teams exist" — the workspace may be full of teams the caller cannot see. Membership changes reach this list when the token re-mints (<=1h, immediately on a workspace switch), so a just-created team can be missing from one request and present in the next. The team ENTITY is platform-wide (the same team Accounts manages, owned by the auth service), but this endpoint reads tasks' OWN copy, replicated from the platform event stream. It makes no call to auth, so auth being unreachable no longer empties this list. A team created in Accounts appears here within seconds, with a minted issue-key prefix and the default workflow. A team DELETED in Accounts leaves this list, while its issues stay readable by direct reference — deleting a team must not destroy the work filed under it.

Change how a team's board behaves

Partial: an absent field is left alone, so a client may send only what changed and two people editing different settings do not overwrite each other. `defaultStateId` additionally distinguishes an empty string (clear it, restoring "the team's lowest-position state") from omission (leave it). `key` is the issue prefix. It is uppercased and trimmed, must be 1-6 letters or digits, and is unique within the workspace — a clash is a 409. Changing it changes the displayed id of EVERY issue in the team, because an issue's id is its team's key plus its own number: GEN-42 becomes ENG-42. Existing links that carry the old id will not resolve. Every value is validated here before the database's CHECK constraints see it, so a bad value is a 400 naming the field rather than a 500. `cyclesEnabled` is the only way a team gets cycles at all — there is no create route. A background job keeps them running on the cadence: it appends the current cycle plus `cycleUpcoming` more, contiguously (or `cycleCooldownDays` apart, if set), and never moves, renames or removes one that already exists — nothing in this API can delete a cycle once the roller has made it. Turning `cyclesEnabled` on from off creates the first cycle immediately rather than waiting for the next hourly tick. Changing the cadence affects only the cycles created after it — the quarter that already happened is not rewritten. `cycleStartDay` aligns only the very first cycle; after that each begins `cycleCooldownDays` after the previous ends, so the rhythm cannot drift or leave a gap beyond the one asked for. `cycleRollover` moves an unfinished issue into the next cycle the moment its own cycle ends; completed and canceled issues stay where they are, since they are that cycle's record of what happened, not work still open. Off by default. Turning it on from off closes out every cycle that has already ended, so the very next rollover only ever affects cycles that end from here on — it does not walk months of already-finished cycles forward into the one running now. Requires org.teams.manage, or leading this team.