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

# Getting started with the SiteGPT API

> Learn how to authenticate and make requests to the SiteGPT API.

The SiteGPT API allows you to programmatically manage chatbots, send messages, access conversation history, and configure settings. All endpoints use REST principles and return JSON responses.

<Warning>
  This page documents the legacy `/api/v0` API. For new integrations, use **API Reference → v2** from the version selector.
</Warning>

## Base URL

All API requests are made to:

```
https://sitegpt.ai/api/v0
```

## Authentication

SiteGPT uses API keys for authentication. Include your API key in the `Authorization` header of every request.

<Note>
  This is the **legacy v0 API**. New integrations should use the
  [v2 Agent API](/docs/api-reference/v2/getting-started) with scoped `sgpt_` tokens
  from the **Agents** page.
</Note>

### Getting your API key

1. Sign in to your SiteGPT account
2. Open **Billing** in the top navigation; your API key is shown there when your plan includes API access
3. Copy your API key
4. Store it securely (never commit to version control)

<Warning>Keep your API key secure. Anyone with your key can access and modify your chatbots.</Warning>

### Using your API key

Include your API key in the `Authorization` header with the `Bearer` scheme:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://sitegpt.ai/api/v0/chatbots \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sitegpt.ai/api/v0/chatbots', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://sitegpt.ai/api/v0/chatbots',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  ```
</CodeGroup>

### Authentication errors

