Skip to main content
This section is for developers. If you want a business-level overview of Narya, see What is Narya.
Narya runs coding agents behind one HTTP API. One long-lived host owns the sessions, the store and the model connections. The terminal client and the one-shot command that Lerian ships drive this API. A client you write drives the same one.

​
Transport and authorization

The host listens on a Unix socket in your Narya home. Narya creates the socket owner-only, and file permissions are the whole authorization. There is no password, no token and no TLS. The socket is narya.sock inside the Narya home. The home is $NARYA_HOME, or $XDG_CONFIG_HOME/narya, or ~/.config/narya, in that order. Requests are HTTP/1.1 with JSON bodies. Field names are camelCase. Dial the socket and send an ordinary request:
The authority in that URL is ignored, because the connection is already the socket. Any host name works.

​
Work is accepted, and results stream

Results never arrive on the response of the request that caused them. POST /v1/sessions/{sessionId}/messages answers 202 with a turn id. Everything the turn produces streams over GET /v1/events as server-sent events. Each frame carries an id: line, a data: line, and a blank line. The data payload is one JSON event envelope, and its type property says which event it is. Frames carry no event: or retry: line.
Two query parameters shape the stream. sessionId narrows it to one session. hostEvents=true adds the events that belong to no session, and it applies only beside sessionId. To resume, send the last id you received in the Last-Event-ID request header. The stream continues from the first event after it that the store still holds. Compare the first id you receive against the one you sent, and read state again through the GET operations when there is a gap. A cursor newer than anything the store holds gets 409 with code NRY-0026, and the same cursor is refused identically every time.

​
The two envelopes

A paged list answers a cursor envelope: items, limit and a nextCursor when more remains. Cursors are opaque. Pass one back as the cursor query parameter to get the next page. One error envelope: code, title and message, plus a fields map on a 422. Codes are NRY- and four digits.

The host API

Read what the host serves and why the contract has this shape.

Error list

Look up every code the host answers.