Getting Started - G-Tateth API Documentation

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, or any HTTP library in your language of choice
The base URL for your target environment (see 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

Log in to your G-Tateth account
Go to Settings → Developer Console
Click Create API Key
Choose your environment (production or staging)
Select the permissions your key needs (see Authentication for the full permission list)
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):

curl https://api.g-tateth.com/api/v1/health

Expected response:

{ "status": "ok" }

Step 3 — Make your first authenticated request

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

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:

curl -H "X-API-Key: sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations

A successful response looks like:

{
  "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:

# 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:

# 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

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

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

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:

{
  "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 for full details and code examples.

Rate limits

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

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 for backoff examples and per-key custom limits.

API reference and Swagger UI

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

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:

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.

Using the SDKs

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

JavaScript / TypeScript

npm install @g-tateth/sdk

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 for the full reference.

Python

pip install gtateth-sdk

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 for the full reference.

Next steps

Authentication guide — permissions, key rotation, IP whitelisting
Webhooks guide — subscribe to real-time events
Rate Limits guide — limits, headers, and backoff strategies
Error Handling guide — all error codes with fix guidance
Postman Collection — import and explore the API interactively

​Prerequisites

​Base URLs

​Step 1 — Create an API key

​Step 2 — Verify connectivity

​Step 3 — Make your first authenticated request

​Pagination

​Common request examples

​Create a customer

​Create a conversation

​Register a webhook

​Error responses

​Rate limits

​API reference and Swagger UI

​Using the SDKs

​JavaScript / TypeScript

​Python

​Next steps