> ## 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 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](https://docs.lerian.studio/pt/platform/narya/what-is-narya.md).

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

***

Na sua própria máquina, o host escuta em um Unix socket.

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 -H "Authorization: Bearer <token>" 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

***

`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.

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, e responde `404` para uma sessão que este host não tem. `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. O host apaga os eventos de um turno depois que o turno termina. Quando uma retomada pula esses eventos, o stream abre com um evento `replay-gap`. O `payload.forgottenThrough` dele é o maior id de evento que o stream esqueceu. Quando a sua última leitura da transcrição terminou abaixo desse id, leia a transcrição de novo e retome a partir do `lastEventId` dela. Uma leitura que o alcançou já tem o que foi esquecido. 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`.

## 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`. 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."
}
```

> [card] [A API do host](https://docs.lerian.studio/pt/platform/narya/the-host-api.md)
>
> Leia o que o host serve e por que o contrato tem este formato.

> [card] [Lista de erros](https://docs.lerian.studio/pt/reference/platform/narya/host-api-error-list.md)
>
> Consulte todos os códigos que o host responde.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.