> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tally.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Learn how versioning works in the Tally API

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](https://tally.so/settings/api-keys). You can however also manually specify a version to use at request level by providing the `tally-version` header.

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

## Example

If you created an API key when we initially launched the Tally API, 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

```bash theme={null}
curl -X GET 'https://api.tally.so/forms' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'
```

### Response

```json theme={null}
[
  {
    "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

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

### Response

```json theme={null}
{
  "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
}
```

<Tip>You could also just rotate your API key to make use of the latest version by default.</Tip>