# Gately API Documentation

The Gately API is a RESTful API that allows you to programmatically interact with your Gately project. Use it to manage users, forms, content, and more.

## Base URL

All API requests should be made to:

```
https://api.usegately.com/api/v1
```

The legacy `/sdk` path is still supported for backward compatibility but is deprecated. New integrations should use `/api/v1`.

## API Playground

**Try it live!** Each API endpoint page has an interactive playground. Enter your API key and test requests directly from the documentation.

To use the API playground:

1. Get your API key from **Dashboard → Settings → API Keys**
2. Click on any endpoint in the sidebar
3. Enter your API key in the Authorization field (format: `gately_sk_live_xxxxx`)
4. Fill in the parameters and click **Send**

Make sure you’re using a valid API key that starts with `gately_`. Project IDs won’t work - you need an actual API key from your dashboard.

## Available Endpoints

The Gately API provides endpoints for:

| Category | Description |
| --- | --- |
| **Authentication** | Login, signup, magic links, SSO |
| **Members** | CRUD operations for project members |
| **Forms** | Form management and submissions |
| **Analytics** | Page views, events, and statistics |
| **Plans** | Subscription plans and management |
| **Discussions** | Community discussions and comments |
| **Ecommerce** | Products, cart, and orders |
| **Help Center** | Knowledge base articles and search |
| **Feedback** | Customer feedback collection |
| **LMS** | Courses, enrollments, and progress |
| **Member Content** | Page protection rules |
| **Storage** | File uploads |
| **Webhooks** | Event notifications |

## Authentication

The API uses API key authentication. Your API key contains the project context, so no separate project ID is needed.

### API Key Authentication

Include your API key in the `Authorization` header:

```
curl -X GET "https://api.usegately.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### JWT Authentication (Client-side)

For client-side requests from authenticated users, use the JWT token from a user session:

```
curl -X GET "https://api.usegately.com/api/v1/user/profile" \
  -H "Authorization: Bearer USER_JWT_TOKEN"
```

## Request Headers

All requests must include:

| Header | Description |
| --- | --- |
| `Authorization` | Bearer token (API key or JWT) |
| `Content-Type` | `application/json` for POST/PUT requests |

## Response Format

All responses are returned in JSON format:

```
{
  "success": true,
  "data": {
    // Response data
  }
}
```

### Error Responses

```
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## HTTP Status Codes

| Code | Description |
| --- | --- |
| `200` | Success |
| `201` | Created |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing authentication |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Resource doesn’t exist |
| `422` | Validation Error - Invalid input data |
| `429` | Rate Limited - Too many requests |
| `500` | Server Error - Something went wrong |

## Rate Limiting

API requests are rate limited to ensure fair usage:

- **Standard**: 100 requests per minute
- **Authentication endpoints**: 20 requests per minute

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
```

## Pagination

List endpoints support pagination:

```
GET /api/members?page=1&limit=20
```

Response includes pagination metadata:

```
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}
```

## Filtering & Sorting

Many endpoints support filtering and sorting:

```
# Filter by status
GET /api/members?status=active

# Sort by created date
GET /api/members?sort=created_at&order=desc

# Search
GET /api/members?search=john
```

## SDKs & Libraries

We provide official SDKs for common platforms:

[**JavaScript SDK** 
\
For browsers and Node.js](/content/docs/sdk/introduction/index.html)

[**React Hooks** 
\
React-specific hooks and components](/content/docs/sdk/introduction/index.html)

## Need Help?

[**API Keys** 
\
Learn how to create and manage API keys](/content/docs/api-reference/api-keys/index.html)

[**Webhooks** 
\
Set up real-time event notifications](/content/docs/api-reference/webhooks/overview.mdx)