API overview

The web app is a client of a public HTTP API, and everything it does can be done with curl. The full spec is docs/openapi.json (OpenAPI 3.1, 63 operations): open it in Swagger Editor or any OpenAPI viewer to read every route and try it against the hosted API. Every server-sent event type is described in docs/api-contract.md §3.

Base URL: https://api.hellonear.xyz (NEAR testnet), or http://localhost:4000.
Auth: a session cookie, hn_session. Get one with POST /v1/auth/demo (guest, no wallet) or with a NEAR wallet: POST /v1/auth/challenge, sign the message (NEP-413), then POST /v1/auth/login. curl works as is (no Origin header); a browser page on another site gets 403 for any call that changes something (CSRF protection).
Streams: chat, approve/decline, workflow runs and attack runs answer text/event-stream: run.started, text.delta, tool.called, tool.result, tool.approval_required, run.finished, run.verified and more.
Guests get 403 demo_not_allowed for owner actions (wallet policy, freeze, memory edits, rules, schedules); everything else works.
Checked live: the last column marks the endpoints called against the hosted API with a guest session on 12 Nov 2026 and answered as documented (owner-only and money-moving endpoints are covered by the backend’s integration tests instead).

System

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/health`	Health of the backend and the engine	200	yes

Auth

Method	Path	What it does	Answer	Checked live
`POST`	`/v1/auth/challenge`	Get a NEP-413 sign-in message and a one-time nonce	200
`POST`	`/v1/auth/login`	Sign in with a NEAR wallet signature (NEP-413)	200
`POST`	`/v1/auth/demo`	Start a try-out (guest) session: no wallet, 20 messages	201	yes
`POST`	`/v1/auth/logout`	Sign out	204
`GET`	`/v1/me`	The signed-in user	200	yes

Catalog

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/templates`	Mind templates	200	yes
`GET`	`/v1/skills`	Every skill a Mind can equip, with its tools	200	yes
`GET`	`/v1/skills/{skillId}`	One skill with its playbook (SKILL.md body)	200	yes

Minds

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds`	The user’s Minds, newest first	200	yes
`POST`	`/v1/minds`	Create a Mind from a template	201	yes
`GET`	`/v1/minds/{mindId}`	One Mind	200	yes
`PATCH`	`/v1/minds/{mindId}`	Change a Mind: name, voice, model, skills, memory switches, auto-approve rules	200
`DELETE`	`/v1/minds/{mindId}`	Delete a Mind (and its workflows, schedules and wallet key)	200

Chat

Method	Path	What it does	Answer	Checked live
`POST`	`/v1/minds/{mindId}/chat`	Send a message; the reply streams as server-sent events	SSE	yes
`GET`	`/v1/minds/{mindId}/threads`	Chat threads, newest first	200	yes
`GET`	`/v1/minds/{mindId}/threads/{threadId}/messages`	A thread’s messages, oldest first, paged by `before`	200
`PATCH`	`/v1/minds/{mindId}/threads/{threadId}`	Rename a thread	200
`DELETE`	`/v1/minds/{mindId}/threads/{threadId}`	Delete a thread for good (the engine forgets it too)	200

Runs

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/runs`	Runs of a Mind, with tokens and cost	200	yes
`GET`	`/v1/runs/{runId}`	One run with all its stored events	200	yes
`POST`	`/v1/runs/{runId}/cancel`	Stop a run that is still streaming	200
`GET`	`/v1/minds/{mindId}/events`	Events across runs since a time (Mind Graph history)	200	yes

Approvals

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/approvals`	Runs waiting for the owner’s approval	200	yes
`POST`	`/v1/runs/{runId}/approve`	Approve a waiting tool call; the run resumes as SSE	SSE
`POST`	`/v1/runs/{runId}/decline`	Decline a waiting tool call; the run resumes as SSE	SSE	yes

Verification

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/runs/{runId}/proof`	The proof behind a reply’s Verified badge	200	yes
`POST`	`/v1/runs/{runId}/proof/tee-explorer`	Upload the run’s Intel quote to Phala’s TEE Explorer and get the verified report	200	yes

Wallet

