# Référence API

| API | Route | Scope |
|---|---|---|
| `chat()->send($payload)` | `POST /api/v1/chat` | `chat:create` |
| `structured()->run($payload)` | `POST /api/v1/structured` | `structured:create` |
| `tools()->execute($name,$input)` | `POST /api/v1/tools/:toolName/execute` | `tools:execute` |
| `conversations()->list($query)` | `GET /api/v1/conversations` | `conversations:read` |
| `conversations()->get($id)` | `GET /api/v1/conversations/:id` | `conversations:read` |
| `conversations()->create($payload)` | `POST /api/v1/conversations` | `conversations:read` |
| `runs()->list($query)` | `GET /api/v1/runs` | `runs:read` |
| `runs()->get($id)` | `GET /api/v1/runs/:id` | `runs:read` |

## Client

```php
new RelaiClient(
    RelaiClientOptions|string $baseUrl,
    ?string $token = null,
    ?string $appSlug = null,
    int $timeoutSeconds = 30,
    ?string $defaultProvider = null,
    ?string $defaultModel = null,
    array $headers = [],
    ?HttpClient $httpClient = null,
)
```

L'objet options et les arguments individuels sont deux modes exclusifs. `httpClient`
permet un transport custom/mock.

## Transport

```php
interface HttpClient
{
    public function request(
        string $method,
        string $path,
        array $body = [],
        array $query = [],
        array $headers = [],
    ): array;
}
```

Toutes les ressources retournent `array<string,mixed>` afin de refléter les payloads
évolutifs du Core. Les PHPDoc précisent la forme attendue. Les IDs de chemins sont
encodés avec `rawurlencode`.

## Exceptions

Toutes héritent de `RelaiException`. `RelaiApiException` expose status/body,
`RelaiTimeoutException` le délai, `RelaiValidationException` le champ concerné.

## Adaptations Core

- `conversationId` entier devient string;
- listes conservées sous `{items,total,page,limit}`;
- `chat()->send()` transmet `tools` tel quel comme allowlist générique;
- tool direct `data` devient `output`;
- `appSlug` ajouté uniquement à chat/structured;
- structured tools non vides refusés localement car Core V1 ne les supporte pas.