---
title: "Add cards"
method: POST
path: "/boards/{id}/cards"
---

# Add cards

`POST /boards/{id}/cards`

## Request

- Base URL: `https://clusters.soleilpictures.com/api/v1`
- URL: `https://clusters.soleilpictures.com/api/v1/boards/{id}/cards`
- Auth: HTTP bearer

Cards without x/y are placed in free space so they cannot cover what is already there. For an image card, upload the bytes first with POST /uploads and pass the image_key it returns.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `cards` object[]
    - `id` string
    - `kind` 'note' | 'image' | 'link' | 'doc' | 'video' | 'audio' | 'pdf' | 'file'
    - `x` number
    - `y` number
    - `w` number
    - `h` number
    - `z` number
    - `title` string, nullable
    - `body` string, nullable: The text of the card, whatever kind it is.
    - `html` string, nullable
    - `url` string, nullable
    - `image_key` string, nullable: A key from POST /uploads. Image cards only.
    - `alt` string, nullable
    - `color` string, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable

## Response `201`

The cards as they landed. `live: false` means they are saved but an open canvas will not show them until it reloads.

- object
  - `board_id` string
  - `cards` object[]
    - `id` string
    - `kind` 'note' | 'image' | 'link' | 'doc' | 'video' | 'audio' | 'pdf' | 'file'
    - `x` number
    - `y` number
    - `w` number
    - `h` number
    - `z` number
    - `title` string, nullable
    - `body` string, nullable: The text of the card, whatever kind it is.
    - `html` string, nullable
    - `url` string, nullable
    - `image_key` string, nullable: A key from POST /uploads. Image cards only.
    - `alt` string, nullable
    - `color` string, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
  - `live` boolean

## Other responses

- `400`: An unrecognised kind, or more than 100 cards
- `402`: The board is at its card cap

---

[API](https://skmtc.dev/soleilpictures/apis/soleil-clusters-api.md) · [All operations](https://skmtc.dev/soleilpictures/apis/soleil-clusters-api/llms.txt) · [OpenAPI document](https://skmtc.dev/soleilpictures/apis/soleil-clusters-api/revisions/1d426d587bf3?raw)