Method	Path	What it does	Answer	Checked live
`POST`	`/v1/minds/{mindId}/wallet`	Create the Mind’s OutLayer wallet (testnet)	201
`GET`	`/v1/minds/{mindId}/wallet`	Balance, spent today, frozen, and the policy	200	yes
`GET`	`/v1/minds/{mindId}/wallet/payments`	Payment receipts, refused ones included	200	yes
`GET`	`/v1/minds/{mindId}/payments.csv`	Every payment as a CSV an accountant can open (date UTC, status in words, amount, counterparty, purpose, who approved, tx hash, NearBlocks link)	200 `text/csv`	yes
`GET`	`/v1/status`	Public status of HelloNear and its providers (NEAR AI chat and embeddings, 1Click quotes, OutLayer, NEAR RPC, Agent Market, TEE Explorer): status, latency, uptime, 48 half-hour buckets and incidents of the last 7 days. CORS `*`, cached 30 s	200
`POST`	`/v1/relay`	Relay a NEP-366 signed delegate action to the registry (only `unequip_skill` / `set_wallet`, exactly 1 yoctoNEAR); the relayer pays the gas, never a deposit. Not for try-out users	200, `503 relay_not_configured` until the relayer is set
`POST`	`/v1/minds/{mindId}/wallet/policy`	Build a store_wallet_policy transaction for the owner to sign	200
`POST`	`/v1/minds/{mindId}/wallet/freeze`	Build a freeze_wallet transaction for the owner to sign	200
`POST`	`/v1/minds/{mindId}/wallet/unfreeze`	Build an unfreeze_wallet transaction for the owner to sign	200

Memory

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/memory`	What the Mind remembers about the owner	200	yes
`PUT`	`/v1/minds/{mindId}/memory`	Replace the Mind’s memory	200
`DELETE`	`/v1/minds/{mindId}/memory`	Clear the Mind’s memory	204

Email

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/inbox`	The Mind’s own email address, if any	200	yes
`POST`	`/v1/minds/{mindId}/inbox`	Create the Mind’s own email address (AgentMail)	201
`GET`	`/v1/minds/{mindId}/mail/sent`	Emails the Mind sent, refusals included	200	yes

Autopilot

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/workflows`	Saved Builder workflows	200	yes
`PUT`	`/v1/minds/{mindId}/workflows/{workflowId}`	Save a Builder canvas (compiled to a Mastra workflow)	200	yes
`GET`	`/v1/minds/{mindId}/workflows/{workflowId}`	One workflow with its canvas	200
`DELETE`	`/v1/minds/{mindId}/workflows/{workflowId}`	Delete a workflow and its schedule	204	yes
`POST`	`/v1/minds/{mindId}/workflows/{workflowId}/runs`	Run a workflow now; steps stream as SSE	SSE	yes
`GET`	`/v1/minds/{mindId}/workflows/{workflowId}/runs`	Past runs of a workflow, newest first, with each step	200	yes
`PUT`	`/v1/minds/{mindId}/workflows/{workflowId}/autopilot`	Turn the schedule on (wallet sign-in only)	200	yes
`GET`	`/v1/minds/{mindId}/workflows/{workflowId}/autopilot`	The schedule’s state	200
`DELETE`	`/v1/minds/{mindId}/workflows/{workflowId}/autopilot`	Turn the schedule off	204

Connections

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/connections`	Apps the user connected through Composio	200	yes
`POST`	`/v1/connections/{toolkit}`	Get a Composio Connect Link for an app	200
`DELETE`	`/v1/connections/{toolkit}`	Disconnect an app	204

Telegram

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/minds/{mindId}/telegram`	The Mind’s Telegram bot, if connected	200	yes
`PUT`	`/v1/minds/{mindId}/telegram`	Connect a BotFather token to the Mind	200
`DELETE`	`/v1/minds/{mindId}/telegram`	Disconnect the bot	204

Secrets

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/secrets`	Saved API keys (names and hosts, never values)	200	yes
`PUT`	`/v1/secrets/{name}`	Save an API key for the Mind’s HTTP request skill	200
`DELETE`	`/v1/secrets/{name}`	Delete a saved key	204

Attack playground

Method	Path	What it does	Answer	Checked live
`GET`	`/v1/attacks`	The prompt-injection scenarios	200	yes
`POST`	`/v1/attacks/{attackId}/runs`	Run a scenario on a hidden test Mind; ends with attack.verdict	SSE	yes

Get started

Concepts

Track features

API

Smart contracts

More