Inspired by Stripe’s versioning strategy, we try to version the API using dates to maintain a highly backwards compatible API.

When creating your API key, it will be tied by default to the latest version of the API and can not be changed. The version will be viewable from the API keys dashboard. You can however also manually specify a version to use at request level by providing the tally-version header.

If we would be introducing impossible to avoid breaking changes, you will be informed about this.

​
Example

If you created initially an API key when we launched the Tally API in public beta, then your key is tied to version 2025-01-15. If you would be fetching forms without providing the tally-version header, you would be fetching forms from the 2025-01-15 version of the API.

​
Request

curl -X GET 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'

​
Response

[
  {
    "id": "LmBenY",
    "name": "Test",
    "isNameModifiedByUser": false,
    "workspaceId": "kwob3J",
    "organizationId": "kwob3J",
    "status": "PUBLISHED",
    "hasDraftBlocks": false,
    "numberOfSubmissions": 0,
    "createdAt": "2025-01-28T09:23:24.000Z",
    "updatedAt": "2025-01-28T09:41:22.000Z",
    "index": 0,
    "isClosed": false
  },
  {
    "id": "qnGe3Z",
    "name": "Contact form",
    "isNameModifiedByUser": false,
    "workspaceId": "kwob3J",
    "organizationId": "kwob3J",
    "status": "PUBLISHED",
    "hasDraftBlocks": false,
    "numberOfSubmissions": 7,
    "createdAt": "2025-01-14T09:55:31.000Z",
    "updatedAt": "2025-01-23T13:09:13.000Z",
    "index": 1,
    "isClosed": false
  }
]

Then in version 2025-02-01, we introduced some breaking changes to the /forms endpoint and introduced pagination meta data while the data is wrapped within the items key.

To make use of this you can explicitly specify the version using the tally-version header.

​
Request

curl -X GET 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-H 'tally-version: 2025-02-01'

​
Response

{
  "items": [
    {
      "id": "LmBenY",
      "name": "Test",
      "isNameModifiedByUser": false,
      "workspaceId": "kwob3J",
      "organizationId": "kwob3J",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 0,
      "createdAt": "2025-01-28T09:23:24.000Z",
      "updatedAt": "2025-01-28T09:41:22.000Z",
      "index": 0,
      "isClosed": false
    },
    {
      "id": "qnGe3Z",
      "name": "Contact form",
      "isNameModifiedByUser": false,
      "workspaceId": "kwob3J",
      "organizationId": "kwob3J",
      "status": "PUBLISHED",
      "hasDraftBlocks": false,
      "numberOfSubmissions": 7,
      "createdAt": "2025-01-14T09:55:31.000Z",
      "updatedAt": "2025-01-23T13:09:13.000Z",
      "index": 1,
      "isClosed": false
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 2,
  "hasMore": false
}
You could also just rotate your API key to make use of the latest version by default.