Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🔌Nexus API

Audience: Developers building an external dApp, dashboard, bot, or data pipeline that reads a hosted Nexus deployment.

Goal: Configure a provisional hosted URL and provider-issued API key, consume REST and SSE safely, and understand the public response and recovery contract.

The Nexus API is a hosted, read-only HTTP boundary over indexed Nexus state.

Nexus events to hosted API projections

The architecture figure separates the hosted service from your application: the provider owns indexing and projections, while your code owns presentation, cursor persistence, retry policy, and secret custody. The API is a read surface; state changes still use a wallet-approved CLI or SDK transaction flow.

Use an out-of-band key for the hosted REST API
Phase 1: Deliver an API key and call hosted REST. Keyed facts: the Provider issues x-api-key out of band; the external app / backend receives it; the GET request sends the header to Hosted Nexus API for authentication.
Hosted API reads a projection and preserves errors
Phase 2: Read a REST projection with an explicit error response. Keyed facts: external dApp / backend sends GET with x-api-key to the Hosted Nexus API; the projection returns JSON or an explicit error, and the API preserves status, body, request ID, and rate headers to the caller.
SSE signals trigger a fresh REST readback
Phase 3: Use SSE signals and fresh REST readback. Keyed facts: the external dApp / backend opens SSE with a cursor; the Event log replays missed events and keeps a live tail; the client performs a fresh REST readback after the event.

The sequence keeps credentials server-side and treats SSE as an invalidation and replay signal rather than a substitute for authoritative REST reads. A disconnect, replay gap, rate limit, stale projection, or envelope-free timeout becomes an explicit degraded state followed by the documented retry or re-read action.

Start here

Tutorial — configure a provider-issued key, read resources, stream events, assemble a raw-HTTP dApp, and port it to React

Connect a dApp — keep the key in a backend relay and expose only same-origin public data to a browser

Raw REST and SSE consumer — the typed-client page now uses page-local public types and standard fetch/EventSource-compatible behavior

API reference — scopes, resources, envelopes, status values, events, rate limits, and errors

Troubleshooting — diagnose credentials, projection lag, cursors, rate limits, and service responses

Configure the hosted consumer boundary

Obtain NEXUS_API_KEY from the provider through the agreed secure out-of-band channel. The public consumer contract does not assume a self-service key dashboard, a public credential-minting service, or a live service at the placeholder URL. Store the key in a secret manager or a mode-0600 temporary file, send it only from your server-side relay, and remove it after a short-lived test.

What it serves

Resource family
Indexed state
Concept

/agents, skills, revisions

Agent registry records and skill contracts

/dags

Published DAG objects

/tools

Tool registry records

/tasks, occurrences, reserves

Scheduled Task state

/executions, walks, events, verdicts, failures, payment ledger

DAGExecution traces and payment projections

/payments, /priority-fee-vault/events

Execution payments and fee-vault activity

/leaders

Public leader registry records

/events/stream

The deployment's decoded event log

The public projection may omit Task rejection or Invocation fields. If a deployment does not publish a field or event, use the provider’s documented schema and do not infer the missing state from an empty response.

Read, react, and recover

REST responses are the source for the view; the SSE stream is a timely, replayable signal that tells the application when to re-read. List pages use an opaque next_token, statuses are open sets, and a missing row can mean projection lag rather than absence. The tutorial and document show the exact envelopes and cursor rules.

Last updated