---
title: "Atomically create and place a Project Card"
method: POST
path: "/api/v2/orgs/{orgId}/teams/{teamId}/project-cards"
tags: ["Teams"]
---

# Atomically create and place a Project Card

`POST /api/v2/orgs/{orgId}/teams/{teamId}/project-cards`

## Request

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

Creates a Project-owned Card, optionally assigns an effective Project
member, links the Project when separately authorized, and places the Card
on this Team board in one transaction. The selected Status and Sprint
policy are revalidated under the Team lock before any row is inserted.
A status with `assignMoverOnEntry` assigns the caller, using the API key's
owning user for API-key requests. Destination required fields are
enforced unless explicitly bypassed.

## Headers

- `Idempotency-Key` string

## Request body

- CreateTeamProjectCardRequest
  - `projectId` string, uuid, required
  - `name` string, required: Sanitized by the server to a resource name of at most 255 characters.
  - `description` string, nullable
  - `resolution` string, nullable
  - `deadline` string, date-time, nullable
  - `effort` integer, nullable
  - `assigneeId` string, uuid, nullable: Use `assigneeIds`.
  - `assigneeIds` string[]
  - `tagIds` string[]
  - `cardLinks` CreateTeamCardLinkInput[]
    - `cardId` string, uuid, required
    - `linkType` 'relates_to' | 'depends_on' | 'dependency_of'
  - `statusId` string, uuid, nullable: Defaults to the Team's first not-started Status.
  - `sprintId` string, uuid, nullable: Planned or active Sprint; null places the Card in the backlog.
  - `bypassRequiredFields` boolean: Explicitly create the card despite missing destination-status fields.

## Response `201`

Project Card, Team placement, and current history head.

- CreateTeamProjectCardResponse
  - `card` AgileCard, required
    - `id` string, uuid, required
    - `name` string, required
    - `description` string, nullable, required
    - `resolution` string, nullable, required: Optional Markdown resolution; closing or reopening the card does not clear it.
    - `created_by_user` string, uuid, nullable, required
    - `author_display_name` string, nullable: Display name of the user who created the card, when available.
    - `created_at` string, date-time, nullable, required
    - `closed_at` string, date-time, nullable: Timestamp of the latest transition to the closed state; null while open.
    - `updated_at` string, date-time, nullable, required
    - `deadline` string, date-time, nullable, required
    - `is_open` boolean, required
    - `project_id` string, uuid, required
    - `effort` integer, nullable, required: Unit-agnostic estimate, commonly interpreted as story points or hours.
  - `link` TeamCardLink, required
    - `id` string, uuid, required
    - `card_id` string, uuid, required
    - `team_id` string, uuid, required
    - `sprint_id` string, uuid, nullable, required
    - `status_id` string, uuid, nullable, required
    - `created_at` string, date-time, nullable, required
  - `historyHeadId` string, uuid, nullable, required: Latest committed card-history row ID; null only before a card has history.
  - `historyHeadSequence` string, nullable, required: Globally monotonic card-history sequence.

## 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`.
- `422`: The destination status requires card fields that are currently missing. Error code is `CARD_STATUS_FIELDS_REQUIRED`; `error.details` includes `teamId`, `statusId`, `statusName`, and `missingFields`. Supply the fields atomically or explicitly set `bypassRequiredFields=true`.
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.

## Changes

- **2026-09-24** (v2) `4b520e771e08`: 6 info
  - added the new optional request property `assigneeIds`
  - added the new optional request property `bypassRequiredFields`
  - added the new optional request property `cardLinks`
  - added the new optional request property `tagIds`
  - …2 more
- **2026-09-15** (v2) `aa52eb4e8fd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/orgs/:orgId/teams/:teamId/project-cards/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)