---
title: "Create a workflow status"
method: POST
path: "/api/v2/orgs/{orgId}/teams/{teamId}/statuses"
tags: ["Teams"]
---

# Create a workflow status

`POST /api/v2/orgs/{orgId}/teams/{teamId}/statuses`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/orgs/{orgId}/teams/{teamId}/statuses`
- Auth: HTTP bearer

Creates a new ordered status column for the team board.

## Headers

- `Idempotency-Key` string

## Request body

- CreateTeamStatusRequest
  - `name` string, required: Sanitized by the server to a resource name of at most 255 characters.
  - `description` string, nullable
  - `color` string
  - `position` string
  - `transitionState` 'not_started' | 'started' | 'closed'
  - `closeMode` 'off' | 'manual' | 'automatic' | 'add_mover_to_assignees': Automatic close-on-entry behavior for a workflow status. The bulk close action is available for every status. `off` leaves card state unchanged on entry, while `automatic` closes open cards on entry. `manual` is a deprecated legacy value with the same entry behavior as `off`. `add_mover_to_assignees` is a deprecated write alias that stores `closeMode=off` with `assignMoverOnEntry=true`; reads never return that alias.
  - `assignMoverOnEntry` boolean
  - `requiredCardFields` CardRequiredField[]

## Response `201`

Workflow status created.

- TeamStatusResponse
  - `status` TeamWorkflowStatus, required
    - `id` string, uuid, required
    - `name` string, required
    - `description` string, nullable, required
    - `position` string, required
    - `color` string, required
    - `status` string, required: Workflow-status lifecycle flag; `active` is the database default.
    - `transition_state` 'not_started' | 'started' | 'closed', required
    - `closeMode` 'off' | 'manual' | 'automatic' | 'add_mover_to_assignees', required: Automatic close-on-entry behavior for a workflow status. The bulk close action is available for every status. `off` leaves card state unchanged on entry, while `automatic` closes open cards on entry. `manual` is a deprecated legacy value with the same entry behavior as `off`. `add_mover_to_assignees` is a deprecated write alias that stores `closeMode=off` with `assignMoverOnEntry=true`; reads never return that alias.
    - `assignMoverOnEntry` boolean, required: When true, entering this status adds the authenticated mover as an assignee without removing existing assignees. Combines with any `closeMode`.
    - `requiredCardFields` CardRequiredField[], required
    - `team_id` string, uuid, required

## Other responses

- `400`: Malformed request parameters or body. Agile requests may return `INVALID_PAGINATION` or `INVALID_IDEMPOTENCY_KEY`.
- `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request.
- `403`: Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`).
- `404`: The resource does not exist in the parent named by the path, or is hidden from the caller. Absence and privacy denial are deliberately indistinguishable so project, organization, and private-team existence cannot be probed.
- `409`: The resource's current state no longer permits this operation, or a unique name, hierarchy, dependency, or lifecycle invariant would be violated. Examples include an active sprint that must be completed first, a duplicate card-tag name (`TAG_NAME_CONFLICT`), or a dependency cycle. Idempotent creates may return `IDEMPOTENCY_KEY_REUSED` or `IDEMPOTENCY_REQUEST_IN_PROGRESS`; the latter includes `Retry-After`.
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.
- `503`: Idempotency protection is temporarily unavailable. Error code is `IDEMPOTENCY_UNAVAILABLE`; the response includes `Retry-After`.

## Changes

- **2026-09-24** (v2) `4b520e771e08`: 1 warning, 5 info
  - added the new `add_mover_to_assignees` enum value to the `status/closeMode` response property for the response status `201`
  - added the new optional request property `assignMoverOnEntry`
  - added the new optional request property `requiredCardFields`
  - added the new `add_mover_to_assignees` enum value to the request property `closeMode/allOf[#/components/schemas/TeamStatusCloseMode]/`
  - …2 more
- **2026-09-15** (v2) `67c8b8616dbb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/orgs/:orgId/teams/:teamId/statuses/post.md)

---

[API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)