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

# Getting Started

Welcome to the G-Tateth CRM API. This guide walks you from zero to your first successful API call.

## Prerequisites

Before you begin, make sure you have:

* A G-Tateth account with at least one workspace (tenant)
* Access to **Settings → Developer Console** (Admin or Owner role required to create API keys)
* A tool to make HTTP requests: `curl`, [Postman](https://postman.com), or any HTTP library in your language of choice
* The base URL for your target environment (see [Base URLs](#base-urls) below)

***

## Base URLs

| Environment    | Base URL                           |
| -------------- | ---------------------------------- |
| **Production** | `https://api.g-tateth.com`         |
| **Staging**    | `https://staging-api.g-tateth.com` |
| **Local dev**  | `http://localhost:3001`            |

All API paths are relative to the base URL, e.g. `https://api.g-tateth.com/api/v1/conversations`.

***

## Step 1 — Create an API key

1. Log in to your G-Tateth account
2. Go to **Settings → Developer Console**
3. Click **Create API Key**
4. Choose your environment (`production` or `staging`)
5. Select the permissions your key needs (see [Authentication](/guides/authentication) for the full permission list)
6. Copy the full key — **it is only shown once**

Production keys start with `sk_live_`. Staging keys start with `sk_test_`.

> **Note:** Test keys are automatically blocked in the production environment.

***

## Step 2 — Verify connectivity

Before making authenticated requests, confirm the API is reachable (no auth required):

```bash theme={null}
curl https://api.g-tateth.com/api/v1/health
```

Expected response:

```json theme={null}
{ "status": "ok" }
```

***

## Step 3 — Make your first authenticated request

Pass your API key in the `Authorization` header as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations
```

Alternatively, use the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations
```

A successful response looks like:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "64a1b2c3d4e5f6789012345a",
      "subject": "Customer inquiry about billing",
      "status": "open",
      "priority": "medium",
      "channel": "email",
      "customerId": "64a1b2c3d4e5f6789012345b",
      "inboxId": "64a1b2c3d4e5f6789012345d",
      "createdAt": "2026-05-01T09:00:00.000Z",
      "updatedAt": "2026-05-01T09:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 243,
    "page": 1,
    "limit": 50,
    "totalPages": 5
  }
}
```

***

## Pagination

All list endpoints return paginated results. Use the `page` and `limit` query parameters to navigate:

```bash theme={null}
# Page 2, 20 items per page
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.g-tateth.com/api/v1/conversations?page=2&limit=20"
```

**Pagination parameters:**

| Parameter | Default            | Max   | Description           |
| --------- | ------------------ | ----- | --------------------- |
| `page`    | `1`                | —     | Page number (1-based) |
| `limit`   | varies by endpoint | `100` | Items per page        |

**Pagination response fields:**

| Field        | Description                                       |
| ------------ | ------------------------------------------------- |
| `total`      | Total number of matching records across all pages |
| `page`       | Current page number                               |
| `limit`      | Items returned on this page                       |
| `totalPages` | Total number of pages (`ceil(total / limit)`)     |

To retrieve all records, iterate pages until `page >= totalPages`:

```bash theme={null}
# Fetch all conversations, 100 at a time
curl -H "Authorization: Bearer sk_live_..." \
  "https://api.g-tateth.com/api/v1/conversations?page=1&limit=100"
# Then page=2, page=3, ... until page >= totalPages
```

***

## Common request examples

### Create a customer

```bash theme={null}
curl -X POST https://api.g-tateth.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+2348012345678",
    "company": "Acme Corp",
    "tier": "gold",
    "tags": ["vip", "enterprise"]
  }'
```

### Create a conversation

```bash theme={null}
curl -X POST https://api.g-tateth.com/api/v1/conversations \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Support request: billing issue",
    "inboxId": "64a1b2c3d4e5f6789012345d",
    "customerId": "64a1b2c3d4e5f6789012345b",
    "channel": "email",
    "priority": "high"
  }'
