---
title: API Overview
description: Programmatic access to the Syntext platform via REST API.
icon: api
---

# API Overview

The Syntext API provides programmatic access to manage documentation projects, trigger builds, configure search, and more.

## Base URL

```
https://api.syntext.dev/v1
```

## Authentication

All API requests require authentication via API key:

```bash
curl https://api.syntext.dev/v1/projects \
  -H "Authorization: Bearer stx_abc12345_your_api_key"
```

API keys look like `stx_{prefix}_{secret}` and support scopes (`full`, `build`, `read`) — see [API Keys](/api-reference/api-keys/create). Create keys from the dashboard or the API.

<Warning>
Keep your API key secret. Never commit it to version control or expose it in client-side code.
</Warning>

## Request Format

- **Content-Type**: `application/json`
- **Accept**: `application/json`

```bash
curl -X POST https://api.syntext.dev/v1/projects \
  -H "Authorization: Bearer stx_abc12345_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Docs"}'
```

## Response Format

All responses return JSON with consistent structure:

### Success Response

```json
{
  "data": {
    "id": "prj_abc123",
    "name": "My Docs"
  }
}
```

### List Response

```json
{
  "data": [
    { "id": "prj_abc123", "name": "My Docs" },
    { "id": "prj_def456", "name": "API Docs" }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20
  }
}
```

See [Pagination](/api-reference/pagination) for details.

### Error Response

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}
```

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `unauthorized` | 401 | Invalid or missing API key |
| `forbidden` | 403 | API key lacks required permissions |
| `usage_limit_exceeded` | 403 | Monthly plan limit reached |
| `not_found` | 404 | Resource does not exist |
| `invalid_request` | 400 | Request validation failed |
| `rate_limited` | 429 | Too many requests |
| `internal_error` | 500 | Server error |

See [Errors](/api-reference/errors) for the full reference and retry guidance, and [Rate Limits](/api-reference/rate-limits) for limit behavior.

## API Surface

| Section | What it covers |
|---------|----------------|
| [Projects](/api-reference/projects/list) | Create and manage documentation projects |
| [Builds](/api-reference/builds/list) | Trigger, monitor, and cancel builds |
| [Audit Log](/api-reference/audit-log/list) | Per-project audit trail with CSV/JSON export |
| [Search](/api-reference/search/query) | Query and reindex full-text search |
| [Domains](/api-reference/domains/add) | Custom domain management |
| [Audiences](/api-reference/audiences/list) | Gated content access tiers |
| [API Keys](/api-reference/api-keys/list) | Create, rotate, and revoke keys |
| [AI Chat](/api-reference/chat/ask) | The AI assistant — streaming Q&A with citations |
| [Analytics](/api-reference/analytics/overview) | Tracking beacons + dashboard metrics |
| [Webhooks](/api-reference/webhooks/overview) | Git-triggered builds and signature verification |
| [Feedback](/api-reference/feedback/overview) | Page and section-level visitor feedback |
| [Pages & Content](/api-reference/pages/overview) | Read/write MDX content programmatically |
| [Collaboration](/api-reference/collaboration/overview) | Reviews, approvals, schedules, linting, access control |

## Rate Limiting

| Plan | Rate Limit |
|------|------------|
| Free | 100 requests/minute |
| Pro | 1,000 requests/minute |
| Enterprise | Custom |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705312800
```

## Pagination

List endpoints support pagination:

```bash
curl "https://api.syntext.dev/v1/projects?page=2&per_page=50"
```

| Parameter | Default | Max | Description |
|-----------|---------|-----|-------------|
| `page` | 1 | — | Page number |
| `per_page` | 20 | 100 | Items per page |

## Idempotency

For `POST` requests, use the `Idempotency-Key` header to safely retry:

```bash
curl -X POST https://api.syntext.dev/v1/builds \
  -H "Authorization: Bearer stx_abc12345_..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"project_id": "prj_abc123"}'
```

Retrying with the same key returns the original response.

## SDKs

Official SDK for TypeScript:

<CardGroup cols={1}>
  <Card title="TypeScript" icon="code" href="https://npmjs.com/package/@syntext/sdk">
    `npm install @syntext/sdk`
  </Card>
</CardGroup>

## API Resources

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/api-reference/projects">
    Create and manage documentation projects
  </Card>
  <Card title="Builds" icon="hammer" href="/api-reference/builds">
    Trigger and monitor builds
  </Card>
  <Card title="Search" icon="search" href="/api-reference/search">
    Query documentation content
  </Card>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API key management
  </Card>
</CardGroup>