Nexus API Reference

All API endpoints return JSON. Use Authorization: Bearer <token> for authentication.

Admin = requires the NEXUS_ADMIN_TOKEN
Agent = requires an agent auth token (or admin token)
Public = no auth required

Admin token: 1396cd02de5b3e6d60c8fb1e3ed846676f6dff15f49b0437ddc697c5ef8b60ef

🤖 Agents

GET/api/agentsAdmin

List all registered agents

POST/api/agents/registerPublic

GET/api/agents/:slug/profilePublic

Get an agent's profile (how it's configured in Nexus)

POST/api/agents/:slug/heartbeatAgent

Send a heartbeat ping. The agent token used in the Authorization header must match the agent's slug.

PUT/api/agents/:slug/tokenAdmin

Create or rotate an agent's auth token. Returns the new token (this is the only time it's shown).

DELETE/api/agents/:slug/token/:tokenHashAdmin

Revoke an agent token by its SHA-256 hash

📋 Profiles

GET/api/profiles

List all inference profiles

GET/api/profiles/:name

Get a single profile by name (e.g. Prod-Reliable, Dev Fast & Cheap)

POST/api/profilesAdmin

Create a new profile
Body:

{ "name": "my-profile", "model": "openai/gpt-4o", "fallbacks": [], "vision": false, "gateway": null, "description": "", "parameters": {} }

PUT/api/profiles/:nameAdmin

Update a profile (partial — only include fields to change)

DELETE/api/profiles/:nameAdmin

Delete a profile

🔐 Vault / Secrets

GET/api/vault/secrets?scope=:scopeAgent

List secrets accessible to the authenticated agent. Pass ?scope= to filter.

POST/api/vault/secretsAdmin

Create a new secret
Body: { "scope": "infrastructure", "name": "my-key", "value": "supersecret", "allowed_profiles": [] }
Empty allowed_profiles = accessible by all agents

GET/api/vault/secrets/:idAgent

Get a single secret by ID. Decrypts and returns the plaintext value.

Response: { "id", "scope", "name", "value" (decrypted), "allowed_profiles" }

DELETE/api/vault/secrets/:idAdmin

Delete a secret

📚 Knowledge

GET/api/knowledge?kind=server,project&query=ollama&format=yaml

Query the knowledge base. Parameters are all optional:

kind — filter by type: server, domain, infrastructure, project, agent (comma-separated)
query — text search across titles and content
format — yaml for raw YAML, default is JSON

GET/api/knowledge/:kind

Shorthand — filter to a single kind. Example: /api/knowledge/server

📦 Model Registry

GET/api/registry/modelsAgent

List all registered models

GET/api/registry/models/:slugAgent

Get a model by slug

POST/api/registry/modelsAgent

DELETE/api/registry/models/:slug/:modelIdAgent

Delete a model entry

🔗 Assignments

GET/api/assignmentsAdmin

List all assignments

PUT/api/assignments/:slugAdmin

Create or update an assignment
Body: { "profile_name": "Prod-Reliable" }

DELETE/api/assignments/:slugAdmin

Remove an assignment

🧠 Memories

GET/api/memories/list?agent=:slug&date=YYYY-MM-DD

List memory files for an agent, optionally filtered by date

POST/api/memories/collect

Store a memory entry
Body: { "agent": "addy", "content": "Remember this...", "date": "2026-07-01" }

GET/api/memories/download/:agent/:date?format=markdown

Download a full day's memory file for an agent

🛡️ Admin

GET/admin/statusAdmin

System status overview

GET/admin/audit-logAdmin

Audit log (access tracking from vault and other services)

🔑 Auth (UI specific)

GET/api/auth/me

Get current user session info. Returns { userId, name, email, image } or { error: "unauthorized" }.

GET/api/auth/login

Redirect to Inflo SSO login

GET/api/auth/logout

Logout (clears session, redirects to Inflo)

GET/api/auth/nexus-gate

Nexus login gate page

📡 UI Endpoints (agent-accessible via Bearer token)

These are HTML endpoints but return JSON data when accessed with an Accept: application/json header or Bearer token:

GET/api/secrets?profile=:nameAgent

List all secrets (unrestricted + matching profile filter). Uses the admin token.
Example: curl -H 'Authorization: Bearer $ADMIN_TOKEN' nexus.studio.dripper.live/api/secrets?profile=Prod-Reliable

GET/api/memories/listAgent

List memory files. Accepts ?agent= and ?date= filters.