fizzy/docs/api

Fizzy API

Fizzy has an API that allows you to integrate your application with it or to create a bot to perform various actions for you.

API Endpoints

• Authentication
• Identity
• Account
• Boards
• Columns
• Cards
• Pins
• Steps
• Comments
• Reactions
• Tags
• Users
• Notifications
• Rich Text
• Webhooks

Authentication

There are two ways to authenticate with the Fizzy API:

1. Personal access tokens - Long-lived tokens for scripts and integrations
2. Magic link authentication - Session-based authentication for native apps

Read the authentication guide to get started.

Caching

Most endpoints return ETag and Cache-Control headers. You can use these to avoid re-downloading unchanged data.

Using ETags

When you make a request, the response includes an ETag header:

HTTP/1.1 200 OK
ETag: "abc123"
Cache-Control: max-age=0, private, must-revalidate

On subsequent requests, include the ETag value in the If-None-Match header:

GET /1234567/cards/42.json
If-None-Match: "abc123"

If the resource hasn't changed, you'll receive a 304 Not Modified response with no body, saving bandwidth and processing time:

HTTP/1.1 304 Not Modified
ETag: "abc123"

If the resource has changed, you'll receive the full response with a new ETag.

Example in Ruby:

# Store the ETag from the response
etag = response.headers["ETag"]

# On next request, send it back
headers = { "If-None-Match" => etag }
response = client.get("/1234567/cards/42.json", headers: headers)

if response.status == 304
  # Nothing to do, the card hasn't changed
else
  # The card has changed, process the new data
end

Error Responses

When a request fails, the API response will communicate the source of the problem through the HTTP status code.

Status Code	Description
400 Bad Request	The request was malformed or missing required parameters
401 Unauthorized	Authentication failed or access token is invalid
403 Forbidden	You don't have permission to perform this action
404 Not Found	The requested resource doesn't exist or you don't have access to it
422 Unprocessable Entity	Validation failed (see error response format above)
500 Internal Server Error	An unexpected error occurred on the server

If a request contains invalid data for fields, such as entering a string into a number field, in most cases the API will respond with a 500 Internal Server Error. Clients are expected to perform some validation on their end before making a request.

A validation error will produce a 422 Unprocessable Entity response, which will sometimes be accompanied by details about the error:

{
  "avatar": ["must be a JPEG, PNG, GIF, or WebP image"]
}

Pagination

All endpoints that return a list of items are paginated. The page size can vary from endpoint to endpoint, and we use a dynamic page size where initial pages return fewer results than later pages.

If there are more results to fetch, the response will include a Link header with a rel="next" link to the next page of results:

curl -H "Authorization: Bearer put-your-access-token-here" -H "Accept: application/json" -v http://fizzy.localhost:3006/686465299/cards
# ...
< link: <http://fizzy.localhost:3006/686465299/cards?page=2>; rel="next"
# ...

List parameters

When an endpoint accepts a list of values as a parameter, you can provide multiple values by repeating the parameter name:

?tag_ids[]=tag1&tag_ids[]=tag2&tag_ids[]=tag3

List parameters always end with [].

File Uploads

Some endpoints accept file uploads. To upload a file, send a multipart/form-data request instead of JSON. You can combine file uploads with other parameters in the same request.

Example using curl:

curl -X PUT \
  -H "Authorization: Bearer put-your-access-token-here" \
  -F "user[name]=David H. Hansson" \
  -F "user[avatar]=@/path/to/avatar.jpg" \
  http://fizzy.localhost:3006/686465299/users/03f5v9zjw7pz8717a4no1h8a7

Rich Text Fields

Some fields accept rich text content. These fields accept HTML input, which will be sanitized to remove unsafe tags and attributes.

See the rich text guide for more information, including how to attach files to rich text fields using the direct upload flow.