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

curl http://127.0.0.1:8080/health

Resposta

{
  "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

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

Resposta

{
  "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

{
  "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

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

{
  "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

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:

data: [DONE]

O ultimo chunk pode incluir usage se include_usage=true.

Erros

Exemplo de payload de erro:

{
  "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.