Referência da API

O ollaya serve expõe duas APIs em http://localhost:11435:

• a API nativa em /api/*, modelada na do Ollama, para decisões e gerenciamento de modelos;
• a API compatível com o TypeSafe em /v1/*, idêntica em nível de protocolo à do TypeSafe, para que os SDKs TypeSafe existentes funcionem sem alterações. Consulte Compatibilidade com o TypeSafe.

/api/push e /api/blobs/:digest estão reservados e respondem 501 NOT_IMPLEMENTED. Os endpoints de texto do Ollama (/api/generate, /api/chat, /api/embed) respondem 404: os modelos de decisão nunca geram texto.

Convenções

• JSON. Os corpos de requisição e resposta são objetos JSON. O corpo é analisado como JSON qualquer que seja o Content-Type, então curl -d funciona como está. As requisições têm no máximo 8 MiB.
• Os nomes de campos usam snake_case. Campos de requisição desconhecidos são ignorados; null significa ausente.
• Os nomes de modelos são [host/][namespace/]model[:tag], sem diferenciar maiúsculas de minúsculas. Uma tag ausente significa latest. As respostas sempre usam a forma canônica, como laya:latest.
• Números. Probabilidades, confianças, score e noul são arredondados para 4 casas decimais. As durações são inteiros em nanossegundos; os carimbos de data e hora são RFC 3339 em UTC.
• Streaming. /api/pull e /api/create transmitem JSON delimitado por quebras de linha, um objeto por linha, terminando com exatamente um {"status":"success"} ou uma linha de erro. Envie "stream": false para obter uma única resposta.
• IDs de requisição. Toda resposta carrega X-Request-Id, e as respostas de /v1/* também x-typesafe-request-id. Um X-Request-Id válido enviado pelo cliente é repetido na resposta.
• Concorrência. Um modelo carregado executa uma requisição por vez, e cada requisição responde a todas as suas perguntas em uma única passada. As requisições para o mesmo modelo entram na fila, então enviar mais de uma de cada vez não termina mais cedo; o tempo de ida e volta de cada uma passa a incluir a espera. Faça todas as perguntas sobre um estado em uma única requisição. Modelos carregados diferentes são executados em paralelo.
• Nenhum download implícito. Nenhum endpoint baixa um modelo como efeito colateral. O ollaya run baixa primeiro; as aplicações chamam /api/pull.

Erros

Todo erro, em qualquer endpoint, tem este corpo:

{
  "error": "model \"laya:xl\" not found, try pulling it first",
  "code": "MODEL_NOT_FOUND"
}

O conjunto de códigos é aberto: trate um código desconhecido pelo seu status HTTP. Um erro de validação lista todos os problemas de uma vez:

{
  "error": "state: Field required; questions.urgency.score.criteria: List should have at least 2 items after validation, not 1",
  "code": "INVALID_REQUEST",
  "detail": [
    {"loc": ["body", "state"], "msg": "Field required", "type": "missing"},
    {
      "loc": ["body", "questions", "urgency", "score", "criteria"],
      "msg": "List should have at least 2 items after validation, not 1",
      "type": "too_short",
      "ctx": {"field_type": "List", "min_length": 2, "actual_length": 1}
    }
  ]
}

Depois que um stream começa, uma falha chega como última linha no mesmo formato, por exemplo {"error": "…", "code": "DIGEST_MISMATCH"}. Verifique em cada linha se há error antes de lê-la como progresso.

Perguntas

/api/decide, /v1/systemone e /api/create compartilham um único esquema de perguntas, o do TypeSafe. Uma requisição tem 1–256 perguntas, indexadas por qualquer id; as respostas voltam na mesma ordem.

• instructions pode ser uma string, um objeto, um array ou null. Quando está ausente ou é null, o modelo lê o id da pergunta, então um id descritivo como is_spam funciona sozinho.
• state é uma string, um objeto ou um array, de até 65.536 tokens. Se exceder o contexto disponível do modelo, /api/decide o trunca e reporta state_truncated: true. /v1/systemone e /v1/decisions retornam 422 STATE_TRUNCATED com o modelo que respondeu em detail[0].ctx.model.
• Limites do modelo. Cada opção precisa de espaço no contexto do modelo: cerca de 125 opções para laya:en (512 tokens) e 250 para laya:multilingual (1.024). Mais do que isso é 422 TOO_MANY_OPTIONS. Para um roteador, valem os limites do destino.

As respostas têm os formatos do TypeSafe, nesta ordem de campos:

confidence é a probabilidade máxima normalizada do TypeSafe, (K · p_max − 1) / (K − 1) para K opções: 0 quando todas as opções são igualmente prováveis, 1 quando uma opção concentra toda a probabilidade. A fórmula é a mesma para todo modelo, mas o que uma dada confiança significa não é: os modelos são calibrados de forma diferente, então ajuste um limiar por modelo nos seus próprios dados. As probabilidades são calibradas com as temperaturas de cada modelo. Em uma GPU CUDA roda o grafo fp16, cujas respostas podem diferir do fp32 em empates apertados.

keep_alive

Por quanto tempo um modelo permanece carregado depois que uma requisição termina, com a semântica do Ollama:

O cronômetro começa quando uma requisição termina, e o valor da requisição mais recente prevalece. Para um roteador, ele se aplica ao destino que respondeu. O /v1/* ignora keep_alive.

Decidir

POST /api/decide

Responde perguntas tipadas sobre um estado em uma única passada direta. O corpo é o corpo de /v1/systemone mais opções nativas; a resposta é a resposta do TypeSafe mais campos nativos, então um cliente TypeSafe também consegue analisá-la.

curl http://localhost:11435/api/decide -d '{
  "model": "laya",
  "state": "I was charged twice for my subscription this month. Please refund the second charge.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {
        "billing": "Payments, invoices and refunds",
        "technical": "Bugs, errors and outages",
        "account": "Login, profile and settings"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": ["Can wait", "Needs attention this week", "Needs attention today"]
    },
    "refund": {
      "type": "noul",
      "instructions": "The customer asks for money back.",
      "criteria": {"true": "Asks for a refund", "false": "Does not ask for a refund"}
    }
  },
  "keep_alive": "10m"
}'

{
  "model": "laya:en",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.7781,
      "probabilities": {"billing": 0.8521, "technical": 0.0611, "account": 0.0868}
    },
    "urgency": {
      "type": "score",
      "score": 1.1982,
      "confidence": 0.3418,
      "legend": {"0": "Can wait", "1": "Needs attention this week", "2": "Needs attention today"},
      "probabilities": {"0": 0.1203, "1": 0.5612, "2": 0.3185}
    },
    "refund": {"type": "noul", "noul": 0.9127}
  },
  "usage": {"input_tokens": 118, "output_tokens": 0},
  "routing": {
    "router": "laya:latest",
    "model": "laya:en",
    "route": "english",
    "reason": "English Latin text"
  },
  "state_truncated": false,
  "done_reason": "decide",
  "created_at": "2026-09-24T09:30:12.418Z",
  "total_duration": 18734512,
  "load_duration": 0,
  "eval_duration": 16302117
}

Com "extras": ["laya"], cada resposta também tem um objeto laya: confidence (a confiança do laya baseada em entropia) e act_probability (da cabeça de ato do modelo, ou null).

Imagens

Um modelo de visão (decider:2b-vision ou winnow:e4b-vision) responde perguntas sobre uma imagem além do estado. Envie a imagem em images, codificada em base64, do mesmo modo que o images do Ollama funciona:

curl http://localhost:11435/api/decide -d '{
  "model": "decider:2b-vision",
  "state": "A photo from the warehouse camera.",
  "images": ["'"$(base64 -w0 shelf.png)"'"],
  "questions": {
    "blocked": {"type": "noul", "instructions": "Is the aisle blocked?"},
    "fill": {"type": "score", "instructions": "How full is the shelf?", "criteria": ["empty", "half full", "full"]}
  }
}'

• Decider: Uma imagem por requisição, apenas PNG. O pré-processamento do modelo é reproduzido valor a valor, então os pixels precisam corresponder ao que os autores do modelo decodificam. Os decodificadores de JPEG do Rust diferem do libjpeg-turbo em até 4 níveis em alguns pixels, então o JPEG ainda não é aceito: converta-o para PNG primeiro.
• Decider: A imagem é redimensionada para múltiplos de 32 pixels, como o modelo espera, e pode ter no máximo 4.096 patches de 16x16 pixels depois disso, cerca de um megapixel (1024x1024). Uma imagem maior recebe um 422 que diz isso; reduza-a antes.
• Decider: As perguntas aceitam no máximo 10 opções. O mesmo modelo também responde a requisições apenas de texto.
• Winnow E4B vision: até 16 PNGs ordenados, 2–64 opções por pergunta, dentro do contexto combinado de imagem/estado/pergunta. O projetor correspondente é descarregado separadamente da mesma revisão do autor. As tags de texto existentes da Winnow não o carregam.
• Um modelo que não lê imagens responde a uma requisição com images com um 422.

/v1/systemone e /v1/decisions permanecem idênticos à API do TypeSafe, que não tem campo de imagem.

Carregar e descarregar. Uma requisição sem state e questions nunca decide. Sem keep_alive, ou com um valor positivo ou negativo, ela carrega o modelo (todos os destinos, no caso de um roteador) e retorna done_reason: "load". Com keep_alive: 0 ela o descarrega ("unload"). O ollaya run pré-carrega desse modo, e o ollaya stop descarrega.

curl http://localhost:11435/api/decide -d '{"model": "laya:en", "keep_alive": -1}'
curl http://localhost:11435/api/decide -d '{"model": "laya:en", "keep_alive": 0}'

Uma decisão não tem efeito colateral sobre dados armazenados, então é seguro tentar de novo.

Predefinições

Uma predefinição é um conjunto nomeado de perguntas. Seis são integradas (triage, email, guard, moderation, router, agent), e você pode salvar as suas próprias. Envie "preset": "NAME" para /api/decide no lugar de questions.

curl http://localhost:11435/api/presets/create -d '{
  "name": "billing-check",
  "description": "Billing, and how upset the customer is",
  "questions": {
    "billing": {"type": "noul", "instructions": "The message is about a charge, an invoice or a refund."},
    "tone": {"type": "choice", "instructions": "How does the customer sound?", "criteria": {"calm": null, "annoyed": null, "angry": null}}
  }
}'
curl http://localhost:11435/api/decide -d '{"model": "winnow:e4b", "state": "I was charged twice this month.", "preset": "billing-check"}'

Os nomes têm de 1 a 64 caracteres de letras minúsculas, dígitos, - e _. Um nome integrado não pode ser reutilizado (422) nem excluído (403), e um nome desconhecido é um 404. As predefinições personalizadas são armazenadas junto dos modelos, então todo cliente do servidor vê as mesmas.

Roteadores

Um roteador como laya (laya:latest) não tem pesos: para cada requisição ele escolhe um de seus destinos, que então responde. O laya lê apenas o state:

Textos curtos em maiúsculas e sem letras acentuadas, como nomes de comerciantes em uma fatura de cartão (MIGROS KADIKOY ISTANBUL TR), SKUs ou nomes de usuário, geralmente não podem ser identificados e vão para laya:en. Se você sabe o idioma, peça laya:multilingual ou laya:en diretamente; o model da resposta diz qual checkpoint respondeu.

O roteamento custa microssegundos. Ramifique com base em route, nunca em reason, cujo texto pode mudar. O laya:typed-decisions nunca é escolhido pelo roteador; peça-o diretamente.

Listar modelos locais

GET /api/tags

Os modelos nesta máquina, do mais novo para o mais antigo. Cada entrada tem name, model (o mesmo), modified_at, size em bytes, digest (sha256 do manifesto, em hex puro) e details: parent_model, format (onnx, gguf ou router), family, families, parameter_size e quantization_level (as precisões que ele carrega, como F16/F32, ou a quantização de um modelo GGUF, como Q8_0).

{
  "models": [
    {
      "name": "laya:en",
      "model": "laya:en",
      "modified_at": "2026-09-24T08:11:02.117Z",
      "size": 853634822,
      "digest": "bf30e4654e9483ff1e6a4fe6fb21b8a71baff6c8a01013046e7d13339020efd7",
      "details": {
        "parent_model": "",
        "format": "onnx",
        "family": "laya",
        "families": ["laya"],
        "parameter_size": "421M",
        "quantization_level": "F16/F32"
      }
    }
  ]
}

Mostrar detalhes de um modelo

POST /api/show

curl http://localhost:11435/api/show -d '{"model": "laya:en"}'

Um roteador é mostrado como ele mesmo, não resolvido para um destino.

Listar modelos em execução

GET /api/ps

Os modelos carregados, ordenados por nome. Os roteadores nunca aparecem; seus destinos carregados, sim. Cada entrada tem name, model, size (memória, RAM mais VRAM), digest, details (com a precisão realmente carregada: F16 ou F32, ou a quantização de um modelo GGUF), expires_at (quando ele será descarregado, ou null quando mantido carregado), size_vram, context_length e device (cpu, cuda:0, metal, …).

Baixar um modelo

POST /api/pull

{"model": "laya:en"}

Baixa o modelo para o armazenamento local e verifica cada blob em relação ao seu sha256. Baixar um roteador também baixa todos os modelos para os quais ele roteia. Só as camadas de que esta máquina precisa são baixadas, blobs compartilhados entre modelos são baixados uma vez, e downloads interrompidos são retomados.

A resposta transmite o progresso, com as strings de status do Ollama:

{"status":"pulling manifest"}
{"status":"pulling 891102d37268","digest":"sha256:891102d372688fc2a094dac56a384bc537b87c63f21f9f3dac0be2b7cbc8d86c","total":842609210,"completed":420557117}
{"status":"pulling 891102d37268","digest":"sha256:891102d372688fc2a094dac56a384bc537b87c63f21f9f3dac0be2b7cbc8d86c","total":842609210,"completed":842609210}
{"status":"verifying sha256 digest"}
{"status":"writing manifest"}
{"status":"success"}

Um modelo só aparece em /api/tags depois de writing manifest. Para um roteador há um único success, no final. Um nome que não é analisado, um modelo que não está no registro e um registro inacessível são erros HTTP comuns (422, 404, 502) antes de o stream começar, então curl --fail funciona. Com "stream": false a resposta é {"status": "success"} quando termina. Um segundo download do mesmo nome se junta ao que está em andamento. Seguro tentar de novo.

Excluir um modelo

DELETE /api/delete

{"model": "triage"}

Remove o nome, e os blobs que nenhum outro modelo usa. Um modelo carregado é descarregado assim que suas requisições terminam; excluir um roteador mantém seus destinos. A resposta é 200 com corpo vazio, e 404 MODEL_NOT_FOUND quando o nome não existe; após um timeout, trate isso como sucesso.

Copiar um modelo

POST /api/copy

{"source": "laya:en", "destination": "my-guardrail"}

Copia um modelo para um novo nome, sobrescrevendo um destino existente. A resposta é 200 com corpo vazio.

Criar um modelo

POST /api/create

A API por trás de ollaya create -f Modelfile: a CLI lê o Modelfile e os arquivos que ele nomeia e envia seus conteúdos como JSON.

curl http://localhost:11435/api/create -d '{
  "model": "triage",
  "from": "laya:en",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": ["billing", "technical", "account"]
    }
  },
  "parameters": {"precision": "fp32"},
  "description": "Support ticket triage"
}'

O stream reporta using existing layer sha256:… para cada camada herdada, creating new layer sha256:… para cada nova, depois writing manifest e success. As camadas são endereçadas por conteúdo, então repetir uma criação produz o mesmo modelo.

Versão

GET /api/version

{"version": "0.1.0"}

Endpoints compatíveis com o TypeSafe

O /v1/* ignora campos nativos como keep_alive e extras, e nunca adiciona campos nativos às suas respostas. Os erros usam o mesmo corpo que /api/*, que o SDK TypeSafe lê corretamente. Consulte Compatibilidade com o TypeSafe.

Segurança

O servidor se liga a 127.0.0.1:11435 e, como o Ollama, confia nos chamadores locais. Vinculá-lo a outro endereço (OLLAYA_HOST=0.0.0.0) permite que todos que conseguem alcançar a porta executem decisões e baixem, excluam e criem modelos, então:

• OLLAYA_API_KEY faz toda requisição, exceto GET /, HEAD / e o preflight de CORS, exigir Authorization: Bearer <key>; caso contrário, a resposta é 401 UNAUTHORIZED. O SDK TypeSafe envia sua chave desse modo, e a CLI ollaya envia $OLLAYA_API_KEY. O servidor registra um aviso quando escuta além do loopback sem uma chave.
• O TLS não é terminado pelo servidor; coloque um proxy reverso na frente para acesso remoto.
• Navegadores. Requisições com um cabeçalho Origin são permitidas apenas de localhost, 127.0.0.1, 0.0.0.0 e [::1] (qualquer porta), de webviews de aplicativos e editores, e das origens em OLLAYA_ORIGINS (separadas por vírgulas, curingas *). Um servidor em loopback também rejeita cabeçalhos Host inesperados, o que bloqueia DNS rebinding.
• Seus dados. Os estados e as perguntas nunca são registrados nem repetidos nos erros.