Skip to main content
The client comes from r5d.dev’s npm registry, npm.r5d.dev:
Create an API key in r5d settings or with r5dctl auth api-key create. Keep it in your application’s secret configuration:
The client also accepts a device credential as token. Credentials belong to one installation; use the matching baseUrl for production, stage, or your own server.

Browse session trees

client.projects.sessions.list(projectRef, { branch?, mine? }) returns only top-level sessions. Each R5dctlSessionListEntry includes parentSessionId, numeric childCount, live runState, and project/branch context (null for workspace children). The list also has the top-level sessions your teams share with you on the project’s repository, each with owner and shared (the team you read it through and its path), its teammate’s projectPath and a null projectId; mine: true leaves them out.
Children are one generation only and follow owned parent relationships across projects, branches and workers. Both lists sort by the session’s own catalog updatedAt descending, then ID ascending; counts exclude hidden/deleted and inaccessible children. A valid leaf returns []; a missing or inaccessible parent throws R5dctlApiError with status 404. These GET requests and conversation reads never start or resume an agent. The child REST route is GET /api/r5dctl/sessions/:sessionId/children. lastConversationMessage (GET /api/r5dctl/sessions/:sessionId/conversation/last) returns the agent’s latest message with text as message (null before it has written one), with the session’s status. message.final is true when the conversation ended with that message: it calls no tools and nothing follows it. conversation (GET /api/r5dctl/sessions/:sessionId/conversation) returns the transcript that r5dctl conversation prints as agentText: the active branch as the agent’s model sees it, its latest model request and then what came after it. It is human-readable unless you pass { format: "raw" }; includeTools and includeSystem add the request’s tool definitions and system prompt. thread holds the active branch’s nodes and conversation every branch with its complete items. client.sessions.detach(sessionId) (POST /api/sessions/:sessionId/detach) detaches a subagent from the session that started it, as r5dctl session detach does (Start and continue a conversation): it becomes a top-level session. The answer names the former parent (detachedFrom: its ID, name and when), changed (false when it was detached already), parentNotified (the former parent was working and was told once) and sharedWith (teams that read the session only through a session above it, which now read it through a share of its own). A session that was never a subagent throws R5dctlApiError with status 409 and code not_a_subagent. sessions.status(...) of a detached session carries detachedFrom: { sessionId, at }.

Scheduled sessions

R5dctlScheduleTiming also accepts { kind: "delay", delay: "10m" } and { kind: "once", at: "2030-06-01T09:00:00Z" }. Creation optionally accepts parentSessionId. For UTC cron, supply timezone: "UTC" explicitly (the CLI defaults it for you). The server validates timing and returns HTTP 201 with R5dctlSchedule; list returns { schedules } and removal returns { id, status: "removed" }. REST routes are POST /api/r5dctl/projects/:projectRef/schedules, GET /api/r5dctl/schedules (optional project and worker queries), and DELETE /api/r5dctl/schedules/:scheduleId. A list spans your projects and workers unless filtered, also with the credential of an agent’s shell. Schedules are durable without the creating process. See scheduled sessions for cron/DST rules, offline retry limits, missed-occurrence coalescing and non-overlap. Removal prevents unclaimed occurrences, but an already-claimed dispatch may complete; it never stops a launched session.

Conversations

models.list(...) returns the models your enabled providers offer (models and efforts), as r5dctl get models lists them: each one’s model ID, provider, the efforts it accepts, its defaultEffort, its description, and default for the model sessions of that project and branch run on without one. model takes one of those IDs and effort one of its efforts; provider is needed only when two of your providers offer the same model ID. The package exports the efforts as MODEL_EFFORTS (none, minimal, low, medium, high, xhigh, max), with the ModelEffort type, isModelEffort, modelEffortSchema (zod) and MODEL_EFFORT_LABELS, also from @ricsam/r5d-api/model-efforts. Keep the same requestId and body when retrying an uncertain prompt response. Read messageDelivery to distinguish queued or blocked input from active execution. The returned run status and the acceptance of a new message are separate facts. model and effort are optional on prompts and on answerQuestions/answerEnvRequest. Without them, the session keeps its current model and effort (its branch’s default model for a session that has none yet); an effort alone keeps the model at that effort. Supply them only to change the session’s model, as the first prompt above does; omit them for reports from one agent to another. sessions.describe(...) returns the model, effort and provider a session runs on.
Abort the iterator to detach. Use client.sessions.stop(session.id) to stop the conversation. After the user authorizes resuming it, call client.sessions.resume(session.id, { requestId: crypto.randomUUID(), confirm: true }). Reuse the same request ID after a lost response. This preserves existing queued work; result.resume.status distinguishes queued acceptance from a resume applied by the runner.

