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

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

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.

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

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

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

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"]
}

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://app.fizzy.localhost:3006/686465299/cards
# ...
< link: <http://app.fizzy.localhost:3006/686465299/cards?page=2>; rel="next"
# ...

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 [].

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://app.fizzy.localhost:3006/686465299/users/03f5v9zjw7pz8717a4no1h8a7

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.