### Example Usage: Creating a Simple Contact Form

Source: https://developers.tally.so/api-reference/mcp

An example of how to prompt an AI assistant to create a basic contact form using natural language.

```APIDOC
## Example Usage

Once configured, you can ask your AI assistant to create forms using natural language. Here are some examples:

### Creating a Simple Contact Form

```
Create a simple contact form
```

The AI assistant will automatically create a contact form with commonly expected fields based on its understanding of what a typical contact form should include.
```

--------------------------------

### Example Usage: Creating a Form with Specific Fields

Source: https://developers.tally.so/api-reference/mcp

An example of explicitly defining the fields required for a form, including their names, types, and whether they are required or optional.

```APIDOC
### Creating a form with specific fields

Alternatively, you can be explicit about exactly what fields you want:

```
Create a contact form with these specific fields:
- Name (required)
- Email (required)
- Phone (optional)
- Message (required)
- Captcha (required)
```

The AI assistant should create a form with the specified fields and save it.
```

--------------------------------

### Fetch Forms (Default Version)

Source: https://developers.tally.so/api-reference/versioning

This example shows how to fetch forms without specifying a version, which defaults to the version tied to your API key.

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

--------------------------------

### Fetch Forms (Specific Version)

Source: https://developers.tally.so/api-reference/versioning

This example demonstrates how to fetch forms from a specific API version by including the 'tally-version' header.

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

--------------------------------

### Fetch Forms Response (Default Version)

Source: https://developers.tally.so/api-reference/versioning

Example response when fetching forms without a specified version. The data is returned directly.

```json
[
  {
    "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
  }
]
```

--------------------------------

### Prompt: Create Form with Specific Fields

Source: https://developers.tally.so/api-reference/mcp

Example prompt to create a form with explicitly defined fields, including their types and whether they are required. This ensures precise form structure.

```text
Create a contact form with these specific fields:
- Name (required)
- Email (required)
- Phone (optional)
- Message (required)
- Captcha (required)
```

--------------------------------

### Fetch Forms Response (Specific Version)

Source: https://developers.tally.so/api-reference/versioning

Example response when fetching forms with a specified version. Note the 'items' key and pagination metadata.

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

--------------------------------

### Prompt: Create a Simple Contact Form

Source: https://developers.tally.so/api-reference/mcp

Example prompt to instruct an AI assistant to create a basic contact form. The AI will infer standard fields for a contact form.

```text
Create a simple contact form
```

--------------------------------

### GET /workspaces

Source: https://developers.tally.so/api-reference/endpoint/workspaces/list

Retrieves a paginated list of workspaces. Each workspace object includes details about its members and pending invites.