```

### Register a webhook

```bash theme={null}
curl -X POST https://api.g-tateth.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My production webhook",
    "url": "https://myapp.com/webhooks/g-tateth",
    "events": ["conversation.created", "customer.updated", "call.completed"],
    "retryPolicy": {
      "maxRetries": 3,
      "backoffStrategy": "exponential"
    }
  }'
```

***

## Error responses

All errors follow this shape:

```json theme={null}
{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}
```

Common error codes:

| Code                  | HTTP Status | Meaning                                       |
| --------------------- | ----------- | --------------------------------------------- |
| `AUTH_REQUIRED`       | 401         | No credentials provided                       |
| `API_KEY_INVALID`     | 401         | Key doesn't exist or was revoked              |
| `API_KEY_EXPIRED`     | 401         | Key has passed its expiry date                |
| `PERMISSION_DENIED`   | 403         | Key lacks the required permission             |
| `PLAN_LIMIT_EXCEEDED` | 403         | Monthly API call quota reached                |
| `RESOURCE_NOT_FOUND`  | 404         | Requested ID doesn't exist                    |
| `VALIDATION_ERROR`    | 422         | Request body or params failed validation      |
| `RATE_LIMIT_EXCEEDED` | 429         | Too many requests — check `X-RateLimit-Reset` |

See the [Error Handling guide](/guides/error-handling) for full details and code examples.

***

## Rate limits

Rate limits are enforced per API key. Every response includes these headers:

```http theme={null}
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1746394800
```

`X-RateLimit-Reset` is a Unix timestamp. When you receive a `429`, wait until that timestamp before retrying.

Default limits by plan:

| Plan                   | Limit           |
| ---------------------- | --------------- |
| Starter / Standard     | 500 req/hour    |
| Professional / Premium | 5,000 req/hour  |
| Enterprise             | 50,000 req/hour |

See the [Rate Limits guide](/guides/rate-limits) for backoff examples and per-key custom limits.

***

## API reference and Swagger UI

The interactive API explorer (Swagger UI) is available at:

```text theme={null}
https://api.g-tateth.com/api-docs/
```

> **Note:** Swagger UI requires a valid JWT session (log in to your G-Tateth account in the same browser).

The raw OpenAPI 3.0 spec (JSON) — suitable for Postman import, code generators, and contract testing — is at:

```text theme={null}
https://api.g-tateth.com/api-docs/spec.json
```

A static copy of the spec is also available in the repository at [`docs/openapi.json`](../openapi.json).

***

## Using the SDKs

Official SDKs handle auth, pagination, and retries for you.

### JavaScript / TypeScript

```bash theme={null}
npm install @g-tateth/sdk
```

```typescript theme={null}
import { createClient } from '@g-tateth/sdk';

const client = createClient({ apiKey: 'sk_live_your_api_key' });

const conversations = await client.conversations.list({ status: 'open' });
const customer = await client.customers.create({
  firstName: 'Jane',
  email: 'jane@example.com'
});
```

See the [JavaScript SDK documentation](/sdks/javascript) for the full reference.

### Python

```bash theme={null}
pip install gtateth-sdk
```

```python theme={null}
from gtateth import GtatethClient

client = GtatethClient(api_key='sk_live_your_api_key')
conversations = client.conversations.list(status='open')
customers = client.customers.list(tier='gold')
```

See the [Python SDK documentation](/sdks/python) for the full reference.

***

## Next steps

* [Authentication guide](/guides/authentication) — permissions, key rotation, IP whitelisting
* [Webhooks guide](/guides/webhooks) — subscribe to real-time events
* [Rate Limits guide](/guides/rate-limits) — limits, headers, and backoff strategies
* [Error Handling guide](/guides/error-handling) — all error codes with fix guidance
* [Postman Collection](/guides/postman-collection) — import and explore the API interactively