Account settings

Environment reads return metadata only. To replace a stored entry, pass its id; omitting value preserves its value. environment.revoke(id) clears the value, and environment.delete(id) removes the entry.

Team integrations

An issue tracker or another tool can follow the work shared with a team: read what is shared, and learn when sessions are shared, change status or work items, or open a pull request. It uses a team API key, which reads exactly what a member of the team reads and nothing else. A team key can’t act: every request that would change something answers 403, and so does every route outside the team. A team admin creates keys on the team’s Integrations page (https://r5d.dev/t/<team>/integrations). The key, r5d_team_…, is shown once; the page shows when each key was last used, and revoking one stops it at once. Members can also call these methods with their own API key, and their agents with the credential of their shell (R5D_TOKEN).

Read what is shared

team is the team’s URL name (acme in /t/acme). Both lists take the same filters:
  • remote: the repository, as a remote URL (https://github.com/acme/api.git, git@github.com:acme/api.git) or its identity (github.com/acme/api). Spellings of the same remote match. A project without a remote is ~<owner's handle>/<project>.
  • branch: the branch name.
  • workItem: the URL of a tracker item a session works on, for example https://github.com/acme/api/issues/42, exactly as the session has it. A launch link sets a session’s work items, and an agent can add them with r5dctl session work-items add.
  • status: one status or several (comma-separated in the REST route).
A branch matches when one of its sessions matches workItem and status; it then lists all of its sessions. Each session has its status, workItems, repository, branchName, owner, parentSessionId (for a subagent) and links: links.session is the read-only page team members open, and links.branch the branch’s permanent team page. Sessions and branches also have teamArchive: { archivedAt, archivedBy } while the branch is archived for the team, else null. A work item is how r5d shows it, not which tracker it comes from: its url (the item’s identity: find your items by it), label (acme/api#42), shortLabel for compact rows (#42; the label when absent), title and icon (issue, pull-request or link, the default). Its status is one of: statusVersion is the version of the last session.status the team got for the session (see below), or null before the first.

Events

Events tell you what changed. Each has an id, a type, a sequence (its position in the team’s feed), createdAt, the team and data: Removing a branch from the team revokes its shares, which share.revoked reports like any revoked share. New event types can be added: ignore types you don’t know. Events cover only what is shared with the team. Revoking a share stops every read of its sessions at once, but events reported while they were shared stay in the feed until they expire. r5d checks shared sessions every couple of seconds, so a status that lasted less than that can be skipped. It looks for a branch’s pull request when a session on the branch stops running, and every few minutes while the branch is active; it finds pull requests on GitHub for members’ GitHub projects. Delivery is at least once: the same event can arrive twice, so deduplicate by id. A session.status event’s version grows with every change of that session’s status in the team: ignore one whose version is lower than the last one you applied. A session.updated event carries the session as it is now; ignore it when you already applied a status newer than its session.statusVersion.

Follow the event feed

The feed works from anywhere, including a tracker r5d can’t reach, such as one behind a firewall. Ask for the events after a cursor; when there are none, the request waits up to wait seconds (at most 30) for one:
Store cursor once you have handled the events and pass it as the next after. With hasMore, ask again at once. Without after, the feed starts at the oldest event r5d keeps. Events are kept for 30 days: truncated: true means some after your cursor are gone, so list the sessions again. To start without the history, list first and follow from the list’s cursor:
follow long-polls until you abort it. After an error, start it again from the last cursor you saved. When the events after that cursor are gone, it throws R5dctlTeamEventsTruncatedError: list the sessions again and follow from the new list’s cursor.

Webhooks

A team admin adds webhooks on the team’s Integrations page: a public HTTPS URL, and a secret that r5d generates and shows once unless you give one. r5d POSTs every event of the team to the URL as JSON, the same object as in the feed, with these headers: Answer with a 2xx status within 10 seconds. Anything else, including a redirect, is a failed attempt: r5d tries again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours and 6 hours, then gives up. Retries can deliver events out of order, so order them by sequence, and session.status events by version. The Integrations page shows each webhook’s delivery log with every attempt’s response, delivers an event again on request, and sends a test ping, which isn’t part of the feed. Verify the signature on the raw body before you parse it:

Errors

Non-success HTTP responses throw R5dctlApiError, which includes status, path, and body. Avoid logging credentials or sensitive request bodies. The package README lists the complete typed method surface, including branch operations, claims, process output, and conversation inspection.