```APIDOC
## GET /workspaces

### Description
Returns a paginated array of workspace objects with associated users and pending invites.

### Method
GET

### Endpoint
https://api.tally.so/workspaces

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number for pagination (default: 1)

### Response
#### Success Response (200)
- **items** (array) - An array of Workspace objects.
- **page** (number) - Current page number.
- **limit** (number) - Number of items per page.
- **total** (number) - Total number of items.
- **hasMore** (boolean) - Whether there are more pages available.

#### Response Example
```json
{
  "items": [
    {
      "id": "ws_123",
      "name": "My Workspace",
      "members": [
        {
          "id": "user_abc",
          "firstName": "John",
          "lastName": "Doe",
          "fullName": "John Doe",
          "email": "john.doe@example.com",
          "avatarUrl": null,
          "organizationId": "org_xyz",
          "isDeleted": false,
          "hasTwoFactorEnabled": true,
          "createdAt": "2023-01-01T10:00:00Z",
          "updatedAt": "2023-01-01T10:00:00Z",
          "subscriptionPlan": "PRO"
        }
      ],
      "invites": [
        {
          "id": "invite_456",
          "email": "jane.doe@example.com",
          "workspaceIds": ["ws_123"]
        }
      ],
      "createdByUserId": "user_abc",
      "createdAt": "2023-01-01T10:00:00Z",
      "updatedAt": "2023-01-01T10:00:00Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 50,
  "hasMore": true
}
```

#### Error Response (401)
Unauthorized
```

--------------------------------

### Fetch Forms (Default Version)

Source: https://developers.tally.so/api-reference/versioning

This example shows how to fetch forms using the default API version associated with your API key. No specific version header is provided, so the API key's default version is used.

```APIDOC
## GET /forms

### Description
Fetches a list of forms associated with the API key's default version.

### Method
GET

### Endpoint
https://api.tally.so/forms

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Should be `application/json`.

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

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the form.
- **name** (string) - The name of the form.
- **isNameModifiedByUser** (boolean) - Indicates if the form name was modified by the user.
- **workspaceId** (string) - The ID of the workspace the form belongs to.
- **organizationId** (string) - The ID of the organization the form belongs to.
- **status** (string) - The current status of the form (e.g., PUBLISHED).
- **hasDraftBlocks** (boolean) - Indicates if the form has draft blocks.
- **numberOfSubmissions** (integer) - The total number of submissions for the form.
- **createdAt** (string) - The timestamp when the form was created.
- **updatedAt** (string) - The timestamp when the form was last updated.
- **index** (integer) - The index of the form.
- **isClosed** (boolean) - Indicates if the form is closed.

#### Response Example
```json
[
  {
    "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
  }
]
```
```

--------------------------------

### Example Usage: Updating an Existing Form with URL

Source: https://developers.tally.so/api-reference/mcp

Shows how to update a specific existing form by providing its URL and detailing the desired modifications, such as removing fields, adding CAPTCHA, and changing field options.

```APIDOC
### Updating an existing form

```
Update this form https://tally.so/r/a1B2c3
- Remove the phone number field
- Also add a captcha
- Make company field optional
```

The AI assistant will use the MCP tools to load your form, make the requested changes, and save the updated version.
```

--------------------------------

### Example Usage: Updating a Form

Source: https://developers.tally.so/api-reference/mcp

Demonstrates how to modify an existing form by providing natural language instructions to remove fields, add elements like CAPTCHA, and change field requirements.

```APIDOC
### Updating the Contact Form

If the generated form isn't exactly what you wanted, you can easily modify it by following up:

```
We don't need the Company field, remove the consent checkbox and maybe add a captcha
```

The AI assisant should correctly modify the form and save it.
```

--------------------------------

### Fetch Forms (Specific Version)

Source: https://developers.tally.so/api-reference/versioning

This example demonstrates how to fetch forms by explicitly specifying an API version using the 'tally-version' header. This is useful for accessing specific versions of the API, especially when breaking changes have been introduced.

```APIDOC
## GET /forms (with version)

### Description
Fetches a list of forms using a specific API version provided via the `tally-version` header.

### Method
GET

### Endpoint
https://api.tally.so/forms

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Should be `application/json`.
- **tally-version** (string) - Required - The specific API version to use (e.g., `2025-02-01`).

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

### Response
#### Success Response (200)
- **items** (array) - An array of form objects.
  - **id** (string) - Unique identifier for the form.
  - **name** (string) - The name of the form.
  - **isNameModifiedByUser** (boolean) - Indicates if the form name was modified by the user.
  - **workspaceId** (string) - The ID of the workspace the form belongs to.
  - **organizationId** (string) - The ID of the organization the form belongs to.
  - **status** (string) - The current status of the form (e.g., PUBLISHED).
  - **hasDraftBlocks** (boolean) - Indicates if the form has draft blocks.
  - **numberOfSubmissions** (integer) - The total number of submissions for the form.
  - **createdAt** (string) - The timestamp when the form was created.
  - **updatedAt** (string) - The timestamp when the form was last updated.
  - **index** (integer) - The index of the form.
  - **isClosed** (boolean) - Indicates if the form is closed.
- **page** (integer) - The current page number of the results.
- **limit** (integer) - The maximum number of items per page.
- **total** (integer) - The total number of items available.
- **hasMore** (boolean) - Indicates if there are more pages of results.

#### Response Example
```json
{
  "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
}
```
```

--------------------------------

### Example API Response for Form Submissions

Source: https://developers.tally.so/documentation/fetching-form-submissions

The API response includes pagination details, submission counts, form question metadata, and a list of individual submissions with their responses.

```json
{
  "page": 1,
  "limit": 50,
  "hasMore": false,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 4,
    "completed": 4,
    "partial": 0
  },
  "questions": [
    {
      "id": "EKOE2N",
      "type": "INPUT_TEXT",
      "title": "First name",
      "fields": [
        {
          "uuid": "21dd98ef-4c54-4e77-bcc6-7ec79409b3ea",
          "type": "INPUT_FIELD",
          "questionType": "INPUT_TEXT",
          "title": "First name"
        }
      ]
    }
  ],
  "submissions": [
    {
      "id": "GG6z5L",
      "formId": "mexJoq",
      "respondentId": "jzQdR9",
      "isCompleted": true,
      "submittedAt": "2024-12-30T09:02:01.000Z",
      "responses": [
        {
          "id": "4r5rAWb",
          "questionId": "EKOE2N",
          "answer": "Filip"
        }
      ]
    },
    {
      "id": "2WXeKV",
      "formId": "mexJoq",
      "respondentId": "kzQdR0",
      "isCompleted": true,
      "submittedAt": "2024-12-30T08:57:52.000Z",
      "responses": [
        {
          "id": "eR4RxeQ",
          "questionId": "EKOE2N",
          "answer": "Marie"
        }
      ]
    },
    {
      "id": "GPWkYL",
      "formId": "mexJoq",
      "respondentId": "lzQdR1",
      "isCompleted": true,
      "submittedAt": "2024-12-27T10:23:16.000Z",
      "responses": [
        {
          "id": "GlZqg8Q",
          "questionId": "EKOE2N",
          "answer": "Wouter"
        }
      ]
    },
    {
      "id": "MxBPJ8",
      "formId": "mexJoq",
      "respondentId": "mzQdR2",
      "isCompleted": true,
      "submittedAt": "2024-12-27T10:22:38.000Z",
      "responses": [
        {
          "id": "X0p8gDO",
          "questionId": "EKOE2N",
          "answer": "Frederik"
        }
      ]
    }
  ]
}
```

--------------------------------

### OpenAPI Specification for Listing Webhooks

Source: https://developers.tally.so/api-reference/endpoint/webhooks/get

This OpenAPI 3.0.1 specification defines the GET /webhooks endpoint for listing webhooks. It includes details on parameters, responses, and security.

```yaml
GET /webhooks
openapi: 3.0.1
info:
  title: OpenAPI
  description: Tally's API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tally.so
security:
  - bearerAuth: []
paths:
  /webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks
      description: >-
        Returns a paginated list of all webhooks across your accessible forms
        and workspaces.
      parameters:
        - name: page
          in: query
          required: false
          description: 'Page number for pagination (default: 1)'
          schema:
            type: number
            minimum: 1
        - name: limit
          in: query
          required: false
          description: 'Number of webhooks per page (default: 25, max: 100)'
          schema:
            type: number
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    description: List of webhooks
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Webhook ID
                        formId:
                          type: string
                          description: Form ID the webhook is attached to
                        url:
                          type: string
                          description: The webhook endpoint URL
                        signingSecret:
                          type: string
                          nullable: true
                          description: Secret used to sign webhook payloads
                        httpHeaders:
                          type: array
                          nullable: true
                          description: Custom HTTP headers to include in webhook requests
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: Header name
                              value:
                                type: string
                                description: Header value
                        eventTypes:
                          type: array
                          description: Types of events this webhook subscribes to
                          items:
                            $ref: '#/components/schemas/EventType'
                        externalSubscriber:
                          type: string
                          nullable: true
                          description: External subscriber identifier
                        isEnabled:
                          type: boolean
                          description: Whether the webhook is enabled
                        lastSyncedAt:
                          type: string
                          format: date-time
                          nullable: true
                          description: When the webhook was last synced
                        createdAt:
                          type: string
                          format: date-time
                          description: When the webhook was created
                        updatedAt:
                          type: string
                          format: date-time
                          description: When the webhook was last updated
                  page:
                    type: number
                    description: Current page number
                  limit:
                    type: number
                    description: Number of webhooks per page
                  hasMore:
                    type: boolean
                    description: Whether there are more pages available
                  totalCount:
                    type: number
                    description: Total number of webhooks
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - bearerAuth: []
components:
  schemas:
    EventType:
      type: string
      enum:
        - FORM_RESPONSE
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### OpenAPI Specification for Listing Workspaces

Source: https://developers.tally.so/api-reference/endpoint/workspaces/list

This OpenAPI 3.0.1 specification defines the GET /workspaces endpoint. It includes details on request parameters, response schemas for successful retrieval (200 OK) and unauthorized access (401 Unauthorized), and component schemas for Workspace and User objects.

```yaml
GET /workspaces
openapi: 3.0.1
info:
  title: OpenAPI
  description: Tally's API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tally.so
security:
  - bearerAuth: []
paths:
  /workspaces:
    get:
      summary: Retrieve a list of workspaces
      description: >-
        Returns a paginated array of workspace objects with associated users and
        pending invites.
      parameters:
        - name: page
          in: query
          required: false
          description: 'Page number for pagination (default: 1)'
          schema:
            type: number
      responses:
        '200':
          description: A paginated list of workspaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
                  page:
                    type: number
                    description: Current page number
                  limit:
                    type: number
                    description: Number of items per page
                  total:
                    type: number
                    description: Total number of items
                  hasMore:
                    type: boolean
                    description: Whether there are more pages available
                required:
                  - items
                  - page
                  - limit
                  - total
                  - hasMore
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
components:
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/User'
        invites:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              email:
                type: string
              workspaceIds:
                type: array
                items:
                  type: string
        createdByUserId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - members
        - invites
        - createdByUserId
        - createdAt
        - updatedAt
    User:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        email:
          type: string
        avatarUrl:
          type: string
          format: uri
          nullable: true
        organizationId:
          type: string
        isDeleted:
          type: boolean
        hasTwoFactorEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        subscriptionPlan:
          type: string
          enum:
            - FREE
            - PRO
            - BUSINESS
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### Prompt: Update Contact Form Fields

Source: https://developers.tally.so/api-reference/mcp

Example prompt to modify an existing form by removing fields, adding new ones, and changing field properties. This demonstrates iterative form refinement.

```text
We don't need the Company field, remove the consent checkbox and maybe add a captcha
```

--------------------------------

### List Organization Invites OpenAPI Specification

Source: https://developers.tally.so/api-reference/endpoint/organizations/invites/get

This OpenAPI 3.0.1 specification defines the GET endpoint for listing organization invites. It details the request path, parameters, and possible responses, including success and error codes.

```yaml
openapi: 3.0.1
info:
  title: OpenAPI
  description: Tally's API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tally.so
security:
  - bearerAuth: []
paths:
  /organizations/{organizationId}/invites:
    get:
      tags:
        - Organization
      summary: List organization invites
      description: Returns a list of all invites in your organization.
      responses:
        '200':
          description: A list of organization invites
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    organizationId:
                      type: string
                    email:
                      type: string
                    createdAt:
                      type: string
                      format: date-time
                    updatedAt:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - User doesn't have required permissions
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### OpenAPI Specification for Fetching a Workspace

Source: https://developers.tally.so/api-reference/endpoint/workspaces/get

This OpenAPI 3.0.1 specification defines the GET /workspaces/{workspaceId} endpoint. It outlines the request parameters, response schemas for successful retrieval and error cases, and security requirements.

```yaml
GET /workspaces/{workspaceId}
openapi: 3.0.1
info:
  title: OpenAPI
  description: Tally's API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tally.so
security:
  - bearerAuth: []
paths:
  /workspaces/{workspaceId}:
    get:
      summary: Retrieve a workspace
      description: Returns a single workspace by its ID with associated members.
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: The ID of the workspace to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Workspace retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          description: Unauthorized
        '404':
          description: Workspace not found
      security:
        - bearerAuth: []
components:
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/User'
        invites:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              email:
                type: string
              workspaceIds:
                type: array
                items:
                  type: string
        createdByUserId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - members
        - invites
        - createdByUserId
        - createdAt
        - updatedAt
    User:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        email:
          type: string
        avatarUrl:
          type: string
          format: uri
          nullable: true
        organizationId:
          type: string
        isDeleted:
          type: boolean
        hasTwoFactorEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        subscriptionPlan:
          type: string
          enum:
            - FREE
            - PRO
            - BUSINESS
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### OpenAPI Specification for Get User Info

Source: https://developers.tally.so/api-reference/endpoint/users/me/get

This OpenAPI 3.0.1 specification defines the GET /users/me endpoint for retrieving current user information. It includes server details, security schemes, request paths, and response schemas.

```yaml
GET /users/me
openapi: 3.0.1
info:
  title: OpenAPI
  description: Tally's API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tally.so
security:
  - bearerAuth: []
paths:
  /users/me:
    get:
      summary: Retrieve current user information
      description: Returns information about the current authenticated user.
      responses:
        '200':
          description: User information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: '#/components/schemas/User'
                properties:
                  subscriptionPlan:
                    type: string
        '401':
          description: Unauthorized
      security:
        - bearerAuth: []
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        email:
          type: string
        avatarUrl:
          type: string
          format: uri
          nullable: true
        organizationId:
          type: string
        isDeleted:
          type: boolean
        hasTwoFactorEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        subscriptionPlan:
          type: string
          enum:
            - FREE
            - PRO
            - BUSINESS
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

--------------------------------

### GET /users/me

Source: https://developers.tally.so/api-reference/endpoint/users/me/get

Returns information about the current authenticated user. This endpoint requires authentication via a bearer token.

```APIDOC
## GET /users/me

### Description
Returns information about the current authenticated user.

### Method
GET

### Endpoint
/users/me

### Parameters

### Request Body

### Request Example

### Response
#### Success Response (200)
- **id** (string) - User's unique identifier
- **firstName** (string) - User's first name
- **lastName** (string) - User's last name
- **fullName** (string) - User's full name
- **email** (string) - User's email address
- **avatarUrl** (string) - URL of the user's avatar (nullable)
- **organizationId** (string) - The ID of the organization the user belongs to
- **isDeleted** (boolean) - Indicates if the user account is deleted
- **hasTwoFactorEnabled** (boolean) - Indicates if two-factor authentication is enabled for the user
- **createdAt** (string) - Timestamp when the user was created (date-time format)
- **updatedAt** (string) - Timestamp when the user was last updated (date-time format)
- **subscriptionPlan** (string) - The user's current subscription plan (FREE, PRO, BUSINESS)

#### Response Example
```json
{
  "id": "user_12345",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "email": "john.doe@example.com",
  "avatarUrl": "https://example.com/avatar.jpg",
  "organizationId": "org_abcde",
  "isDeleted": false,
  "hasTwoFactorEnabled": true,
  "createdAt": "2023-01-01T10:00:00Z",
  "updatedAt": "2023-01-01T12:00:00Z",
  "subscriptionPlan": "PRO"
}
```

#### Error Response (401)
- **description**: Unauthorized
```

--------------------------------

### Claude Desktop/Web Configuration

Source: https://developers.tally.so/api-reference/mcp

Instructions for configuring the Tally MCP server as a custom connector within Claude Desktop or claude.ai.

```APIDOC
### Claude Desktop

This method works for Claude Desktop and [claude.ai](https://claude.ai), and applies across all Claude apps that support connectors, including Claude Chat, Claude Code, and Claude Cowork.

1. Open Claude Desktop (or [claude.ai](https://claude.ai) in your browser) and navigate to **Customize > Connectors > Add custom connector** from the sidebar on the left.
2. Give the connector a name and the Tally MCP server URL.

```bash
https://api.tally.so/mcp
```

3. Click "Add" to save the connector.
4. Restart Claude Desktop
5. The first time you use the Tally MCP server, Claude will open an OAuth flow to authenticate with your Tally account.
```

--------------------------------

### GET /forms

Source: https://developers.tally.so/api-reference/endpoint/forms/list

Retrieves a paginated list of forms. You can filter the results by specifying page number, number of forms per page, and workspace IDs.

```APIDOC
## GET /forms

### Description
Returns a paginated array of form objects.

### Method
GET

### Endpoint
/forms

### Parameters
#### Query Parameters
- **page** (number) - Optional - Page number for pagination (default: 1)
- **limit** (number) - Optional - Number of forms per page (default: 50, max: 500)
- **workspaceIds** (array[string]) - Optional - Filter forms by specific workspace IDs (encoded strings)

### Response
#### Success Response (200)
- **items** (array[Form]) - A list of form objects.
- **page** (number) - Current page number.
- **limit** (number) - Number of items per page.
- **total** (number) - Total number of items.
- **hasMore** (boolean) - Whether there are more pages available.

### Components
#### Schema: Form
- **id** (string)
- **name** (string)
- **workspaceId** (string)
- **status** (FormStatus)
- **numberOfSubmissions** (number)
- **isClosed** (boolean)
- **payments** (array[object])
- **createdAt** (string, format: date-time)
- **updatedAt** (string, format: date-time)

#### Schema: FormStatus
- type: string
- enum: [BLANK, DRAFT, PUBLISHED, DELETED]
```

--------------------------------

### Embed Tally Widget in Next.js Page

Source: https://developers.tally.so/widgets/examples/nextjs

Use the next/script component to load the Tally widget and call Tally.loadEmbeds() once it's available. This example is for the Pages Router.

```tsx
// pages/index.tsx
import Script from 'next/script';

export default function Homepage() {
  return (
    <div>
      <iframe
        data-tally-src="https://tally.so/embed/mRoDv3?alignLeft=1&hideTitle=1&transparentBackground=1&dynamicHeight=1"
        loading="lazy"
        width="100%"
        height="216"
        frameBorder={0}
        marginHeight={0}
        marginWidth={0}
        title="Newsletter subscribers">
      </iframe>

      <Script src="https://tally.so/widgets/embed.js" onLoad={() => Tally.loadEmbeds()} />
    </div>
  );
}
```

--------------------------------

### POST /workspaces

Source: https://developers.tally.so/api-reference/endpoint/workspaces/post

Creates a new workspace and assigns the authenticated user as a member. Requires a Pro subscription.

```APIDOC
## POST /workspaces

### Description
Creates a new workspace and assigns the authenticated user as a member. Requires a Pro subscription.

### Method
POST

### Endpoint
https://api.tally.so/workspaces

### Parameters
#### Request Body
- **name** (string) - Required - The name of the workspace

### Request Example
{
  "name": "My New Workspace"
}

### Response
#### Success Response (201)
- **id** (string) - Description not available in source
- **name** (string) - Description not available in source
- **members** (array) - Description not available in source
- **invites** (array) - Description not available in source
- **createdByUserId** (string) - Description not available in source
- **createdAt** (string) - Description not available in source
- **updatedAt** (string) - Description not available in source

#### Response Example
{
  "id": "ws_12345",
  "name": "My New Workspace",
  "members": [
    {
      "id": "user_abcde",
      "firstName": "John",
      "lastName": "Doe",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "avatarUrl": null,
      "organizationId": "org_123",
      "isDeleted": false,
      "hasTwoFactorEnabled": true,
      "createdAt": "2023-01-01T10:00:00Z",
      "updatedAt": "2023-01-01T10:00:00Z",
      "subscriptionPlan": "PRO"
    }
  ],
  "invites": [],
  "createdByUserId": "user_abcde",
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}

### Error Handling
- **400**: Invalid request body
- **401**: Unauthorized
- **403**: Forbidden - User doesn't have a Pro subscription
```

--------------------------------

### Get Form Data

Source: https://developers.tally.so/api-reference/endpoint/forms/get

Retrieves the data for a specific form, including its structure and configuration. This endpoint is useful for displaying forms to users or for processing form submissions.

```APIDOC
## GET /api/v1/forms/{formId}

### Description
Retrieves the data for a specific form, including its structure and configuration.

### Method
GET

### Endpoint
/api/v1/forms/{formId}

### Parameters
#### Path Parameters
- **formId** (string) - Required - The unique identifier of the form to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the form.
- **name** (string) - The name of the form.
- **description** (string) - A description of the form.
- **fields** (array) - An array of form field objects.

#### Response Example
{
  "id": "form_123",
  "name": "Customer Feedback",
  "description": "Collect feedback from our customers.",
  "fields": [
    {
      "type": "TEXT",
      "name": "customerName",
      "label": "Your Name"
    },
    {
      "type": "RATING",
      "name": "satisfaction",
      "label": "Overall Satisfaction"
    }
  ]
}
```

--------------------------------

### Listing Invites

Source: https://developers.tally.so/llms.txt

Returns a list of all invites in your organization.

```APIDOC
## GET /organizations/invites

### Description
Returns a list of all invites in your organization.

### Method
GET

### Endpoint
/organizations/invites
```

--------------------------------

### Creating Invites

Source: https://developers.tally.so/llms.txt

Invites users to join specific workspaces within your organization.

```APIDOC
## POST /organizations/invites

### Description
Invites users to join specific workspaces within your organization.

### Method
POST

### Endpoint
/organizations/invites
```

--------------------------------

### Listing Users

Source: https://developers.tally.so/llms.txt

Returns a list of all users in your organization.

```APIDOC
## GET /organizations/users

### Description
Returns a list of all users in your organization.

### Method
GET

### Endpoint
/organizations/users
```

--------------------------------

### Fetch Form Submissions

Source: https://developers.tally.so/documentation/fetching-form-submissions

Retrieve all submissions for a given form by sending a GET request to the `/forms/:id/submissions` endpoint. This includes form metadata, questions, and the actual submissions with their responses.

```APIDOC
## GET /forms/:id/submissions

### Description
Retrieve submissions for a form using the Tally API. This endpoint returns a paginated list of submissions along with form metadata and question details.

### Method
GET

### Endpoint
`/forms/:id/submissions`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the form.

#### Query Parameters
* **page** (integer) - Optional - The page number of submissions to retrieve. Defaults to 1.
* **limit** (integer) - Optional - The maximum number of submissions to return per page. Defaults to 50.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```bash
curl -X GET 'https://api.tally.so/forms/:id/submissions' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
Returns an object containing pagination details, form questions, and a list of submissions. Each submission includes its ID, form ID, respondent ID, completion status, submission timestamp, and the actual responses linked to question IDs.

- **page** (integer) - The current page number.
- **limit** (integer) - The number of submissions per page.
- **hasMore** (boolean) - Indicates if there are more submissions available.
- **totalNumberOfSubmissionsPerFilter** (object) - Counts of submissions filtered by status (all, completed, partial).
  - **all** (integer) - Total number of all submissions.
  - **completed** (integer) - Total number of completed submissions.
  - **partial** (integer) - Total number of partial submissions.
- **questions** (array) - An array of question objects from the form.
  - **id** (string) - The unique identifier of the question.
  - **type** (string) - The type of the question (e.g., INPUT_TEXT).
  - **title** (string) - The title or label of the question.
  - **fields** (array) - Details about the input fields for the question.
- **submissions** (array) - An array of submission objects.
  - **id** (string) - The unique identifier of the submission.
  - **formId** (string) - The ID of the form this submission belongs to.
  - **respondentId** (string) - The ID of the respondent.
  - **isCompleted** (boolean) - Whether the submission is completed.
  - **submittedAt** (string) - The timestamp when the submission was made.
  - **responses** (array) - An array of response objects within the submission.
    - **id** (string) - The unique identifier of the response.
    - **questionId** (string) - The ID of the question this response answers.
    - **answer** (any) - The answer provided for the question.

#### Response Example
```json
{
  "page": 1,
  "limit": 50,
  "hasMore": false,
  "totalNumberOfSubmissionsPerFilter": {
    "all": 4,
    "completed": 4,
    "partial": 0
  },
  "questions": [
    {
      "id": "EKOE2N",
      "type": "INPUT_TEXT",
      "title": "First name",
      "fields": [
        {
          "uuid": "21dd98ef-4c54-4e77-bcc6-7ec79409b3ea",
          "type": "INPUT_FIELD",
          "questionType": "INPUT_TEXT",
          "title": "First name"
        }
      ]
    }
  ],
  "submissions": [
    {
      "id": "GG6z5L",
      "formId": "mexJoq",
      "respondentId": "jzQdR9",
      "isCompleted": true,
      "submittedAt": "2024-12-30T09:02:01.000Z",
      "responses": [
        {
          "id": "4r5rAWb",
          "questionId": "EKOE2N",
          "answer": "Filip"
        }
      ]
    }
  ]
}
```
```