> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hellonear.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> How the public HTTP API works, every route, and where the OpenAPI spec lives.

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`](https://github.com/Hellonear-AI/hellonear/blob/main/docs/openapi.json)** (OpenAPI 3.1, 63 operations): open it in [Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Hellonear-AI/hellonear/main/docs/openapi.json) 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`](https://github.com/Hellonear-AI/hellonear/blob/main/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 |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.