---
title: "Create or update a card"
method: POST
path: "/api/board/{boardId}"
tags: ["Cards"]
---

# Create or update a card

`POST /api/board/{boardId}`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/board/{boardId}`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/board/:boardId/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new card on the board. Use field UUIDs (from the schema endpoint) as keys in the request body.

To update an existing card, include its `_id` in the request body. The card must belong to this board.
Fields not provided in the body are left unchanged on update.

Contact fields take person ids from the Contacts API: a `person` field takes
`{ "_id": "<personId>" }` (or `null` to clear it), and a `persons` field takes an
array of them (`[]` clears it). Each id must be an existing contact in the board's
company. The stored value is expanded to `{ _id, name, duogram }`, where `name` is
the contact's full name and `duogram` its initials; any other keys sent are ignored.

Card-link fields (`location`, `unit`, `relatedAptlets`) always take an array of
`{ "_id": "<cardId>" }` (`[]` clears the field). Each id must be a live
(non-archived) card in the board's company that matches every part of the
field's `filter` that is set: the card must be on one of the boards in
`filter.aptletUuids`, and its board's type must be in `filter.aptletTypes`.
`location` and `unit` fields with no `aptletUuids` take cards from the built-in
`location` and `unit` boards. Values are stored as `{ _id, name, duogram }`.

## Path parameters

- `boardId` string, required

## Request body

- object
  - `_id` string: Existing card ID. When provided, updates that card instead of creating a new one.
  - `name` string: Card title (also accepted as `title`).

## Response `200`

Card created.

- object
  - `data` object
    - `_id` string: ID of the created card.

## Other responses

- `400`: A `person`/`persons` or `location`/`unit`/`relatedAptlets` value has the wrong shape, or names a contact or card that does not exist in the board's company or that the field's filter does not allow.
- `401`: Invalid or missing API key.
- `403`: API access is disabled for this board.
- `404`: Board not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)