> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.privategpt.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.privategpt.dev/_mcp/server.

# API Reference

> PrivateGPT REST API — endpoints, request shapes, and response formats.

PrivateGPT exposes a REST API that follows the Claude API model. All endpoints are available at `http://localhost:8080` by default.

The interactive reference below is generated from the OpenAPI schema. Use it to explore request bodies, response shapes, and try requests directly.

---

## Endpoint groups

| Group          | Endpoints                        | Description                                                              |
| -------------- | -------------------------------- | ------------------------------------------------------------------------ |
| **Messages**   | `POST /v1/messages` and variants | Chat, streaming, token counting, validation, async                       |
| **Models**     | `GET /v1/models`                 | List and inspect available models                                        |
| **Artifacts**  | `/v1/artifacts/*`                | Ingest, list, retrieve, and delete documents                             |
| **Embeddings** | `POST /v1/embeddings`            | Generate text embeddings                                                 |
| **Tools**      | `/v1/tools/*`                    | Semantic search, web search, web fetch, database query, tabular analysis |
| **Primitives** | `POST /v1/primitives/search`     | Low-level chunk retrieval                                                |
| **Skills**     | `/v1/skills/*`                   | Create and manage reusable instruction sets                              |

---

## Authentication

When auth is enabled, pass a bearer token on every request:

```bash
curl http://localhost:8080/v1/messages \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

Auth is disabled by default. Enable it in `settings.yaml`:

```yaml
server:
  auth:
    enabled: true
    secret: "Basic <base64-encoded-user:pass>"
```