> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral da API do host do Narya

> O contrato HTTP entre o host do Narya e cada cliente: um Unix socket, um stream de eventos, um envelope de erro e paginação por cursor.

<Tip>
  **Esta seção é para desenvolvedores.** Se você quer uma visão geral de negócio do Narya, veja [O que é o Narya](/pt/platform/narya/what-is-narya).
</Tip>

O Narya executa agentes de codificação por trás de uma única API HTTP. Um host de longa duração é dono das sessões, do store e das conexões de modelo. O cliente de terminal e o comando one-shot que a Lerian distribui usam essa API. Um cliente que você escrever usa a mesma.

## Transporte e autorização

***

O host escuta em um Unix socket na sua pasta Narya. O Narya cria o socket apenas para o proprietário, e as permissões de arquivo são toda a autorização. Não há senha, nem token e nem TLS.

O socket é o `narya.sock` dentro da pasta Narya. A pasta é `$NARYA_HOME`, ou `$XDG_CONFIG_HOME/narya`, ou `~/.config/narya`, nessa ordem.

As requisições são HTTP/1.1 com corpos JSON. Os nomes de campo são camelCase. Conecte-se ao socket e envie uma requisição comum:

```bash theme={null}
curl --unix-socket ~/.config/narya/narya.sock http://localhost/v1/host
```

A authority dessa URL é ignorada, porque a conexão já é o socket. Qualquer nome de host funciona.

## O trabalho é aceito e os resultados chegam em stream

***

Os resultados nunca chegam na resposta da requisição que os causou. `POST /v1/sessions/{sessionId}/messages` responde `202` com um id de turn. Tudo o que o turn produz chega via stream por `GET /v1/events` como server-sent events.

Cada frame carrega uma linha `id:`, uma linha `data:`, e uma linha em branco. O payload de `data` é um único envelope de evento JSON, e sua propriedade `type` diz qual evento é. Os frames não carregam nenhuma linha `event:` ou `retry:`.

```
id: 1011
data: {"id":"1011","type":"turn-finished","sessionId":"6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d","timestamp":"2026-08-08T12:05:00Z","payload":{"turnId":"4d8e2f6a-0b1c-4d3e-9f5a-7b9c1d3e5f0a","stopReason":"completed"}}

```

Dois parâmetros de query moldam o stream. `sessionId` o restringe a uma única sessão. `hostEvents=true` adiciona os eventos que não pertencem a nenhuma sessão, e ele apenas se aplica ao lado de `sessionId`.

Para retomar, envie o último id que você recebeu no header `Last-Event-ID` da requisição. O stream continua a partir do primeiro evento depois dele que o store ainda contém. Compare o primeiro id que você recebe com o que você enviou, e leia o estado novamente por meio das operações `GET` quando houver uma lacuna. Um cursor mais recente do que qualquer coisa que o store contém recebe `409` com o código `NRY-0026`, e o mesmo cursor é recusado de forma idêntica todas as vezes.

## Os dois envelopes

***

Uma lista paginada responde com um envelope de cursor: `items`, `limit` e um `nextCursor` quando resta mais conteúdo. Os cursors são opacos. Passe um de volta como o parâmetro de query `cursor` para obter a próxima página.

Um envelope de erro: `code`, `title` e `message`, além de um mapa `fields` em um `422`. Os códigos são `NRY-` e quatro dígitos.

```json theme={null}
{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}
```

<Columns cols={2}>
  <Card title="A API do host" icon="server" href="/pt/platform/narya/the-host-api">
    Leia o que o host serve e por que o contrato tem este formato.
  </Card>

  <Card title="Lista de erros" icon="triangle-exclamation" href="/pt/reference/platform/narya/host-api-error-list">
    Consulte todos os códigos que o host responde.
  </Card>
</Columns>