bterkuile/fizzy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dd42f0a098f74f41946c41ea0f2c5d90769a74ea
fizzy/docs/api/sections/cards.md
T
Mike Dalessio e70047ca0f Default development environment to app.fizzy.localhost (#2822) 
Using fizzy.localhost causes CORS errors when using minio for Active
Storage because the minio endpoint is at minio.fizzy.localhost — a
sibling subdomain, not a subdomain of the app host. Switching to
app.fizzy.localhost makes both hosts subdomains of fizzy.localhost,
resolving the CORS issue. See #2814 for the related minio CORS fix.

fizzy.localhost will continue to work if people want to use it, but all
docs and scripts have been updated to point to app.fizzy.localhost.
2026-04-09 12:43:01 -04:00

323 lines
9.1 KiB
Markdown
Raw Blame History

# Cards
Cards are tasks or items of work on a board. They can be organized into columns, tagged, assigned to users, and have comments.
## `GET /:account_slug/cards`
Returns a paginated list of cards you have access to. Results can be filtered using query parameters.
__Query Parameters:__
| Parameter | Description |
|-----------|-------------|
| `board_ids[]` | Filter by board ID(s) |
| `tag_ids[]` | Filter by tag ID(s) |
| `assignee_ids[]` | Filter by assignee user ID(s) |
| `creator_ids[]` | Filter by card creator ID(s) |
| `closer_ids[]` | Filter by user ID(s) who closed the cards |
| `card_ids[]` | Filter to specific card ID(s) |
| `indexed_by` | Filter by: `all` (default), `closed`, `not_now`, `stalled`, `postponing_soon`, `golden` |
| `sorted_by` | Sort order: `latest` (default), `newest`, `oldest` |
| `assignment_status` | Filter by assignment status: `unassigned` |
| `creation` | Filter by creation date: `today`, `yesterday`, `thisweek`, `lastweek`, `thismonth`, `lastmonth`, `thisyear`, `lastyear` |
| `closure` | Filter by closure date: `today`, `yesterday`, `thisweek`, `lastweek`, `thismonth`, `lastmonth`, `thisyear`, `lastyear` |
| `terms[]` | Search terms to filter cards |
__Response:__
```json
[
{
"id": "03f5vaeq985jlvwv3arl4srq2",
"number": 1,
"title": "First!",
"status": "published",
"description": "Hello, World!",
"description_html": "<div class=\"action-text-content\"><p>Hello, World!</p></div>",
"image_url": null,
"has_attachments": false,
"tags": ["programming"],
"golden": false,
"last_active_at": "2025-12-05T19:38:48.553Z",
"created_at": "2025-12-05T19:38:48.540Z",
"url": "http://app.fizzy.localhost:3006/897362094/cards/4",
"board": {
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
"name": "Fizzy",
"all_access": true,
"created_at": "2025-12-05T19:36:35.534Z",
"auto_postpone_period_in_days": 30,
"url": "http://app.fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm",
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://app.fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
}
},
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://app.fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
},
"comments_url": "http://app.fizzy.localhost:3006/897362094/cards/4/comments",
"reactions_url": "http://app.fizzy.localhost:3006/897362094/cards/4/reactions"
}
]
```
## `GET /:account_slug/cards/:card_number`
Returns a specific card by its number.
__Response:__
```json
{
"id": "03f5vaeq985jlvwv3arl4srq2",
"number": 1,
"title": "First!",
"status": "published",
"description": "Hello, World!",
"description_html": "<div class=\"action-text-content\"><p>Hello, World!</p></div>",
"image_url": null,
"has_attachments": false,
"tags": ["programming"],
"closed": false,
"golden": false,
"last_active_at": "2025-12-05T19:38:48.553Z",
"created_at": "2025-12-05T19:38:48.540Z",
"url": "http://app.fizzy.localhost:3006/897362094/cards/4",
"board": {
"id": "03f5v9zkft4hj9qq0lsn9ohcm",
"name": "Fizzy",
"all_access": true,
"created_at": "2025-12-05T19:36:35.534Z",
"auto_postpone_period_in_days": 30,
"url": "http://app.fizzy.localhost:3006/897362094/boards/03f5v9zkft4hj9qq0lsn9ohcm",
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://app.fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
}
},
"column": {
"id": "03f5v9zkft4hj9qq0lsn9ohcn",
"name": "In Progress",
"color": {
"name": "Lime",
"value": "var(--color-card-4)"
},
"created_at": "2025-12-05T19:36:35.534Z"
},
"creator": {
"id": "03f5v9zjw7pz8717a4no1h8a7",
"name": "David Heinemeier Hansson",
"role": "owner",
"active": true,
"email_address": "david@example.com",
"created_at": "2025-12-05T19:36:35.401Z",
"url": "http://app.fizzy.localhost:3006/897362094/users/03f5v9zjw7pz8717a4no1h8a7"
},
"comments_url": "http://app.fizzy.localhost:3006/897362094/cards/4/comments",
"reactions_url": "http://app.fizzy.localhost:3006/897362094/cards/4/reactions",
"steps": [
{
"id": "03f8huu0sog76g3s975963b5e",
"content": "This is the first step",
"completed": false
},
{
"id": "03f8huu0sog76g3s975969734",
"content": "This is the second step",
"completed": false
}
]
}
```
> **Note:** The `closed` field indicates whether the card is in the "Done" state. The `column` field is only present when the card has been triaged into a column; cards in "Maybe?", "Not Now" or "Done" will not have this field.
## `POST /:account_slug/boards/:board_id/cards`
Creates a new card in a board.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | The title of the card |
| `description` | string | No | Rich text description of the card |
| `status` | string | No | Initial status: `published` (default), `drafted` |
| `image` | file | No | Header image for the card |
| `tag_ids` | array | No | Array of tag IDs to apply to the card |
| `created_at` | datetime | No | Override creation timestamp (ISO 8601 format) |
| `last_active_at` | datetime | No | Override last activity timestamp (ISO 8601 format) |
__Request:__
```json
{
"card": {
"title": "Add dark mode support",
"description": "We need to add dark mode to the app"
}
}
```
__Response:__
Returns `201 Created` with a `Location` header pointing to the new card.
## `PUT /:account_slug/cards/:card_number`
Updates a card.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | No | The title of the card |
| `description` | string | No | Rich text description of the card |
| `status` | string | No | Card status: `drafted`, `published` |
| `image` | file | No | Header image for the card |
| `tag_ids` | array | No | Array of tag IDs to apply to the card |
| `last_active_at` | datetime | No | Override last activity timestamp (ISO 8601 format) |
__Request:__
```json
{
"card": {
"title": "Add dark mode support (Updated)"
}
}
```
__Response:__
Returns the updated card.
## `DELETE /:account_slug/cards/:card_number`
Deletes a card. Only the card creator or board administrators can delete cards.
__Response:__
Returns `204 No Content` on success.
## `DELETE /:account_slug/cards/:card_number/image`
Removes the header image from a card.
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/closure`
Closes a card.
__Response:__
Returns `204 No Content` on success.
## `DELETE /:account_slug/cards/:card_number/closure`
Reopens a closed card.
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/not_now`
Moves a card to "Not Now" status.
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/triage`
Moves a card into a column.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `column_id` | string | Yes | The ID of the column to move the card into |
__Response:__
Returns `204 No Content` on success.
## `DELETE /:account_slug/cards/:card_number/triage`
Sends a card back to triage.
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/taggings`
Toggles a tag on or off for a card. If the tag doesn't exist, it will be created.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tag_title` | string | Yes | The title of the tag (leading `#` is stripped) |
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/assignments`
Toggles assignment of a user to/from a card.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assignee_id` | string | Yes | The ID of the user to assign/unassign |
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/watch`
Subscribes the current user to notifications for this card.
__Response:__
Returns `204 No Content` on success.
## `DELETE /:account_slug/cards/:card_number/watch`
Unsubscribes the current user from notifications for this card.
__Response:__
Returns `204 No Content` on success.
## `POST /:account_slug/cards/:card_number/goldness`
Marks a card as golden.
__Response:__
Returns `204 No Content` on success.
## `DELETE /:account_slug/cards/:card_number/goldness`
Removes golden status from a card.
__Response:__
Returns `204 No Content` on success.
Reference in New Issue View Git Blame Copy Permalink