If your API key is missing, malformed, or invalid, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
  "success": false,
  "message": "Failed to authenticate",
  "data": null,
  "error": {
    "code": "API_KEY_NOT_VALID",
    "message": "Authorization header does not contain valid API key",
    "details": null
  }
}
```

## Response format

All API responses use a consistent JSON structure:

### Success response

```json theme={null}
{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}
```

### Error response

```json theme={null}
{
  "success": false,
  "message": "Operation failed",
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": null // or array of validation errors
  }
}
```

## Error handling

<AccordionGroup>
  <Accordion title="HTTP status codes">
    * **200 OK** - Request succeeded
    * **400 Bad Request** - Invalid request parameters or body
    * **401 Unauthorized** - Missing or invalid API key
    * **403 Forbidden** - Insufficient permissions
    * **404 Not Found** - Resource doesn't exist
    * **405 Method Not Allowed** - HTTP method not supported
    * **500 Internal Server Error** - Server error
  </Accordion>

  <Accordion title="Common error codes">
    * `API_KEY_NOT_VALID` - Invalid or missing API key
    * `REQUEST_VALIDATION_FAILED` - Request body validation failed
    * `CHATBOT_NOT_FOUND` - Chatbot doesn't exist
    * `CHATBOT_FETCH_FORBIDDEN` - No permission to access chatbot
    * `CHATBOT_LIMIT_REACHED` - Exceeded chatbot quota
    * `MESSAGES_LIMIT_REACHED` - Exceeded message quota
  </Accordion>
</AccordionGroup>

### Validation errors

When request validation fails, the `error.details` array contains specific field errors:

```json theme={null}
{
  "success": false,
  "message": "Failed to create chatbot",
  "data": null,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "Request body is not valid",
    "details": [
      {
        "path": ["chatbotName"],
        "message": "Required"
      }
    ]
  }
}
```

## Rate limiting

API requests are rate-limited to keep the platform stable. Limits depend on
your plan; when you exceed them you receive a `429 Too Many Requests`
response. Back off and retry with exponential delays.

## Pagination

List endpoints support pagination using query parameters:

```bash theme={null}
GET /v0/chatbots?page=1&limit=20
```

Parameters:

* `page` - Page number (default: 1)
* `limit` - Results per page (default: 20, max: 100)

Paginated responses include metadata:

```json theme={null}
{
  "success": true,
  "message": "Fetched chatbots successfully",
  "data": {
    "chatbots": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}
```

## Making requests

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://sitegpt.ai/api/v0/chatbots \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "chatbotName": "My New Chatbot"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sitegpt.ai/api/v0/chatbots', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatbotName: 'My New Chatbot'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://sitegpt.ai/api/v0/chatbots',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'chatbotName': 'My New Chatbot'
      }
  )

  data = response.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://sitegpt.ai/api/v0/chatbots');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'chatbotName' => 'My New Chatbot'
  ]));

  $response = curl_exec($ch);
  $data = json_decode($response, true);
  curl_close($ch);
  ?>
  ```
</CodeGroup>

## Common workflows

<AccordionGroup>
  <Accordion title="Creating and configuring a chatbot" icon="robot">
    <Steps>
      <Step title="Create chatbot">
        `POST /v0/chatbots`
      </Step>

      <Step title="Update appearance">
        `PATCH /v0/chatbots/{chatbotId}/appearance`
      </Step>

      <Step title="Add training content">
        `POST /v0/chatbots/{chatbotId}/links`
      </Step>

      <Step title="Configure settings">
        `PATCH /v0/chatbots/{chatbotId}/settings/general`
      </Step>

      <Step title="Add conversation starters">
        `POST /v0/chatbots/{chatbotId}/quick-prompts`
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Sending messages" icon="message">
    <Steps>
      <Step title="Create thread">
        `POST /v0/chatbots/{chatbotId}/threads`
      </Step>

      <Step title="Send message">
        `POST /v0/chatbots/{chatbotId}/message`
      </Step>

      <Step title="Fetch response">
        Included in send message response
      </Step>

      <Step title="Update reaction">
        `PATCH /v0/chatbots/{chatbotId}/messages/{messageId}`
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Managing conversations" icon="comments">
    <Steps>
      <Step title="Fetch all threads">
        `GET /v0/chatbots/{chatbotId}/threads`
      </Step>

      <Step title="Get thread details">
        `GET /v0/chatbots/{chatbotId}/threads/{threadId}`
      </Step>

      <Step title="Escalate to agent">
        `POST /v0/chatbots/{chatbotId}/threads/{threadId}/escalate`
      </Step>

      <Step title="Update thread">
        `PATCH /v0/chatbots/{chatbotId}/threads/{threadId}`
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## API resources

The SiteGPT API provides endpoints for:

* **Chatbots** - Create, read, update, delete chatbots
* **Appearance** - Customize chatbot visual design
* **Content** - Manage training data and custom responses
* **Messages** - Send and receive messages
* **Threads** - Manage conversation threads
* **Settings** - Configure chatbot behavior
* **Prompts** - Manage instructions and personas
* **Quick Prompts** - Conversation starters
* **Follow-up Prompts** - Post-response suggestions
* **Icons** - Upload custom icons
* **Whitelabel** - Manage white-label brands and users (enterprise)

## Best practices

<Tabs>
  <Tab title="Security">
    <Check>**Never expose API keys** - Keep them server-side only</Check>
    <Check>**Use environment variables** - Don't hardcode keys</Check>
    <Check>**Rotate keys regularly** - Generate new keys periodically</Check>
    <Check>**Limit key scope** - Use separate keys for different environments</Check>
  </Tab>

  <Tab title="Performance">
    <Check>**Cache responses** - Reduce redundant API calls</Check>
    <Check>**Batch operations** - Combine multiple updates when possible</Check>
    <Check>**Use webhooks** - Receive real-time updates instead of polling</Check>
    <Check>**Handle rate limits** - Implement exponential backoff</Check>
  </Tab>

  <Tab title="Error handling">
    <Check>**Check success field** - Always verify `success: true`</Check>
    <Check>**Log error codes** - Track error patterns</Check>
    <Check>**Retry transient errors** - Retry 500 errors with backoff</Check>
    <Check>**Validate before sending** - Reduce 400 errors</Check>
  </Tab>

  <Tab title="Data management">
    <Check>**Use metadata** - Store custom data with chatbots</Check>
    <Check>**Implement pagination** - Handle large result sets</Check>
    <Check>**Filter requests** - Use query parameters to reduce data transfer</Check>
    <Check>**Clean up resources** - Delete unused chatbots and threads</Check>
  </Tab>
</Tabs>

## Webhooks

Instead of polling the API, use webhooks to receive real-time updates:

* New messages
* Lead captures
* Conversation escalations
* Custom events

Configure webhooks in your chatbot settings or via the API.

See [Chatbot Settings - Advanced](/docs/api-reference/chatbot-settings/update-chatbot-settings--advanced) for webhook configuration.

## SDKs and libraries

### Official SDKs

Currently, SiteGPT doesn't provide official SDKs. Use standard HTTP libraries in your language of choice.

### Community libraries

Check our community forum for user-contributed libraries and wrappers.

## Support

Need help with the API?

* **Documentation** - Browse the API reference
* **Email** - [support@sitegpt.ai](mailto:support@sitegpt.ai)
* **Community** - Join our Slack or forum
* **Enterprise** - Dedicated support for enterprise customers

## Next steps

<CardGroup cols={2}>
  <Card title="Chatbot endpoints" icon="robot" href="/docs/api-reference/chatbot/fetch-all-chatbots">
    Create and manage chatbots programmatically
  </Card>

  <Card title="Messages" icon="message" href="/docs/api-reference/chatbot-messages/send-message">
    Send messages and handle conversations
  </Card>

  <Card title="Settings" icon="gear" href="/docs/api-reference/chatbot-settings/update-chatbot-settings--general">
    Configure chatbot behavior via API
  </Card>

  <Card title="Threads" icon="comments" href="/docs/api-reference/chatbot-threads/fetch-all-threads">
    Manage conversation threads
  </Card>
</CardGroup>