ForgeLM/docs/api/endpoints.md

# Endpoints HTTP

Esta pagina documenta a superficie HTTP publica atual do ForgeLM.

## Base URL

- default de bind: `0.0.0.0:8080`
- endereco recomendado para consumo local: `http://127.0.0.1:8080`

Quando esta documentacao usa `127.0.0.1`, ela esta descrevendo o endereco tipico de consumo local, nao necessariamente o bind literal do processo.

## GET /health

Retorna um snapshot simples do estado do processo.

### Auth

- nao exige auth

### Exemplo

```bash
curl http://127.0.0.1:8080/health
```

### Resposta

```json
{
  "status": "ok",
  "model_loaded": true,
  "model_id": "meu-modelo",
  "uptime_secs": 42
}
```

### Observacoes

- hoje `model_loaded` funciona como um sinal operacional simples do processo em pe
- o app desktop usa `GET /health` como parte do readiness check do runtime local

## GET /v1/models

Lista o modelo canonico e aliases conhecidos.

### Auth

- exige auth apenas se `LOCALLLM_API_KEY` estiver configurada

### Cabecalhos aceitos

- `Authorization: Bearer <token>`
- `x-api-key: <token>`
- ou o cabecalho custom configurado em `LOCALLLM_AUTH_HEADER`

### Exemplo

```bash
curl http://127.0.0.1:8080/v1/models
```

### Resposta

```json
{
  "object": "list",
  "data": [
    {
      "id": "default",
      "object": "model",
      "created": 1710000000,
      "owned_by": "local",
      "root": "meu-modelo",
      "parent": "meu-modelo",
      "permission": []
    }
  ]
}
```

### Observacoes

- `root` aponta para o modelo canonico
- `parent` e usado quando um ID e alias do modelo canonico
- o app desktop usa esse endpoint para preencher o seletor de modelo

## POST /v1/chat/completions

Endpoint principal de inferencia.

### Auth

- exige auth apenas se `LOCALLLM_API_KEY` estiver configurada

### Campos principais da request

```json
{
  "model": "default",
  "messages": [
    { "role": "user", "content": "Explique este projeto" }
  ],
  "max_tokens": 1024,
  "temperature": 0.15,
  "top_p": 0.95,
  "stream": false,
  "stop": [],
  "n": 1,
  "seed": null,
  "user": null,
  "response_format": null,
  "tools": [],
  "tool_choice": null,
  "parallel_tool_calls": null,
  "stream_options": null
}
```

### Defaults importantes

- `max_tokens`: `1024`
- `temperature`: `0.15`
- `top_p`: `0.95`
- `n`: `1`

### Regras de validacao

- `model` deve existir no catalogo de modelos
- `messages` nao pode ser vazio
- `n` precisa ser `1`
- `tools` podem ser rejeitadas se tool calling estiver desabilitado

### Exemplo sem streaming

```bash
curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Diga ola"}],
    "stream": false
  }'
```

### Resposta sem streaming

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "meu-modelo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Ola!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20,
    "tokens_per_second": 31.5
  }
}
```

### Exemplo com streaming

```bash
curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Escreva um resumo"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'
```

### Streaming SSE

O backend envia eventos `data: ...` no formato `chat.completion.chunk` e termina com:

```text
data: [DONE]
```

O ultimo chunk pode incluir `usage` se `include_usage=true`.

### Erros

Exemplo de payload de erro:

```json
{
  "error": {
    "message": "Only n=1 is currently supported",
    "type": "invalid_request_error",
    "param": "n",
    "code": "unsupported_value"
  }
}
```

### Limitacoes atuais

- o servidor nao implementa toda a plataforma OpenAI
- `parallel_tool_calls` nao deve ser tratado como recurso plenamente suportado
- o campo `content` de mensagens pode aceitar arrays de partes textuais, mas o backend reduz isso a texto consolidado
- reasoning nativo nao aparece como campo separado na API HTTP; o app desktop separa `<think>...</think>` no frontend

## Codigos de status mais comuns

- `200 OK` - sucesso
- `400 Bad Request` - payload invalido ou modo nao suportado
- `401 Unauthorized` - chave ausente/invalida quando auth esta habilitada
- `404 Not Found` - modelo nao encontrado

Para configuracao do servidor e variaveis de ambiente, veja `configuration.md`.