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

# API Overview

> GeniusForms REST API reference

# API Overview

The GeniusForms API is a REST API that allows you to programmatically create forms, manage questions, and retrieve responses.

## Base URL

```
https://geniusforms.ai/api/v1
```

For local development:

```
http://localhost:8000/api/v1
```

## Authentication

All endpoints require an API key passed in the `X-API-Key` header. See [Authentication](/authentication) for details.

## Content Type

All requests with a body should use `Content-Type: application/json`.

## AI Credits

AI-powered endpoints (form generation, analytics, chat) consume credits. CRUD operations are always free. Every response includes `X-Credits-Remaining`, `X-Credits-Used`, and `X-Monthly-Allowance` headers. See [Pricing & Credits](/pricing) for full details.

## Question Types

GeniusForms supports 15+ question types:

| Type           | Description                   | Requires Options            |
| -------------- | ----------------------------- | --------------------------- |
| `text`         | Short text input              | No                          |
| `textarea`     | Long text input               | No                          |
| `email`        | Email address with validation | No                          |
| `number`       | Numeric input                 | No                          |
| `phone`        | Phone number                  | No                          |
| `url`          | URL with validation           | No                          |
| `date`         | Date picker                   | No                          |
| `time`         | Time picker                   | No                          |
| `select`       | Dropdown selection            | Yes                         |
| `multi_select` | Checkbox selection            | Yes                         |
| `rating`       | Star rating (1-5)             | No                          |
| `slider`       | Range slider                  | Yes (`sliderConfig`)        |
| `yes_no`       | Boolean toggle                | No                          |
| `file_upload`  | File upload                   | No                          |
| `currency`     | Currency input                | Optional (`currencyConfig`) |

### Options Examples

**Select/Multi-select:**

```json theme={null}
{
  "type": "select",
  "question": "Favorite color",
  "options": ["Red", "Green", "Blue"]
}
```

**Slider:**

```json theme={null}
{
  "type": "slider",
  "question": "How likely to recommend?",
  "sliderConfig": {
    "min": 0,
    "max": 10,
    "step": 1
  }
}
```

**Currency:**

```json theme={null}
{
  "type": "currency",
  "question": "Budget",
  "currencyConfig": {
    "currency": "USD",
    "min": 0,
    "max": 10000
  }
}
```

## Display Modes

Forms support two display modes:

| Mode          | Description                         |
| ------------- | ----------------------------------- |
| `single-page` | All questions on one page (default) |
| `multi-step`  | One question per step               |

## Common Patterns

### Create → Publish → Share

```bash theme={null}
# 1. Create form
FORM=$(curl -s -X POST https://geniusforms.ai/api/v1/forms \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Feedback", "questions": [...]}')

FORM_ID=$(echo $FORM | jq -r '.id')

# 2. Publish
curl -X POST "https://geniusforms.ai/api/v1/forms/$FORM_ID/publish" \
  -H "X-API-Key: $API_KEY"

# 3. Share URL is now live
echo "Form URL: https://geniusforms.ai/f/$(echo $FORM | jq -r '.shareUrl')"
```

### Paginate Responses

```bash theme={null}
# Get first page
curl "https://geniusforms.ai/api/v1/forms/$FORM_ID/responses?limit=50&offset=0" \
  -H "X-API-Key: $API_KEY"

# Get next page
curl "https://geniusforms.ai/api/v1/forms/$FORM_ID/responses?limit=50&offset=50" \
  -H "X-API-Key: $API_KEY"
```

## SDKs

Official SDKs coming soon. For now, use any HTTP client:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import requests

    API_KEY = "your_api_key"
    BASE_URL = "https://geniusforms.ai/api/v1"

    headers = {"X-API-Key": API_KEY}

    # List forms
    response = requests.get(f"{BASE_URL}/forms", headers=headers)
    forms = response.json()["forms"]
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const API_KEY = "your_api_key";
    const BASE_URL = "https://geniusforms.ai/api/v1";

    // List forms
    const response = await fetch(`${BASE_URL}/forms`, {
      headers: { "X-API-Key": API_KEY }
    });
    const { forms } = await response.json();
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://geniusforms.ai/api/v1/forms \
      -H "X-API-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>