> ## 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. # A API do host > Um host, um contrato HTTP. Todo cliente Narya conduz a mesma API, e você pode escrever a sua contra ela. O Narya roda agentes de código atrás de uma API HTTP. Um host de vida longa faz o trabalho, e todo cliente conduz essa mesma API. A API tem um documento OpenAPI 3.1. A Lerian gera o servidor do host e seu próprio cliente Go a partir desse documento. Três tipos de cliente a falam. O cliente de terminal que a Lerian entrega abre uma sessão interativa. O comando de execução única `narya -p` roda um prompt para um pipeline. Um cliente que você escreve conduz as mesmas operações com um token próprio. ## De que o host é dono *** * **Sessões**: conversas duradouras, cada uma ligada a um caminho de repositório. * **Faixas**: as trilhas paralelas dentro de uma sessão. * **Checkpoints e rebobinagens**: pontos de restauração da sua árvore de trabalho e os movimentos de volta até eles. * **O armazenamento**: o banco de dados que guarda as sessões e as decisões. O host toma o lock dele. * **Conexões com os modelos**: o host chama o fornecedor do modelo com a sua credencial. * **Agendamentos**: prompts no relógio do host. * **Workflows**: programas JavaScript que orquestram agentes. * **Monitores**: comandos de longa duração ao lado de uma sessão, cuja saída chega à conversa. Um monitor iniciado com `wake` definido como `true` começa um turno quando a saída dele chega enquanto a conversa está ociosa. Quem o iniciou paga por esse turno. * **Perguntas de permissão**: as perguntas antes de uma chamada de ferramenta e as respostas que você devolve. * **Sessões de produto**: sessões sobre a API de um produto Lerian, em que cada escrita espera pelo dono. Veja [Rodar o Narya](https://docs.lerian.studio/pt/platform/narya/running-narya.md#product-sessions). ## Chegar ao host *** Na sua própria máquina, o host escuta em um socket Unix na sua pasta Narya. O Narya cria o socket apenas para o dono, e o socket não usa TLS. A requisição de uma pessoa carrega um bearer token do provedor de identidade definido nas suas configurações `[identity]`. O host verifica a assinatura, o emissor, a expiração, e a pessoa e a organização que o token nomeia. Uma requisição com um token que não é válido recebe `401` com `NRY-0011`. Um chamador cujo papel não tem a permissão que uma operação exige recebe `403` com `NRY-0028`. Uma operação que declara outro esquema de segurança também aceita essa credencial: o stream de eventos aceita a requisição assinada de uma extensão registrada. Na sua própria máquina, o host também aceita uma requisição sem token do seu próprio usuário do sistema operacional. Essa requisição recebe `401` com `NRY-0011` no trabalho que chega à sua organização além desta máquina. [Rodar o Narya](https://docs.lerian.studio/pt/platform/narya/running-narya.md) diz quando o host exige autenticação. Qualquer outra requisição sem credencial recebe `401` com `NRY-0011`. Quando você está autenticado, os clientes que a Lerian entrega apresentam o token que o `narya login` guardou. O socket é o `narya.sock` dentro da sua pasta Narya, que é `~/.config/narya` por padrão. Defina `NARYA_HOME` para mudá-la de lugar. Sobre esse socket o host fala HTTP/1.1 e responde JSON com campos em camelCase. A autoridade na URL não carrega nada, então qualquer nome funciona ali. ```bash theme={null} TOKEN="an-access-token-from-your-identity-provider" curl --unix-socket ~/.config/narya/narya.sock \ -H "Authorization: Bearer $TOKEN" \ http://narya/v1/host # Answers one JSON object about the running host. ``` Quando um host está rodando, o comando de execução única é ele próprio um cliente dessa API. Uma execução única que não encontra host abre o armazenamento por conta própria, quando nenhum outro processo Narya o segura. ## Quem responde a uma pergunta de permissão *** Uma pergunta de permissão espera por uma resposta apenas em uma sessão acompanhada. Uma sessão que o seu cliente cria sem `clientKind`, ou com `api`, não é acompanhada. O host recusa cada pergunta nela e registra um motivo. Nomeie `inline` ou `tui` como `clientKind` quando uma pessoa responde às perguntas do seu cliente, ou chame `PUT /v1/sessions/{sessionId}/posture` com `attended`. Em um diretório em que ninguém confia, o host recusa um turno de uma sessão `api`, e a mensagem diz como confiar no diretório. [Permissões e confiança](https://docs.lerian.studio/pt/platform/narya/permissions-and-trust.md#attended-and-detached-sessions) traz a regra completa. ## Os resultados chegam pelo stream de eventos *** Uma mensagem responde `202` com um id de turno. Tudo o que esse turno produz chega a você em `GET /v1/events` como server-sent events. Envie uma `idempotencyKey` com uma mensagem, e um reenvio cuja resposta se perdeu não começa um segundo turno. Novas faixas, agendamentos, execuções de workflow e resumos também aceitam uma chave. A linha `data` carrega um envelope JSON. O campo `type` dele diz qual é esse evento: um delta de texto, uma chamada de ferramenta, uma pergunta de permissão, um turno terminado. Um cliente lê um formato e se ramifica por `type`. Envie um header `Last-Event-ID` para retomar de onde parou. Um cursor que nomeia um evento mais novo que o armazenamento responde `409`. Um consumidor lento demais para acompanhar perde a própria conexão, e todos os outros clientes seguem recebendo o stream. Dois parâmetros de query estreitam o stream. O `sessionId` mantém uma sessão. O `hostEvents=true` acrescenta os eventos que não pertencem a nenhuma sessão, e apenas se aplica ao lado do `sessionId`. O `narya -p --json` imprime esses mesmos envelopes, um por linha. Um pipeline e um cliente leem um formato só. Veja [Automação e CI](https://docs.lerian.studio/pt/platform/narya/automation-and-ci.md). ## Um formato para listas e erros *** Uma lista paginada responde um envelope de cursor: `items`, `limit` e um `nextCursor` quando ainda resta algo. Os cursores são opacos, e a API não oferece paginação por offset. O armazenamento recebe muitas inserções, então um offset se desloca sob uma escrita concorrente. Um envelope de erro: `code`, `title` e `message`. Um código é `NRY-` e quatro dígitos. A [lista de erros](https://docs.lerian.studio/pt/reference/platform/narya/host-api-error-list.md) nomeia cada código e o que fazer com ele. ## Leia a referência *** > [card] [Visão geral da API do host do Narya](https://docs.lerian.studio/pt/reference/platform/narya/host-api-overview.md) > > Visão geral da API do host do Narya: transporte, streaming, envelopes e cada operação. > [card] [Lista de erros da API do host do Narya](https://docs.lerian.studio/pt/reference/platform/narya/host-api-error-list.md) > > Cada código com que o host responde, o que o dispara e a saída. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.