# API Reference

> Tarout REST API documentation

# API Reference

Tarout provides a REST API for programmatic access to all platform features. The API is built on tRPC with OpenAPI support.

## Base URL

```
https://tarout.sa/api
```

## Authentication

All API requests require authentication via an API key or session token.

### API Keys

Generate an API key in **Settings → API Keys**.

```bash
curl https://tarout.sa/api/v1/applications \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Session Tokens

When using the CLI or browser, session tokens are managed automatically.

## Common Endpoints

### Applications

```bash
# List applications
GET /api/v1/applications

# Get application details
GET /api/v1/applications/:id

# Create application
POST /api/v1/applications

# Deploy application
POST /api/v1/applications/:id/deploy

# Delete application
DELETE /api/v1/applications/:id
```

### Databases

```bash
# List databases
GET /api/v1/databases

# Create database
POST /api/v1/databases

# Delete database
DELETE /api/v1/databases/:id
```

### Domains

```bash
# List domains
GET /api/v1/domains

# Add domain
POST /api/v1/domains

# Delete domain
DELETE /api/v1/domains/:id
```

## Response Format

All responses follow this format:

```json
{
  "result": {
    "data": { ... }
  }
}
```

## Error Handling

Errors return appropriate HTTP status codes:

| Code | Description |
|------|-------------|
| `400` | Bad request - invalid parameters |
| `401` | Unauthorized - missing or invalid authentication |
| `403` | Forbidden - insufficient permissions or suspended account |
| `404` | Not found - resource doesn't exist |
| `429` | Rate limited - too many requests |
| `500` | Internal server error |

## Rate Limits

API requests are rate-limited to prevent abuse. If you exceed the limit, you'll receive a `429` response with a `Retry-After` header.

## AI Gateway

The AI Gateway is an OpenAI-compatible endpoint for chat completions:

```
https://tarout.sa/api/ai/v1
```

It serves `POST /chat/completions`, `GET /models` and `GET /models/{id}`. Usage
is billed per token in SAR from your organization's prepaid balance.

### One key for every model

A gateway key (`sk_tarout_...`) is not tied to a model. The same key calls any
model in the catalog, and each request chooses one with the `model` field. A key
has a name, an optional monthly credit limit in SAR, and an optional expiry
date. Keys created before this change work with every model too; there is
nothing to migrate.

Create a key in the [dashboard](https://tarout.sa/dashboard/ai-models/keys), or
from the CLI (`--monthly-cap` is the monthly credit limit in SAR):

```sh
tarout ai keys create --name production --monthly-cap 50
```

### Call a model with the Tarout SDK

```sh
npm install @tarout/ai
```

```ts
import Tarout from "@tarout/ai";

// Reads TAROUT_API_KEY from the environment and defaults to the
// gateway base URL above.
const client = new Tarout();

const res = await client.chat.completions.create({
  model: "glm",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(res.choices[0]?.message.content);
```

To switch models, change the `model` string. The key and everything else stay
the same:

```ts
await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### List available models

```bash
curl https://tarout.sa/api/ai/v1/models \
  -H "Authorization: Bearer $TAROUT_API_KEY"
```

The response lists every model you can call right now. Any OpenAI-compatible
client's `models.list()` calls the same endpoint, and `tarout ai models` shows
the catalog from the CLI.

To look up one model, use its ID or alias. An alias returns the model it points
at, and a model that is not live right now returns `404` with `error.code`
`model_not_found` (this is what `models.retrieve()` calls):

```bash
curl https://tarout.sa/api/ai/v1/models/glm \
  -H "Authorization: Bearer $TAROUT_API_KEY"
```

### Models

Set `model` to a model's stable alias or to its full ID. Both work.

**Global**: five open-weight flagships, one per lab.

| Model | Alias | ID |
|-------|-------|----|
| GLM 5.3 | `glm` | `z-ai/glm-5.3` |
| DeepSeek V4 Pro 0813 | `deepseek-v4-pro` | `deepseek/deepseek-v4-pro-0813` |
| Kimi K3 | `kimi-k3` | `moonshotai/kimi-k3` |
| MiniMax M3 | `minimax-m3` | `minimax/minimax-m3` |
| Qwen 3.8 2.4T A95B | `qwen3` | `qwen/qwen3.8-2.4t-a95b` |

**Saudi Arabia**: tuned for fast inference. The `-local` suffix marks models on
this route. They can be temporarily unavailable, so check
`GET /api/ai/v1/models` for what is live now. Aliases and full IDs:

```text
gpt-oss-local        groq/openai/gpt-oss-120b
gpt-oss-20b-local    groq/openai/gpt-oss-20b
qwen3.8-local        groq/qwen/qwen3.8-27b
qwen3.6-local        groq/qwen/qwen3.6-27b
```

### Errors

Every error uses the OpenAI envelope
`{"error": {"message": "...", "type": "...", "code": "..."}}`. For gateway
errors `type` and `code` carry the same value, for example `PAYMENT_REQUIRED`
(the wallet cannot cover the request), `BUDGET_EXCEEDED` (the key's monthly
credit limit is reached) or `RATE_LIMIT_EXCEEDED`. A `429` also sends a
`Retry-After` header with the number of seconds to wait. A streaming request
that fails after the stream has started ends with one `data:` event carrying the
same `error` object, followed by `data: [DONE]`.

A request for a model that is unknown or has been removed from the catalog
returns HTTP `404` with `error.type` set to `MODEL_NOT_FOUND` and this message:

```text
Model <id> is not offered. Available models: <comma-separated ids>
```

Set `model` to one of the listed IDs, or pick one from `GET /api/ai/v1/models`.
Removed models are rejected. They are never redirected to a different model.
These were removed from the Global catalog:

```text
glm-flash            z-ai/glm-5.3-flash
deepseek-v4-flash    deepseek/deepseek-v4-flash-0731
kimi-code            moonshotai/kimi-k2.7-code
qwen-flash           qwen/qwen3.8-flash
nemotron             nvidia/nemotron-3-ultra-550b-a55b
```

## Learn More

- [Authentication](https://tarout.sa/docs/api/authentication) - Detailed auth guide.
- [CLI](https://tarout.sa/docs/cli) - Use the CLI for common operations.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md