# `~/.ornn/installed-skills.json` — registry contract

Companion to `SKILL.md` §0.5. This file specifies the schema, when to read, when to write, and the per-execution version-check protocol for the persistent installed-skills registry.

> **One file, one machine, every Ornn-aware agent.** `~/.ornn/installed-skills.json` is the **shared** source of truth across sessions and runtimes: a Claude Code session installs `csv-tools`, then a later Codex session on the same box reads the registry and knows it already has `csv-tools` at v1.3 — no re-install, no duplicate fetch. Treat the file as a contract; don't shape it to your runtime's quirks.

---

## 1. Where the file lives

| Platform | Path |
|---|---|
| macOS / Linux | `~/.ornn/installed-skills.json` |
| Windows | `%USERPROFILE%\.ornn\installed-skills.json` |
| Sandboxed runtime that can't write under `$HOME` | hold the same list in working memory and tell the user "the registry won't survive a session restart" |

If `~/.ornn/` does not exist, create it with mode `0700` (Unix). If `installed-skills.json` does not exist, create it as a literal `[]` the first time you append a record. Never write a different default — `null` and `{}` are not valid initial states.

---

## 2. Schema

A flat JSON array. Each element is an `InstalledSkillRecord`:

```jsonc
[
  {
    "name":             "chrono-ai-service-manual",            // required — Ornn skill name (kebab-case)
    "ornnGuid":         "1d9bfda2-dea8-4032-85bd-b0cbe1621684",// required — stable UUID-style id
    "installedVersion": "1.0",                                  // required — frontmatter version of the local copy
    "installedAt":      "2026-05-04T17:27:55Z",                 // optional — ISO 8601 UTC; set on first install + every upgrade
    "localPath":        "~/.claude/skills/chrono-ai-service-manual/",  // optional — directory you wrote files to (or omit if context-only)
    "isPinned":         false                                   // optional — when true, skip auto-update prompts; user explicitly locked the version
  }
]
```

### Field semantics

| Field | Required | Notes |
|---|---|---|
| `name` | yes | Matches `metadata.name` in the skill's `SKILL.md` frontmatter. Kebab-case. Used for fast human lookup; the GUID is the canonical id. |
| `ornnGuid` | yes | The `data.guid` returned by `POST /skills` (creation), `GET /skills/:idOrName`, etc. Always use this as the lookup key when the registry has it. |
| `installedVersion` | yes | The frontmatter `version:` of the local copy, as a `<major>.<minor>` string. Compare against `items[0].version` from `/versions` to detect updates. |
| `installedAt` | no | ISO 8601 UTC timestamp. Set when you append the record; bump every time you upgrade the local copy. Useful when the user asks "when did I install this?". |
| `localPath` | no | Filesystem directory the skill files were written to. Omit for runtimes that load skills only into context (memory). When set, must end with a trailing slash. |
| `isPinned` | no | Default `false`. When `true`, the per-execution version check (§5) skips the upgrade prompt — the user has explicitly locked the version. Setting requires explicit user request; never auto-set. |

### What NOT to add

- **Do not store secrets** in the registry. No tokens, no API keys, no credentials. Anyone reading the file sees what's installed; they should not see anything sensitive.
- **Do not store skill content** (the SKILL.md, scripts/, etc.) — only metadata. The actual files live at `localPath` or in your runtime's context.
- **Do not store remote audit verdicts** — they're queryable from `/audit` endpoints and go stale fast.

### Forward compatibility

You may encounter records with fields not listed above (e.g. a future runtime added a `runtimeHint` field). **Preserve them on round-trip** — read, modify the fields you care about, write back without dropping unknowns.

---

## 3. When to read

The **first thing every Ornn-aware session does, before any other Ornn operation**, is read this file.

```pseudocode
on session start:
  if file exists:
    parse JSON; on parse error, surface to user, do not overwrite
  else:
    treat as empty []
  cache in memory for the session
```

**Re-read if** the file may have been mutated by another process (parallel sessions, a different agent, the user editing manually). A safe default: re-read at the start of any Ornn task. Cheap I/O.

---

## 4. When to write

Writes happen at four well-defined moments. Each one is a full file rewrite — read the file, mutate the array, write the whole thing back. Atomic-write best-practice (write to `installed-skills.json.tmp`, then rename) avoids torn writes.

| Event | What changes | Notes |
|---|---|---|
| Installed a new skill | Append a new record | Triggered by §2.1 step 3 (pull) or §2.1 step 5 (build + install). |
| Upgraded to a new version | On the matching record (by `ornnGuid`), bump `installedVersion` + `installedAt` | Triggered by §2.6 (pull a different version), §2.3 after publishing yourself, or the auto-update branch of §5. |
| Uninstalled / deleted a skill | Remove the matching record entirely | Triggered by §2.10 if the deleted version was the locally installed one and there's no fallback, or §2.11 (entire skill deleted). |
| User pinned a version | Set `isPinned: true` on the record | Triggered when the user explicitly says "stay on v1.2 — don't auto-prompt me". Never set this without explicit user intent. |

After each write, verify by re-reading. If the read returns malformed JSON, surface the error to the user and do not retry-loop — something else is interfering with the file.

### What about uninstall when the skill is still present remotely?

If the user "uninstalls" a skill (i.e. removes it from their local environment) but the skill remains on the Ornn registry, just remove the record. Don't call any Ornn delete endpoint — local uninstall is purely client-side.

---

## 5. Per-execution version check (the protocol)

**Before you actually execute an installed Ornn skill** on the user's task, check whether a newer version exists. One API call:

```bash
nyxid proxy request ornn-api \
  "/api/v1/skills/<name-or-guid>/versions" \
  --method GET --output json
```

For public skills you can drop the auth and call the same endpoint anonymously (HTTP form: `curl https://ornn.chrono-ai.fun/api/v1/skills/<name>/versions`).

Response: `{ items: [{ version, skillHash, createdOn, isDeprecated, deprecationNote, releaseNotes, ... }, ...] }` sorted newest-first. Compare `items[0].version` to the `installedVersion` on the matching registry record:

| Outcome | Action |
|---|---|
| Same version | Execute as-is. |
| Newer version available | Tell the user `"Skill <name> has a newer version <X.Y> (you have <A.B>). Release notes: <releaseNotes>. Update? (y/n)"`. If yes, re-fetch the package (§2.1 step 3 in `SKILL.md`), overwrite the local copy, bump `installedVersion` + `installedAt`, then execute. If no, execute the installed version. |
| Your installed version has `isDeprecated: true` (look up the matching item in `items`) | Warn the user with `deprecationNote`, recommend updating before executing. |
| Skill 404s | The skill was deleted or hidden from you. Tell the user; if they agree, remove the record from the registry. Otherwise leave the record (with a note) — local copy is still usable. |

**Skip the version check when the matching record carries `isPinned: true`.** Pinning means "don't ask me again about updates."

### When to defer the version check

- The user said "just run it, don't check for updates."
- The skill execution is on a hot path and adding an HTTP round-trip would break the user-perceived latency budget.
- The Ornn API is unreachable. Fall back to the locally-installed version, surface the failure to the user, do not retry-loop.

---

## 6. Audit-risk fan-out

If the skill is tied to a NyxID admin service (a "system skill" — `isSystemSkill: true`), the audit pipeline can also notify you mid-session via `GET /api/v1/notifications` (see `SKILL.md` §2.13). Treat any `audit.risky_for_consumer` notification as a hard signal to **stop using the skill**, surface it to the user, and ask before continuing — even if your installed version was previously fine. The audit verdict applies to the version you have installed, and the registry record's `installedVersion` is the field that links the notification to your local copy.

You don't need to write anything to the registry on these notifications — they're a side-channel. But if the user agrees to upgrade in response, run the standard upgrade path (§5).

---

## 7. Multi-agent / multi-runtime coexistence

Two agents on the same machine (e.g. Claude Code and Codex) sharing the same `~/.ornn/installed-skills.json` will read each other's installs. That's the design — the registry is the substrate.

But two agents writing simultaneously can race. Mitigations:

- **Atomic write** (write-to-temp-then-rename) is enough for most cases.
- If you observe a corrupted file (parse fails), surface to the user and ask before overwriting. They may want to keep the half-written state for forensics.
- Do not attempt cross-process locking — runtimes vary too much.

---

## 8. Examples

### Empty registry, just installed `chrono-ai-service-manual`

```jsonc
[
  {
    "name": "chrono-ai-service-manual",
    "ornnGuid": "<guid-from-POST-/skills>",
    "installedVersion": "1.0",
    "installedAt": "2026-05-04T17:27:55Z",
    "localPath": "~/.claude/skills/chrono-ai-service-manual/"
  }
]
```

### Two skills, one pinned

```jsonc
[
  {
    "name": "chrono-ai-service-manual",
    "ornnGuid": "1d9bfda2-dea8-4032-85bd-b0cbe1621684",
    "installedVersion": "1.0",
    "installedAt": "2026-05-04T17:27:55Z",
    "localPath": "~/.claude/skills/chrono-ai-service-manual/"
  },
  {
    "name": "csv-tools",
    "ornnGuid": "skl_01HXY...",
    "installedVersion": "1.2",
    "installedAt": "2026-04-30T09:14:21Z",
    "localPath": "~/.claude/skills/csv-tools/",
    "isPinned": true
  }
]
```

### Context-only install (no `localPath`)

```jsonc
[
  {
    "name": "chrono-ai-service-manual",
    "ornnGuid": "1d9bfda2-dea8-4032-85bd-b0cbe1621684",
    "installedVersion": "1.0"
  }
]
```

`installedAt`, `localPath`, and `isPinned` are all optional — when omitted, treat them as "unknown" / "memory-only" / "false" respectively.

# NyxID API Reference

Companion to `SKILL.md` §1. This file enumerates the NyxID HTTP surface (`/api/v1/*` plus the OIDC routes at `/oauth/*` and `/.well-known/*`) at the level of detail the agent actually needs to make calls without guessing. Each section names the path, request shape, response shape, and notable error codes. Per-deployment auth specifics live in `nyxid-token-model.md`.

> **Authoritative source.** This catalogue is derived from the NyxID `docs/AI_AGENT_PLAYBOOK.md` and `docs/API.md`. If the actual API behaviour disagrees, the API is right and this doc is stale — pull a fresh copy of the unified manual (`SKILL.md` §0) before assuming a bug.

---

## 1. Conventions

### 1.1 Base URL and versioning

| Environment | API base | Frontend |
|---|---|---|
| Production | `https://nyx-api.chrono-ai.fun` | `https://nyx.chrono-ai.fun` |
| Local self-host | `http://localhost:3001` | `http://localhost:3000` |

Versioned endpoints under `/api/v1/`. OIDC routes at the root (`/oauth/authorize`, `/oauth/token`, `/.well-known/openid-configuration`, `/.well-known/jwks.json`).

### 1.2 Authentication

| Method | Header | When |
|---|---|---|
| Bearer token (OIDC access token) | `Authorization: Bearer <access-token>` | After `nyxid login` or OAuth flow |
| NyxID API key | `Authorization: Bearer nyxid_...` OR `X-API-Key: nyxid_...` | Headless agents, CI |
| Service account | `Authorization: Bearer <SA-access-token>` | Server-to-server (client_credentials grant) |

Anonymous calls work for OIDC discovery, OpenAPI schema, and a small public slice. See `nyxid-token-model.md` §7 for the exact list.

### 1.3 Common response envelope

Most JSON endpoints follow:

```jsonc
// success
{ "data": <T>, "error": null }

// failure
{ "data": null, "error": { "code": "STRING_CODE", "message": "Human-readable explanation" } }
```

Some legacy routes (notably `/auth/*` and `/oauth/*`) return raw payloads without the envelope — read response shape per-endpoint.

### 1.4 HTTP status mapping

| Status | Meaning |
|---|---|
| 200 | Successful read or write |
| 201 | Resource created |
| 400 | Validation, malformed body, bad query |
| 401 | Authentication missing or invalid |
| 403 | Authenticated but unauthorized (missing role, scope, or per-resource permission) |
| 404 | Resource missing or hidden |
| 409 | Conflict (duplicate, state-machine violation) |
| 410 | Gone (deprecated route, post-removal) |
| 413 | Payload too large |
| 429 | Rate limited |
| 500 | Internal error — capture `X-Request-ID`, retry with backoff |

---

## 2. Authentication & sessions

### 2.1 Register — `POST /api/v1/auth/register`

**Auth: none.** Creates a new user account. Requires an invite code unless `INVITE_CODE_REQUIRED=false` in deployment.

```jsonc
{ "email": "...", "password": "...", "displayName": "...", "invite_code": "NYX-XXXXXXXX" }
```

### 2.2 Login — `POST /api/v1/auth/login`

**Auth: none.** Email + password.

```jsonc
{ "email": "...", "password": "..." }
```

Response: `{ access_token, refresh_token, expires_in, token_type, user: { ... } }`. Access tokens default to 15 min TTL.

### 2.3 Logout — `POST /api/v1/auth/logout`

**Auth: required.** Invalidates the current session.

### 2.4 Refresh — `POST /api/v1/auth/refresh`

**Auth: none** (the refresh token is the credential).

```jsonc
{ "refresh_token": "..." }
```

Same response shape as `/login`.

### 2.5 Forgot / reset password — `POST /api/v1/auth/forgot-password`, `POST /api/v1/auth/reset-password`

**Auth: none.** First sends an email with a reset code; second consumes the code.

---

## 3. Users

### 3.1 Current user — `GET /api/v1/users/me`

**Auth: required.** Returns `{ userId, email, displayName, roles, permissions, ... }`. Use this to debug 403s — it tells you exactly what the proxy thinks the caller is authorized for.

### 3.2 Update profile — `PUT /api/v1/users/me`

**Auth: required.** Accepts `displayName`, `avatarUrl`, etc. The set of editable fields is enforced server-side.

### 3.3 Sessions — `GET /api/v1/sessions`

**Auth: required.** Active sessions for the caller. Useful for revoking rogue sessions through the dashboard.

### 3.4 MFA — `/api/v1/auth/mfa/*`

```text
POST /api/v1/auth/mfa/setup        — start TOTP enrolment (returns secret + QR URL)
POST /api/v1/auth/mfa/confirm      — confirm with first code
POST /api/v1/auth/mfa/verify       — verify MFA code at login
POST /api/v1/auth/mfa/disable      — disable MFA
```

---

## 4. AI Services (the user-facing key management)

The unified `/api/v1/keys` surface auto-provisions UserEndpoint + UserApiKey + UserService records. New integrations should always use `/keys`; the legacy `/connections` and `/providers/{id}/connect/*` routes are deprecated but still functional.

### 4.1 Add a service — `POST /api/v1/keys`

**Auth: required.** Add from catalogue or fully custom.

```jsonc
// Catalogue add
{ "service_slug": "llm-openai", "credential": "$SERVICE_CREDENTIAL", "label": "Production" }

// Catalogue + custom endpoint URL
{ "service_slug": "llm-openclaw", "credential": "$SERVICE_CREDENTIAL",
  "endpoint_url": "http://localhost:18789", "label": "Local OpenClaw" }

// Fully custom (no catalogue entry)
{ "label": "Internal API",
  "endpoint_url": "https://internal.corp.com/api",
  "credential": "$SERVICE_CREDENTIAL",
  "auth_method": "header", "auth_key_name": "X-API-Key" }

// With node routing
{ "service_slug": "llm-openai", "credential": "...", "node_id": "<NODE_UUID>", "label": "..." }
```

`auth_method` ∈ `bearer | header | query | path | basic | none`.

### 4.2 List services — `GET /api/v1/keys`

**Auth: required.** Returns combined view: endpoint URL + credential metadata + service slug, one row per UserService.

### 4.3 Show service — `GET /api/v1/keys/{id}`

**Auth: required.**

### 4.4 Update service — `PUT /api/v1/keys/{id}`

**Auth: required.** Update label, endpoint URL, node routing, etc.

```jsonc
{ "label": "...", "endpoint_url": "...", "node_id": "<NODE_UUID>" }
```

### 4.5 Delete service — `DELETE /api/v1/keys/{id}`

**Auth: required.** Deactivates the UserService + UserApiKey atomically.

### 4.6 OAuth flow — `POST /api/v1/keys/oauth/authorize`

**Auth: required.** Start an OAuth flow for a provider that requires it (e.g. GitHub). Returns `{ authorization_url }`. User opens the URL in a browser, completes consent, NyxID handles the callback at `GET /api/v1/keys/oauth/callback` and stores the resulting tokens.

### 4.7 Force token refresh — `POST /api/v1/keys/{id}/refresh`

**Auth: required.** For OAuth-backed services where the access token has expired and you want to force a refresh-token round-trip.

### 4.8 Update credential — `PUT /api/v1/api-keys/external/{id}`

**Auth: required.**

```jsonc
{ "credential": "$NEW_CREDENTIAL" }
```

Slug is preserved; existing proxy calls keep working.

### 4.9 Update endpoints / user-services / external-keys directly

Underlying records are also addressable individually:

```text
GET    /api/v1/endpoints                 — list user's endpoints
PUT    /api/v1/endpoints/{id}            — update endpoint URL
DELETE /api/v1/endpoints/{id}

GET    /api/v1/api-keys/external         — list user's external credentials
PUT    /api/v1/api-keys/external/{id}    — rotate, relabel
DELETE /api/v1/api-keys/external/{id}

GET    /api/v1/user-services             — list bindings
PUT    /api/v1/user-services/{id}        — update auth config, node routing
DELETE /api/v1/user-services/{id}        — deactivate
```

Prefer `/keys` unless you have a specific reason to address one component.

---

## 5. Catalogue (read-only — discover available services)

### 5.1 List — `GET /api/v1/catalog`

**Auth: required.** Connectable services only.

Query: `include_all=true` — include system / no-auth services.

### 5.2 Show — `GET /api/v1/catalog/{slug}`

**Auth: required.** Full metadata for a single service template — `homepage_url`, `repository_url`, `openapi_spec_url`, `capabilities`, `auth_notes`, `known_limitations`, `required_permissions`.

### 5.3 Endpoints — `GET /api/v1/catalog/{slug}/endpoints`

**Auth: required.** Parsed API endpoints from the service's OpenAPI spec — `{ method, path, name, description, parameters, request_body }`.

---

## 6. Services (admin — catalogue management)

These create the templates that users add via §4. Admin only.

```text
GET    /api/v1/services
POST   /api/v1/services
GET    /api/v1/services/{id}
PUT    /api/v1/services/{id}
DELETE /api/v1/services/{id}
POST   /api/v1/services/{id}/endpoints                   — add API endpoint
POST   /api/v1/services/{id}/discover-endpoints          — auto-discover from OpenAPI
GET    /api/v1/services/{id}/oidc-credentials            — for OIDC services, get client_id + secret
PUT    /api/v1/services/{id}/redirect-uris               — update OIDC redirect URIs
POST   /api/v1/services/{id}/regenerate-secret           — rotate OIDC client secret
```

`POST /services` body schema (selected fields):

```jsonc
{
  "name": "OpenAI API",
  "slug": "openai",
  "base_url": "https://api.openai.com",
  "auth_method": "header",
  "auth_key_name": "Authorization",
  "service_category": "connection",      // "connection" | "internal" | "provider" | "ssh"
  "visibility": "public",                // "public" | "private"
  "openapi_spec_url": "https://api.example.com/openapi.json",
  "credential": "<shared-cred>"          // optional; for internal services where admin provides the key
}
```

For `auth_method: "oidc"`, NyxID auto-creates an OAuth client with generated `client_id` + `client_secret` and sets the default redirect to `{base_url}/callback`.

---

## 7. Proxy

### 7.1 Proxy by slug — `* /api/v1/proxy/s/{slug}/{path}`

**Auth: required.** Any HTTP method. Path is forwarded verbatim to `<service.base_url>/<path>` with the configured credential injected.

### 7.2 Proxy by service ID — `* /api/v1/proxy/{service_id}/{path}`

**Auth: required.** Same semantics; addresses by UUID rather than slug.

### 7.3 Discover — `GET /api/v1/proxy/services`

**Auth: required.** Lists services the caller can route through. Legacy — `GET /api/v1/keys` returns a richer combined view.

### 7.4 Streaming and large bodies

The proxy streams without server-side buffering. HTTP Range requests are supported when the upstream sets `Accept-Ranges`. Request bodies up to 100 MB by default (configurable via `PROXY_MAX_BODY_SIZE`).

### 7.5 Identity propagation (optional)

Per-service flag — when set, the proxy forwards:

```text
X-User-ID                  — NyxID userId
X-User-Email               — caller email
X-User-Name                — caller displayName
X-NyxID-Authenticated      — always "true"
```

Independent of bearer-token forwarding (`forward_access_token`); see `nyxid-token-model.md` §4.2.

---

## 8. Providers

Provider configs back the OAuth / API-key / device-code flows that catalogue services use. Most agents never call these directly — they're admin-managed.

```text
GET    /api/v1/providers
POST   /api/v1/providers                                      — admin
GET    /api/v1/providers/{id}
PUT    /api/v1/providers/{id}                                 — admin
DELETE /api/v1/providers/{id}                                 — admin
GET    /api/v1/providers/{id}/connect/oauth                   — deprecated; use /keys/oauth/authorize
POST   /api/v1/providers/{id}/connect/api-key                 — deprecated; use POST /keys
POST   /api/v1/providers/{id}/connect/device-code/initiate    — start device-code flow
POST   /api/v1/providers/{id}/connect/device-code/poll        — poll device-code status
POST   /api/v1/providers/{id}/refresh                         — refresh provider token
DELETE /api/v1/providers/{id}/disconnect
GET    /api/v1/providers/{id}/credentials                     — get user's own OAuth app creds
PUT    /api/v1/providers/{id}/credentials                     — set user's own OAuth app creds
DELETE /api/v1/providers/{id}/credentials
```

Provider modes (`credential_mode`):

- `admin` — admin provides client credentials, users just authorize.
- `user` — users bring their own client_id / client_secret.
- `both` — admin defaults; users can override.

Device-code flow shape:

```bash
# Initiate
POST /api/v1/providers/{id}/connect/device-code/initiate
# → { user_code, verification_uri, state, expires_in, interval }

# Poll (every interval)
POST /api/v1/providers/{id}/connect/device-code/poll
{ "state": "STATE_FROM_INITIATE" }
# → { status: "pending" | "success" | "expired" | "denied" }
```

---

## 9. Nodes (on-premise credential agents)

### 9.1 Registration tokens — `POST /api/v1/nodes/register-token`

**Auth: required.**

```jsonc
{ "name": "Production Node" }
```

Response: `{ token: "nyx_nreg_...", token_id, expires_at }`. Tokens expire 1 hour after issue.

### 9.2 List / show / delete / rotate

```text
GET    /api/v1/nodes
GET    /api/v1/nodes/{id}
DELETE /api/v1/nodes/{id}
POST   /api/v1/nodes/{id}/rotate-token
```

### 9.3 Bindings (deprecated — use `PUT /user-services/{id}` with `node_id`)

```text
POST   /api/v1/nodes/{id}/bindings
DELETE /api/v1/nodes/{id}/bindings/{binding_id}
```

### 9.4 WebSocket protocol — `GET /api/v1/nodes/ws`

The node agent (running on-prem) connects here over WebSocket and authenticates with its registration token. Live credential rotation, request routing, and metadata exchange happen over this socket. Protocol detail: NyxID's `docs/NODE_PROXY_PROTOCOL.md`.

---

## 10. Developer apps (OAuth clients for "Sign in with NyxID")

```text
GET    /api/v1/developer/oauth-clients
POST   /api/v1/developer/oauth-clients
GET    /api/v1/developer/oauth-clients/{id}
PATCH  /api/v1/developer/oauth-clients/{id}
DELETE /api/v1/developer/oauth-clients/{id}
POST   /api/v1/developer/oauth-clients/{id}/rotate-secret
```

`POST` body:

```jsonc
{
  "name": "My App",
  "redirect_uris": ["https://myapp.example.com/auth/callback"],
  "client_type": "public",                      // "public" | "confidential"
  "allowed_scopes": ["openid", "profile", "email"]
}
```

For `client_type: "confidential"`, the response includes `client_secret` **once**. For `public`, no secret (PKCE expected at the OAuth flow).

`POST .../rotate-secret` returns the new secret (one-time display) and invalidates the old.

---

## 11. OAuth / OIDC routes

```text
GET  /.well-known/openid-configuration                   — OIDC discovery document
GET  /.well-known/jwks.json                              — public signing keys (RS256)
GET  /oauth/authorize                                    — authorization endpoint (browser)
POST /oauth/token                                        — token endpoint
GET  /oauth/userinfo                                     — userinfo endpoint
POST /oauth/userinfo                                     — same, accepts POST too
POST /oauth/introspect                                   — RFC 7662 token introspection
POST /oauth/revoke                                       — RFC 7009 token revocation
```

`POST /oauth/token` grant types:

```text
grant_type=authorization_code   — exchange code (PKCE) for tokens
grant_type=refresh_token        — refresh access token
grant_type=client_credentials   — service-account flow
grant_type=device_code          — device-code grant after polling success
```

`/oauth/userinfo` returns `{ sub, email, email_verified, name, picture, roles, groups, permissions }`. Subject to scope: `openid` is required, `profile` adds name/picture, `email` adds email/email_verified.

---

## 12. Service accounts (server-to-server)

### 12.1 Create — `POST /api/v1/admin/service-accounts`

**Auth: required.** **Admin.**

```jsonc
{ "name": "My Backend Service", "description": "Automated data pipeline" }
```

Response includes `secret` **once** — save it.

### 12.2 Use — `POST /oauth/token`

```bash
curl -X POST "$NYXID_BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<SERVICE_ACCOUNT_ID>" \
  -d "client_secret=<SECRET>"
```

Token TTL defaults to 1 hour.

---

## 13. Approvals

### 13.1 Configure a service — `PUT /api/v1/approvals/service-configs/{service_id}`

**Auth: required.** Service owner / admin.

```jsonc
{ "approval_required": true, "approval_mode": "per_request" }   // default
{ "approval_required": true, "approval_mode": "grant" }         // legacy — creates time-based grants
```

### 13.2 List requests — `GET /api/v1/approvals/requests`

### 13.3 Request detail — `GET /api/v1/approvals/requests/{id}`

### 13.4 Decide — `POST /api/v1/approvals/requests/{id}/decide`

```jsonc
{ "approved": true }
{ "approved": false, "reason": "Not authorized for production data" }
```

### 13.5 Status (poll) — `GET /api/v1/approvals/requests/{id}/status`

Returns `{ status, expires_at, action_description }` where `status` ∈ `pending | approved | denied`.

### 13.6 Grants (only meaningful in grant mode)

```text
GET    /api/v1/approvals/grants
DELETE /api/v1/approvals/grants/{id}
GET    /api/v1/approvals/service-configs
DELETE /api/v1/approvals/service-configs/{service_id}
```

### 13.7 Proxy responses on gated services

| Status | Meaning |
|---|---|
| `403 7000` | Approval pending — body has `request_id`, `action_description` |
| `403 7001` | Approval failed (rejected, expired, timed out) — body has `approve_url` |

---

## 14. Notifications

```text
GET    /api/v1/notifications/settings
PUT    /api/v1/notifications/settings
POST   /api/v1/notifications/telegram/link
DELETE /api/v1/notifications/telegram
POST   /api/v1/notifications/devices                        — register push notification device
GET    /api/v1/notifications/devices
DELETE /api/v1/notifications/devices/{id}
```

`PUT /settings` body:

```jsonc
{ "approval_email": true, "approval_push": true, "approval_telegram": true, "approval_grants": true }
```

---

## 15. SSH

```text
POST /api/v1/ssh/{service_id}/certificate                   — issue user certificate
POST /api/v1/ssh/{service_id}/exec                          — execute remote command
GET  /api/v1/ssh/{service_id}/terminal                      — interactive terminal (WebSocket upgrade)
GET  /api/v1/ssh/{service_id}                               — SSH tunnel (WebSocket upgrade)
```

Certificate body:

```jsonc
{ "public_key": "ssh-ed25519 AAAA..." }
```

Response: `{ certificate, validity_period }`. Default 30-minute TTL.

Exec body:

```jsonc
{ "command": "uptime" }
```

Response: `{ stdout, stderr, exit_code }`.

WebSocket terminal / tunnel: see NyxID's `docs/SSH_REMOTE_EXEC.md` and `docs/SSH_TUNNELING.md` for the wire protocol.

---

## 16. LLM Gateway

OpenAI-compatible interface that injects user-stored credentials.

```text
GET  /api/v1/llm/status                                     — providers available + caller's keys
ANY  /api/v1/llm/gateway/{path}                             — unified gateway (auto-routes to active provider)
ANY  /api/v1/{provider-slug}/{path}                         — route to specific provider
```

Example (OpenAI-compatible):

```bash
curl "$NYXID_BASE/api/v1/llm/gateway/v1/chat/completions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hello"}]}'
```

OpenClaw integration via `s/llm-openclaw/`:

```text
POST /api/v1/proxy/s/llm-openclaw/v1/chat/completions       — chat completions
POST /api/v1/proxy/s/llm-openclaw/tools/invoke              — tools / skills
POST /api/v1/proxy/s/llm-openclaw/v1/responses              — OpenResponses API
```

---

## 17. API keys (NyxID-side bearers)

### 17.1 Create — `POST /api/v1/api-keys`

**Auth: required.**

```jsonc
{
  "name": "AI Agent Key",
  "scopes": "read write proxy",                      // space-separated scope list
  "allowed_service_ids": ["<svc-uuid>", ...],         // restrict which services this key can proxy through
  "allowed_node_ids": ["<node-uuid>", ...],           // restrict node routing
  "allow_all_services": true,                         // ignore allowed_service_ids when true (default)
  "allow_all_nodes": true,                            // ignore allowed_node_ids when true (default)
  "callback_url": "https://my-agent.example.com/webhook"  // optional — channel bot relay
}
```

Response includes `full_key` **once** — save it. Format: `nyxid_...`.

### 17.2 List — `GET /api/v1/api-keys`

**Auth: required.** Returns metadata only — never the key value.

### 17.3 Show — `GET /api/v1/api-keys/{id}`

**Auth: required.**

### 17.4 Update — `PUT /api/v1/api-keys/{id}`

**Auth: required.**

```jsonc
{ "allowed_node_ids": [...], "allow_all_services": false, "callback_url": "..." }
```

### 17.5 Rotate — `POST /api/v1/api-keys/{key_id}/rotate`

**Auth: required.** Returns a new value, invalidates the old. One-time display.

### 17.6 Delete — `DELETE /api/v1/api-keys/{key_id}`

**Auth: required.**

### 17.7 Bindings (`/keys/.../bind`)

CLI: `nyxid api-key bind <ID> --service <SLUG>`. Use bindings + `allow_all_services: false` for tightly-scoped agent keys.

---

## 18. Admin

```text
GET  /api/v1/admin/users                                    — list all users
GET  /api/v1/admin/audit-log                                — platform audit log
POST /api/v1/admin/service-accounts                         — create service account (§12)
POST /api/v1/admin/invite-codes                             — mint invite codes
```

`POST /admin/invite-codes` body:

```jsonc
{ "max_uses": 10, "expires_at": "2026-12-31T23:59:59Z" }
```

`max_uses` accepts 1..1000.

---

## 19. Health / readiness / discovery

```text
GET  /health                                                — liveness probe
GET  /livez                                                 — alias for /health
GET  /readyz                                                — readiness (checks DB)
GET  /openapi.json                                          — auto-generated OpenAPI 3 schema
GET  /llms-full.txt                                         — LLM-friendly playbook (auto-derived from docs)
```

---

## 20. Common error codes (cross-cutting)

| Code | Status | Meaning |
|---|---|---|
| `AUTH_MISSING` / `invalid_token` | 401 | No usable identity |
| `FORBIDDEN` | 403 | Authed but missing role / permission / ownership |
| `NOT_FOUND` | 404 | Resource missing or hidden |
| `VALIDATION_ERROR` | 400 | Request body failed validation |
| `RATE_LIMITED` | 429 | Too many calls |
| `INTERNAL_ERROR` | 500 | Unhandled — capture `X-Request-ID` |

NyxID-specific codes appear per-route; consult the dashboard's error display or NyxID's source for the canonical list.

---

## 21. What's NOT exposed (yet)

The following are **dashboard-only** today; AI agents cannot drive them via API. When the user asks for these, surface the dashboard URL and stop:

- **Org creation, invitation flow, member approval, role binding inside an org** — `<NYXID_FRONTEND>/orgs/<orgId>/members`. See `SKILL.md` §1.4 for the workaround.
- **Email verification template management** — admin dashboard.
- **Custom catalogue service authoring with branded metadata** — admin section under `<NYXID_FRONTEND>/services`.

When in doubt, look at the dashboard first; if there's no UI, the API likely doesn't exist either.

# NyxID CLI Recipes

Companion to `SKILL.md` §1. Quick lookup for `nyxid` CLI subcommands. Each subcommand is shown with its required flags and the most common optional ones; full flag tables are in `nyxid <subcommand> --help`. The CLI auto-attaches the bearer token from `~/.nyxid/access_token` (or `$NYXID_API_KEY`); you don't pass it manually.

> Once you have run `nyxid login --base-url <URL>`, the URL is persisted to `~/.nyxid/base_url`. **You do not need to pass `--base-url` on subsequent commands.** To switch environments, log out, log in to the other URL.

---

## Install / version

```bash
# From git (requires Rust toolchain — https://rustup.rs)
cargo install --git https://github.com/ChronoAIProject/NyxID nyxid-cli

# From local checkout
git clone https://github.com/ChronoAIProject/NyxID && cd NyxID && cargo install --path cli

# Verify
nyxid --version
nyxid status                                              # base URL + auth state
```

If a CLI command fails with an unrecognised flag or missing subcommand, the CLI is outdated. Reinstall first.

---

## Login / logout / refresh

```bash
# Browser-mode login (opens browser for OAuth)
nyxid login --base-url <NYXID_API_BASE>
nyxid login --base-url https://nyx-api.chrono-ai.fun     # production
nyxid login --base-url http://localhost:3001             # local self-host

# Headless / AI-agent password login (user sets $NYXID_PASSWORD first)
nyxid login --base-url <URL> --password --password-env NYXID_PASSWORD --email <email>

# Verify
nyxid whoami
nyxid status

# Force a token refresh (rare — auto-refresh is default)
nyxid auth refresh

# Log out (deletes ~/.nyxid/access_token + base_url)
nyxid logout
```

Tokens persist at `~/.nyxid/access_token` and `~/.nyxid/refresh_token`. Base URL persists at `~/.nyxid/base_url`.

---

## Identity

```bash
# Caller identity (userId, email, displayName, roles, permissions)
nyxid whoami

# Status (base URL, login state, token freshness)
nyxid status
```

If `whoami` shows roles but empty permissions, see `nyxid-token-model.md` §4.1 (headers-mode propagation).

---

## API keys (NyxID-side, long-lived bearers)

```bash
# Create — returns the full key value ONCE; save it immediately
nyxid api-key create --name "AI Agent Key" --scopes "read write"

# With callback URL (channel bot relay)
nyxid api-key create --name "relay-agent" --callback-url "https://my-agent.example.com/webhook"

# List
nyxid api-key list                                        # human table
nyxid api-key list --output json

# Show full details (bindings, allowed services, allowed nodes)
nyxid api-key show <ID>

# Rotate (issues a new value, invalidates old)
nyxid api-key rotate <ID>

# Delete
nyxid api-key delete <ID>

# Bindings — restrict the key to specific services
nyxid api-key bind <ID> --service <SLUG>
nyxid api-key bind <ID> --service <SLUG> --credential <LABEL>   # explicit override

# Restrict to bound services only
nyxid api-key update <ID> --allow-all-services false

# Restrict to specific nodes
nyxid api-key update <ID> --allowed-nodes "<NODE_ID>" --allow-all-nodes false

# Update callback URL
nyxid api-key update <ID> --callback-url "https://..."
```

Use the value as `Authorization: Bearer nyxid_...` in HTTPS calls, or export as `$NYXID_API_KEY` for the CLI to pick up automatically.

---

## Catalogue (read-only — discover available services)

```bash
# Browse — connectable services only
nyxid catalog list

# Include system / no-auth services
nyxid catalog list --all

# Inspect a single service template
nyxid catalog show <slug>
nyxid catalog show llm-openai

# Endpoints parsed from the service's OpenAPI spec
nyxid catalog endpoints <slug>
```

The `show` response includes rich metadata: `homepage_url`, `repository_url`, `openapi_spec_url`, `capabilities` flags, `auth_notes`, `known_limitations`, `required_permissions`.

---

## Services (your installed AI services)

```bash
# List all your services
nyxid service list
nyxid service list --output json

# Show full detail
nyxid service show <slug>

# Add from catalogue (user exports $SERVICE_CREDENTIAL first; agent never sees the value)
nyxid service add <slug> --credential "$SERVICE_CREDENTIAL" --label "Production"

# Catalogue + custom endpoint URL (e.g. self-hosted instance)
nyxid service add llm-openclaw --credential "$SERVICE_CREDENTIAL" \
  --endpoint-url "http://localhost:18789" --label "Local OpenClaw"

# OAuth flow
nyxid service add github --oauth                          # opens browser

# Fully custom — no catalogue entry
nyxid service add-custom \
  --label "Internal API" \
  --endpoint-url "https://internal.corp.com/api" \
  --credential "$SERVICE_CREDENTIAL" \
  --auth-method header --auth-key-name "X-API-Key"

# Update — rename
nyxid service update <slug> --label "My Custom Name"

# Update — endpoint URL
nyxid service update <slug> --endpoint-url "http://localhost:8080/openai"

# Route through a node
nyxid service update <slug> --node-id "<NODE_UUID>"
nyxid service route <SERVICE_ID> --node <NODE_ID>          # equivalent
nyxid service route <SERVICE_ID> --direct                  # back to direct routing

# Delete
nyxid service remove <slug>

# Add a service routed through a node in one call (creates backend record + sets routing)
nyxid service add <slug> --via-node <node-name-or-id>
nyxid service add --custom --via-node <node-name-or-id>    # interactive prompts for URL + auth
```

---

## SSH services

```bash
# Register an SSH service (admin-only; --via-node optional)
nyxid service add-ssh \
  --label "Production Server" --host 10.0.0.5 --port 22 \
  --cert-auth --principals "ubuntu,deploy" --ttl 30 --via-node "$NODE_ID"

# Issue a short-lived user certificate
nyxid ssh issue-cert <SERVICE_ID_OR_SLUG> \
  --public-key-file ~/.ssh/id_ed25519.pub \
  --principal ubuntu \
  --certificate-file ~/.ssh/id_ed25519-cert.pub

# Remote command execution
nyxid ssh exec <SERVICE_ID_OR_SLUG> --principal ubuntu -- uptime

# Interactive terminal
nyxid ssh terminal <SERVICE_ID_OR_SLUG>
nyxid ssh terminal <SERVICE_ID_OR_SLUG> --principal ubuntu

# OpenSSH ProxyCommand integration
nyxid ssh proxy <SERVICE_ID_OR_SLUG>

# With auto certificate issuance
nyxid ssh proxy <SERVICE_ID_OR_SLUG> \
  --issue-certificate \
  --public-key-file ~/.ssh/id_ed25519.pub \
  --principal ubuntu \
  --certificate-file ~/.ssh/id_ed25519-cert.pub

# Generate an OpenSSH config stanza
nyxid ssh config \
  --host-alias prod-server \
  --base-url <NYXID_API_BASE> \
  --service-id "$SERVICE_ID" \
  --principal ubuntu \
  --identity-file ~/.ssh/id_ed25519 \
  --certificate-file ~/.ssh/id_ed25519-cert.pub
```

---

## Proxy (call upstream APIs through NyxID with credential injection)

```bash
# Standard JSON request
nyxid proxy request <slug> <path-after-base-url> \
  --method POST --data '{"foo":"bar"}' --output json

# Streaming response
nyxid proxy request llm-openai v1/chat/completions \
  --method POST --stream \
  --data '{"model":"gpt-4","stream":true,"messages":[{"role":"user","content":"Hello"}]}'

# By service ID instead of slug
nyxid proxy request <SERVICE_ID> v1/chat/completions --by-id \
  --method POST --data '{...}'

# Custom headers
nyxid proxy request <slug> <path> \
  --method GET --header "X-Custom: value"

# Discover what the caller can route through
nyxid proxy discover --output json
```

Path is everything *after* the service's base URL. The proxy prepends the service base + injects the configured credential automatically.

---

## Approvals (transaction approval / per-request gating)

```bash
# Configure a service to require approval — per-request mode (default)
nyxid approval set-config <SERVICE_ID> --require-approval true

# Grant mode (legacy — approval creates a time-based grant)
nyxid approval set-config <SERVICE_ID> --require-approval true --approval-mode grant

# View pending approval requests
nyxid approval list
nyxid approval show <REQUEST_ID>

# Approver actions
nyxid approval approve <REQUEST_ID>
nyxid approval deny <REQUEST_ID> --reason "Not authorized for production data"

# Grants (only relevant in grant mode)
nyxid approval grants
nyxid approval revoke-grant <GRANT_ID>

# Per-service configs
nyxid approval service-configs
```

When a request hits an approval-gated service, the proxy returns `403 7000` (pending) or `403 7001` (failed) with an `action_description` and `approve_url`.

---

## Notifications (Telegram / mobile push for approvals)

```bash
nyxid notification settings                               # current preferences
nyxid notification update --approval-email true \
                          --approval-push true \
                          --approval-telegram true
nyxid notification telegram-link                          # link Telegram account
nyxid notification telegram-disconnect
```

---

## Nodes (on-premise credential agents)

```bash
# Generate a registration token (admin or self-service depending on policy)
nyxid node register-token

# Register the node (run on the box where the agent will live)
nyxid node register --token "<NYX_NREG_TOKEN>" --url "wss://localhost:3001/api/v1/nodes/ws" --keychain
nyxid node register --token "<NYX_NREG_TOKEN>" --url "wss://localhost:3001/api/v1/nodes/ws"

# Add a credential locally (auto-detects setup based on catalog)
nyxid node credentials setup --service <SLUG>

# Manual add for custom endpoints (register backend record first)
nyxid service add --custom --via-node <NODE>
nyxid node credentials add --service <SLUG> --header "Authorization" --secret-format Bearer

# OAuth flow from the node
nyxid node credentials add-oauth --service <SLUG> --from-catalog

# List / remove credentials
nyxid node credentials list
nyxid node credentials remove --service <SLUG>

# Lifecycle
nyxid node start                                          # foreground
nyxid node start --log-level debug

# Daemon (background service)
nyxid node daemon install
nyxid node daemon start
nyxid node daemon status
nyxid node daemon restart
nyxid node daemon stop
nyxid node daemon logs --follow
nyxid node daemon uninstall

# Node management (server-side)
nyxid node list
nyxid node show <NODE_ID>
nyxid node delete <NODE_ID>
nyxid node rotate-token <NODE_ID>

# Secret-storage migration
nyxid node migrate --to keychain
nyxid node migrate --to file

# OpenClaw integration
nyxid node openclaw connect --url <GATEWAY_URL>
nyxid node openclaw status
nyxid node openclaw disconnect
```

Daemon paths:

- macOS: `~/Library/LaunchAgents/dev.nyxid.node.plist`
- Linux: `~/.config/systemd/user/nyxid-node.service`

The daemon auto-reloads credentials within 5 seconds of file changes — no restart needed for routine credential rotation.

---

## MCP setup (auto-configure your AI tool)

```bash
nyxid mcp setup cursor       # writes .cursor/mcp.json
nyxid mcp setup claude       # writes .claude/settings.json MCP entry
nyxid mcp setup codex        # writes ~/.codex/config.toml entry
```

Manual setup (any AI client):

```bash
# Claude Code
claude mcp add --transport http --scope user nyxid http://localhost:3001/mcp

# Cursor — edit .cursor/mcp.json
{ "mcpServers": { "nyxid": { "url": "http://localhost:3001/mcp" } } }

# Codex — edit ~/.codex/config.toml
[mcp_servers.nyxid]
url = "http://localhost:3001/mcp"
```

After setup, restart the AI client; it'll prompt for OAuth in the browser on first use.

---

## OAuth clients (for "Sign in with NyxID" apps)

CLI subcommands are limited; most operations go through HTTP. For full HTTP catalogue see `nyxid-api-reference.md` § "Developer Apps". Typical usage:

```bash
# (HTTP) Register a public OAuth client (no secret)
curl -X POST "$NYXID_BASE/api/v1/developer/oauth-clients" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "redirect_uris": ["https://myapp.example.com/auth/callback"],
    "client_type": "public",
    "allowed_scopes": ["openid", "profile", "email"]
  }'

# (HTTP) Rotate secret for confidential client
curl -X POST "$NYXID_BASE/api/v1/developer/oauth-clients/<id>/rotate-secret" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Common usage patterns

### Multi-environment switching

The CLI tracks one base URL at a time. To flip between staging / prod / local:

```bash
nyxid logout
nyxid login --base-url <other-base>
```

Tokens are not shared across environments — logging out of prod and into local always re-prompts.

### Background-process token usage

For scripts / cron / daemons that can't run `nyxid login` interactively:

```bash
# Once, with a human at the keyboard
nyxid api-key create --name "cron-job" --scopes "proxy read"
# Save output to e.g. /etc/secrets/nyxid_api_key (mode 0600)

# In the script
export NYXID_API_KEY="$(cat /etc/secrets/nyxid_api_key)"
nyxid proxy request ornn-api "/api/v1/skill-search?scope=public&pageSize=5" --method GET --output json
```

The CLI uses `$NYXID_API_KEY` when no interactive token exists. The bearer is sent as `X-API-Key` for API-key-mode and `Authorization: Bearer` for OIDC-token-mode — same endpoints, same response shapes.

### Diagnosing CLI-side auth failures

```bash
nyxid status                                              # is the base URL set, is there a token, when does it expire
nyxid whoami                                              # what does the server say about your identity
nyxid auth refresh                                        # force a refresh — useful if `whoami` says expired
```

If `whoami` returns identity but Ornn calls 403, the issue is permission-side (see `nyxid-token-model.md` §6) not auth-side.

---

## Globals

`--log-level <trace|debug|info|warn|error>` — verbose CLI logging. Default `info`.
`--config <PATH>` — alternate config dir for `nyxid node` (default `~/.nyxid-node`).
`--output <table|json>` — preferred output format (default human table; use `json` for parsing).

# NyxID Token Model

Companion to `SKILL.md` §0.6 + §3. This file explains how NyxID tokens flow — bearer issuance, refresh, scope vs permission, the proxy strip vs forward decision, JWT-mode vs headers-mode identity propagation, the per-user `forward_access_token` flag, and the role → permission mapping. Consult when you hit a 401 / 403 / silent-empty-list and need to know *why*.

---

## 1. Token types

NyxID issues four kinds of credentials. Pick the right one for the situation:

| Type | TTL | Use case | How to get one |
|---|---|---|---|
| **Access token (OIDC)** | 15 min default | Interactive user sessions, CLI after `nyxid login`, "Sign in with NyxID" web apps | OIDC authorization-code flow with PKCE; or `POST /api/v1/auth/login` with email + password |
| **Refresh token** | Long-lived (configurable) | Rotate the access token without re-prompting the user | Returned alongside the access token |
| **NyxID API key** | Indefinite (until revoked) | Headless agents, CI / cron, AI-tool environments where browser OAuth is impractical | `nyxid api-key create --name "..."` or `POST /api/v1/api-keys`. Returns the value **once** |
| **Service account access token** | 1 hour default | Server-to-server (no human), client_credentials grant | `POST /oauth/token` with `grant_type=client_credentials`, using a service-account `client_id` + `client_secret` (admin creates it via `POST /api/v1/admin/service-accounts`) |

All four are bearer tokens. Pass them as `Authorization: Bearer <value>`. NyxID API keys may also be passed as `X-API-Key: <value>`.

---

## 2. Refresh flow

```bash
# Refresh an access token using a refresh token
curl -X POST "$NYXID_BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<REFRESH_TOKEN>" \
  -d "client_id=<YOUR_CLIENT_ID>"

# Or use the JSON convenience endpoint
curl -X POST "$NYXID_BASE/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<REFRESH_TOKEN>"}'
```

The CLI does this automatically — `nyxid` checks token expiry on each call and refreshes when needed, transparently to the agent. NyxID API keys never refresh because they don't expire.

> **Permissions are baked into a token at issue time.** If the user gets a new role mid-session, the existing access token does not pick it up. The CLI may auto-refresh and inherit the new permissions, depending on whether the refresh-token flow re-issues claims (it usually does), but the safest path is **log out + log in again** after a role change.

---

## 3. Scope vs permission — they're not the same thing

Two orthogonal authorization layers, often confused:

| Layer | What it gates | Where it lives |
|---|---|---|
| **Scope** (`openid`, `profile`, `email`, ...) | OIDC userinfo endpoint, what claims the access token carries | OAuth client config + token-issue request |
| **Permission** (`ornn:skill:read`, `ornn:skill:create`, ...) | NyxID-protected API surface, including everything Ornn exposes | NyxID role definitions, baked into the token at issue time |

A token with `openid profile email` and **no Ornn permissions** can authenticate to NyxID's `/oauth/userinfo` but every Ornn write call returns `403 FORBIDDEN: Missing permission: <name>`. Conversely, a token with `ornn:skill:create` but no `email` scope can create skills but cannot read its own email.

**You almost always care about permissions, not scopes,** when you're the agent. Scopes matter for OIDC integrations (§1.6 in `SKILL.md`).

---

## 4. The proxy — what it does to your token

Every Ornn API call goes through the **NyxID proxy**. The proxy is a separate component sitting between the caller and `ornn-api`. Its job:

1. Validate the inbound bearer (signature + expiry + issuer).
2. Decode the identity (or look it up from the API key).
3. Forward to the target service with **identity headers**, optionally also forwarding the bearer.
4. Stream the response back.

### 4.1 Forwarded identity headers

Two propagation modes, controlled by the per-service `forward_identity_mode` setting on each NyxID-side service binding:

| Mode | Headers Ornn receives | What `permissions[]` looks like |
|---|---|---|
| **JWT (preferred)** | `X-NyxID-Identity-Token` — a single signed JWT carrying `sub`, `email`, `name`, `roles[]`, `permissions[]` | Populated correctly. Every Ornn `requirePermission` gate works as expected. |
| **Headers (legacy)** | `X-NyxID-User-Id`, `X-NyxID-User-Email`, `X-NyxID-User-Name` — scalar headers | **Empty** (`permissions: []`). Every gated route returns `403 FORBIDDEN`. |

If `GET /me` returns `200` with empty `permissions`, the Ornn service binding is in headers mode. **Fix:** ask the NyxID admin to flip `forward_identity_mode` to `jwt` on the Ornn service binding in the dashboard. The user must then log out + log in (so a new token round-trip happens through the new mode).

### 4.2 Bearer token strip vs forward

By default, the proxy **does not forward the caller's bearer to the upstream service**. It strips it. This is a security property — the upstream sees identity (via `X-NyxID-*` headers) but never the raw bearer, so it can't impersonate the caller against other services.

Some Ornn endpoints, however, need to call **NyxID itself** on the caller's behalf — most notably `/me/orgs`, which enumerates the user's NyxID org memberships. For Ornn to do that, the proxy must forward the bearer through. This is controlled by a **per-user, per-service** flag: `forward_access_token`.

- **Off (default)** — Ornn cannot call NyxID as the user. `/me/orgs` fail-softs to `[]` (no error, no log entry beyond `duration:0`).
- **On** — Ornn receives the bearer in the forwarded request and uses it to call NyxID's user-facing endpoints.

**This is one of the highest-frequency silent failures.** If `/me/orgs` returns `200 + empty list` for a user you know is in orgs, the flag is off. The user must turn it on in the dashboard themselves (NyxID frontend → AI Services → `ornn-api` → "Forward Access Token" toggle). After flipping, run `/me/orgs` again — non-zero `duration` in the server log + populated `items` confirms it's working.

The flag is per-user (every user toggles their own), per-service (the toggle on the `ornn-api` binding doesn't affect other services), and deliberately defaulted off as a least-privilege posture.

### 4.3 Strip vs forward — diagnostic table

| Symptom | Likely cause |
|---|---|
| `GET /api/v1/me` returns `200` with `permissions: []` | Headers-mode identity propagation (§4.1). Fix: flip `forward_identity_mode` to `jwt`. |
| `GET /api/v1/me/orgs` returns `200` with `items: []` for a user you know is in orgs; server logs show `duration:0` | `forward_access_token` is off. Fix: user flips it on in NyxID dashboard. |
| `GET /api/v1/me/orgs` returns `500 NYXID_ORG_LOOKUP_FAILED` | Ornn called NyxID and got a non-OK response other than 404/403. Most likely cause in prod: `NYXID_BASE_URL` is unset and the host-derivation fallback is wrong (frontend host ≠ API host — see §5). |
| Every authenticated call returns `401 AUTH_MISSING` | Token expired, malformed, or the proxy didn't recognise it. Re-run `nyxid login` (or re-export `$NYXID_API_KEY`). |
| Every gated call returns `403 FORBIDDEN: Missing permission: <name>` | The token's `permissions[]` doesn't include the name. Either headers-mode propagation (§4.1) or NyxID role mapping doesn't grant it. |

---

## 5. `NYXID_BASE_URL` — production gotcha

Ornn has a fallback that derives the NyxID API base URL from the proxy-forwarded token's issuer claim. **The fallback assumes the NyxID frontend and API live on the same host.**

In production, our deployment splits them:

- Frontend: `https://nyx.chrono-ai.fun`
- API: `https://nyx-api.chrono-ai.fun`

The fallback derives `https://nyx.chrono-ai.fun/api/...` from the token issuer, which is **wrong** — the API is on a different host. Server-side calls back to NyxID (e.g. `/me/orgs` org resolution) fail with network errors or `NYXID_ORG_LOOKUP_FAILED`.

**Fix:** ornn-api MUST run with `NYXID_BASE_URL=https://nyx-api.chrono-ai.fun` set explicitly in its environment. Locally on a single-host self-hosted NyxID this isn't required (frontend + API on `localhost:3001` — fallback is correct), but in **any** deployment where the frontend and API have different hosts, you must set it.

This was the cause of an Ornn v0.5.0 prod incident. Keep it on the checklist when standing up new environments.

---

## 6. Role → permission mapping

The mapping is owned by NyxID, configured in the NyxID admin UI (or via NyxID's role API), not Ornn. The defaults shipped with NyxID:

| NyxID role | Permissions granted (Ornn-relevant) |
|---|---|
| `ornn-user` | `ornn:skill:read`, `ornn:skill:create`, `ornn:skill:update`, `ornn:skill:delete`, `ornn:skill:build`, `ornn:playground:use` |
| `ornn-admin` | All of `ornn-user` plus `ornn:admin:skill`, `ornn:admin:category` |
| (no Ornn role) | empty Ornn permissions; user can hit anonymous endpoints only |

To grant a permission to a user:

1. NyxID admin assigns the role in the NyxID dashboard (`Users → <user> → Roles`).
2. The user logs out and logs in again — permissions are baked at token-issue time.

There is no "promote my permissions mid-session" flow. The CLI's auto-refresh *may* pick up new permissions if NyxID re-issues claims on refresh-token grants; the only reliable path is full re-login.

---

## 7. Anonymous calls — what works without a token

A small slice of Ornn is reachable with no `Authorization` header at all:

- `GET /api/v1/skill-format/rules` — canonical skill format spec.
- `GET /api/v1/skill-search` with `scope=public` — public skills only, keyword mode (semantic mode requires auth — `400 AUTH_REQUIRED`).
- `GET /api/v1/skills/:idOrName` for public skills — anonymous gets `404 SKILL_NOT_FOUND` for private (existence is intentionally not leaked).
- `GET /api/v1/skills/:idOrName/versions`, `/audit`, `/audit/history`, `/audit/summary-by-version`, `/analytics`, `/analytics/pulls` — visibility-gated to public skills only when anonymous.
- `GET /api/v1/skills/:idOrName/json` — **requires auth + `ornn:skill:read`**. The closest signal to "agent pulled this skill"; recorded as `api` source in analytics.
- `GET /openapi.json`, `/health`, `/livez`, `/readyz` — all anonymous.

Everything else requires authentication. The full per-endpoint auth + authorization rules are in `references/ornn-api-reference.md` §1.4 and per-endpoint sections.

---

## 8. Self-hosted vs hosted differences

| Concern | Hosted (production) | Self-hosted (localhost) |
|---|---|---|
| Frontend host | `https://nyx.chrono-ai.fun` | `http://localhost:3000` |
| API host | `https://nyx-api.chrono-ai.fun` | `http://localhost:3001` |
| Ornn host | `https://ornn.chrono-ai.fun` | varies — you set it |
| TLS | Always required | Usually disabled for `localhost` |
| `NYXID_BASE_URL` on `ornn-api` | **Must be explicit** (see §5) | Optional — fallback works |
| Email verification | Enabled by default | Auto-verified if `AUTO_VERIFY_EMAIL=true` in `.env.dev` |
| Invite codes | Required for registration | Disabled if `INVITE_CODE_REQUIRED=false` |
| OIDC issuer in tokens | `https://nyx-api.chrono-ai.fun` | `http://localhost:3001` |

Self-hosted NyxID setup is documented in the NyxID repo's `README.md` and `docs/QUICKSTART.md`.

---

## 9. Quick reference — when something doesn't work

```text
401 AUTH_MISSING                    → re-login or re-export $NYXID_API_KEY
403 FORBIDDEN: Missing permission   → either §4.1 (headers mode) or §6 (role not granted)
200 + permissions:[]                → §4.1 — headers mode; flip forward_identity_mode=jwt
200 + me/orgs items:[] + dur:0      → §4.2 — forward_access_token off; user toggles in dashboard
500 NYXID_ORG_LOOKUP_FAILED in prod → §5 — set NYXID_BASE_URL explicitly
404 SKILL_NOT_FOUND for known skill → private skill, you're not in share list (intentional)
```

# Ornn API Reference

Companion to `SKILL.md` §2. This file enumerates every endpoint in the Ornn HTTP surface (`/api/v1/*`) plus the four out-of-band routes the deployment exposes for health and OpenAPI introspection. Each endpoint lists its full path, request shape (headers, params, body), success response, all known error codes, authentication requirement, and authorization rules. The contents below are derived from `ornn-api/src/domains/**/routes.ts` and `ornn-api/src/bootstrap.ts`. If the code disagrees with this document, the code is the source of truth — re-pull the skill (`SKILL.md` §0) and report the drift.

> **Companion files in this skill:** `nyxid-api-reference.md` for the NyxID side of the stack (identity, services catalogue, orgs, OAuth clients, proxy); `nyxid-token-model.md` for how bearers / scopes / permissions actually flow through the proxy; `nyxid-cli-recipes.md` for the CLI subcommand quick reference; `installed-skills-registry.md` for the `~/.ornn/installed-skills.json` schema.

---

## Table of contents

1. [Conventions](#1-conventions)
   - 1.1 Base URL and versioning
   - 1.2 Response envelope
   - 1.3 Authentication
   - 1.4 Authorization model
   - 1.5 Permission catalogue
   - 1.6 Visibility rules for skills
   - 1.7 HTTP status mapping
   - 1.8 Error code legend
   - 1.9 SSE protocol
   - 1.10 Pagination
   - 1.11 Standard headers
2. [Out-of-band endpoints](#2-out-of-band-endpoints)
3. [Skills CRUD](#3-skills-crud)
4. [Skill audit](#4-skill-audit)
5. [Skill search](#5-skill-search)
6. [Skill format](#6-skill-format)
7. [Skill generation (SSE)](#7-skill-generation-sse)
8. [Playground (SSE)](#8-playground-sse)
9. [Notifications](#9-notifications)
10. [Analytics](#10-analytics)
11. [Me — caller scope](#11-me--caller-scope)
12. [Users directory](#12-users-directory)
13. [Admin](#13-admin)
14. [Platform settings](#14-platform-settings)

---

## 1. Conventions

### 1.1 Base URL and versioning

Every domain endpoint is mounted under `/api/v1/`. There is exactly one mounted version; v0 was retired pre-1.0. Out-of-band endpoints (§2) live at the root.

| Environment | Base URL |
|---|---|
| Production | `https://ornn.chrono-ai.fun/api/v1` |
| Other deployments | `https://<host>/api/v1` (configured via `ORNN_API_URL`) |

Agents reach the API through the NyxID proxy — they do not call the host directly. The proxy adds the auth headers described in §1.3 and forwards the request to `ornn-api`.

### 1.2 Response envelope

Every JSON response uses this exact envelope:

```jsonc
{
  "data":  <T> | null,
  "error": { "code": "STRING_CODE", "message": "Human-readable explanation" } | null
}
```

- `2xx` responses → `data` populated, `error: null`.
- `4xx` / `5xx` responses → `data: null`, `error` populated.
- SSE responses (§7, §8) do **not** use the envelope. Each `data:` line in the stream is a self-contained JSON event.

Always check HTTP status as well as `error`: a TLS/proxy error may return a non-Ornn body that does not follow the envelope.

### 1.3 Authentication

All `/api/v1/*` requests pass through the **NyxID proxy** (which is itself an OAuth-protected gateway). The proxy verifies the caller's bearer token and rewrites the request with a set of forwarded identity headers before handing it to `ornn-api`. The backend never validates JWT signatures directly — it trusts the proxy.

Two propagation modes are supported (driven by NyxID's `forward_identity_mode` setting on the `ornn-api` service):

| Mode | Header(s) read by `ornn-api` | Notes |
|---|---|---|
| **JWT (preferred)** | `X-NyxID-Identity-Token` | Single signed JWT carrying `sub`, `email`, `name`, `roles[]`, `permissions[]`. The backend decodes (no verification — proxy already verified) and populates the auth context. |
| **Headers (legacy)** | `X-NyxID-User-Id`, `X-NyxID-User-Email`, `X-NyxID-User-Name` | Scalar headers only. `roles` and `permissions` arrive empty, so any `requirePermission`-gated route returns 403. |

For agent / SDK callers via `nyxid proxy request ornn-api ...`, the proxy handles all of this — the agent only needs `Authorization: Bearer <user-token>`. The proxy may also forward that bearer token through to `ornn-api` so that ornn can call NyxID on the caller's behalf (used by `/me/orgs`). When forwarding is disabled, org lookups fail-soft to an empty list.

When auth fails (no usable identity headers), every authenticated route responds:

```jsonc
{ "data": null, "error": { "code": "AUTH_MISSING", "message": "Authentication required" } }
```

with HTTP 401.

### 1.4 Authorization model

Two layers stack:

1. **Permission gate** — `requirePermission("ornn:foo:bar")` checks that the proxy-asserted permission set includes the named string. Failures return 403 `FORBIDDEN` with `Missing permission: <name>`.
2. **Resource gate** — for skill-scoped writes and reads of private skills, an additional ownership / visibility check (`canManageSkill`, `canReadSkill`) runs after the permission gate. Failures return 403 `FORBIDDEN` (writes) or 404 `SKILL_NOT_FOUND` (reads — to avoid leaking existence).

Skill writes always require **author OR platform admin**. Org admins do **not** inherit write access on skills shared with their org.

### 1.5 Permission catalogue

Permissions are issued by NyxID as part of the proxy-forwarded identity. Roles map to permissions; the role-to-permission mapping is configured in NyxID, not Ornn.

| Permission | Typical role | Endpoints it unlocks |
|---|---|---|
| `ornn:skill:read` | `ornn-user` | `GET /skills/:idOrName/json`, `POST /skill-format/validate` |
| `ornn:skill:create` | `ornn-user` | `POST /skills`, `POST /skills/pull` |
| `ornn:skill:update` | `ornn-user` | `PUT /skills/:id`, `PUT /skills/:id/permissions`, `POST /skills/:id/refresh`, `PATCH /skills/:idOrName/versions/:version` |
| `ornn:skill:delete` | `ornn-user` | `DELETE /skills/:id`, `DELETE /skills/:idOrName/versions/:version` |
| `ornn:skill:build` | `ornn-user` | `POST /skills/generate`, `POST /skills/generate/from-source`, `POST /skills/generate/from-openapi` |
| `ornn:playground:use` | `ornn-user` | `POST /playground/chat` |
| `ornn:admin:skill` | `ornn-admin` | All `/admin/*` skill-scoped routes; admin force-audit; platform settings |
| `ornn:admin:category` | `ornn-admin` | `GET/POST/PUT/DELETE /admin/categories/*` |

A few endpoints (`POST /skills/:idOrName/audit`, the various caller-scoped reads) gate on **ownership** instead of (or in addition to) a permission — those are documented per-endpoint.

### 1.6 Visibility rules for skills

Reading a skill (and any of its derived data — versions, audit, analytics, diff) follows `canReadSkill`:

```text
PUBLIC skill                        → anyone (auth optional)
PRIVATE skill, anonymous caller     → 404 SKILL_NOT_FOUND
PRIVATE skill, authenticated caller →
  caller is the author              → allowed
  caller has ornn:admin:skill       → allowed
  caller's user_id is in            → allowed
    sharedWithUsers
  caller is admin/member of any org → allowed
    listed in sharedWithOrgs
  otherwise                         → 404 SKILL_NOT_FOUND
```

Note: 404 (not 403) for hidden private skills — existence is intentionally not leaked.

Writing / managing a skill (`canManageSkill`) collapses to: **author OR platform admin**, period. Org membership grants no write access.

### 1.7 HTTP status mapping

| Status | Used for |
|---|---|
| 200 | Successful read or write |
| 201 | Resource created (admin category / tag create) |
| 400 | Validation error, malformed body, bad query param |
| 401 | `AUTH_MISSING` — no usable identity from the proxy |
| 403 | `FORBIDDEN` — authed but missing permission, ownership check failed, or trying to mutate someone else's skill |
| 404 | `*_NOT_FOUND` — resource missing or hidden under visibility rules |
| 409 | Conflict (e.g. duplicate version on publish) |
| 413 | `PAYLOAD_TOO_LARGE` — ZIP exceeds `MAX_PACKAGE_SIZE_BYTES` (default 50 MiB) |
| 500 | `INTERNAL_ERROR` or domain-specific 500 — retry with backoff and include `X-Request-ID` if reporting |
| 503 | `/readyz` only — Mongo unreachable |

### 1.8 Error code legend

The codes below appear across many endpoints. Per-endpoint sections list any additional codes specific to that route.

| Code | Status | Meaning |
|---|---|---|
| `AUTH_MISSING` | 401 | No identity from the proxy. Re-run `nyxid login`. |
| `FORBIDDEN` | 403 | Permission missing, or ownership check failed. The `message` names the missing permission when relevant. |
| `NOT_SKILL_OWNER` | 403 | Variant of FORBIDDEN raised when a non-author / non-admin tries to mutate / refresh / audit a skill. |
| `SKILL_NOT_FOUND` | 404 | Skill does not exist, or exists but is hidden by visibility rules. |
| `AUDIT_NOT_FOUND` | 404 | No audit has been run for the requested skill / version. |
| `ORG_NOT_FOUND` | 404 | Org id does not resolve, or NyxID will not return it to the caller. |
| `SKILL_VERSION_NOT_FOUND` | 404 | Version string does not exist on the skill. |
| `SAME_VERSION` | 400 | `from` and `to` parameters in a diff are identical. |
| `INVALID_CONTENT_TYPE` | 400 | Endpoint expected `application/zip` (or `application/octet-stream`) and got something else. |
| `EMPTY_BODY` | 400 | Request body was zero-length when the endpoint required bytes. |
| `INVALID_QUERY` | 400 | Query string failed Zod validation. `message` lists offending fields. |
| `INVALID_BODY` / `VALIDATION_ERROR` | 400 | Body failed Zod validation. |
| `INVALID_DEPRECATION_PATCH` | 400 | Body for `PATCH /versions/:version` is malformed. |
| `INVALID_PERMISSIONS` | 400 | Body for `PUT /skills/:id/permissions` is malformed. |
| `MISSING_PROMPT` / `MISSING_REPO` / `MISSING_SOURCE` / `MISSING_SPEC` | 400 | Required JSON field absent on the relevant generation / pull endpoint. |
| `invalid_mode` | 400 | `POST /skills/generate` `mode` is not `simple` or `advanced` (§7.1). |
| `AMBIGUOUS_SOURCE` | 400 | `/skills/generate/from-source` got both `code` and `repoUrl`. |
| `EMPTY_SOURCE` | 400 | `/skills/generate/from-source` got an empty `code` after fetching. |
| `REPO_FETCH_FAILED` | 400 | `/skills/generate/from-source` could not fetch the requested GitHub repo. |
| `PULL_FAILED` | 400 | `POST /skills/pull` could not pull or zip the requested repo. |
| `REFRESH_FAILED` | 400 | `POST /skills/:id/refresh` could not re-pull the source. |
| `NO_UPDATE` | 400 | `PUT /skills/:id` body had no actionable fields (no zip, no `isPrivate`). |
| `INVALID_WINDOW` / `INVALID_BUCKET` / `INVALID_RANGE` | 400 | Analytics query params out of range or unparseable. |
| `INVALID_SETTING` | 400 | `PATCH /admin/settings` body has out-of-range values or no recognised fields. |
| `INVALID_NYXID_SERVICE_PATCH` | 400 | `PUT /skills/:id/nyxid-service` body failed Zod validation. |
| `NYXID_SERVICE_NOT_FOUND` | 404 | NyxID catalog service is missing or not visible to caller. Existence is intentionally not leaked. |
| `NYXID_SERVICE_NOT_ELIGIBLE` | 403 | Caller is not allowed to tie a skill to that service (would tie to another user's personal service). |
| `SYSTEM_SKILL_MUST_BE_PUBLIC` | 400 | Skill tied to an admin service cannot be made private. Untie first. |
| `QUERY_REQUIRED` / `AUTH_REQUIRED` | 400 | `/skill-search` invariant violated (semantic mode needs both query and auth). |
| `PAYLOAD_TOO_LARGE` | 413 | Upload exceeds `MAX_PACKAGE_SIZE_BYTES`. |
| `PACKAGE_DOWNLOAD_FAILED` | 500 | The backend could not retrieve the skill ZIP from object storage. |
| `NYXID_ORG_LOOKUP_FAILED` | 500 | NyxID returned a non-OK response when the backend tried to resolve an org on the caller's behalf. |
| `INTERNAL_ERROR` | 500 | Catch-all for unhandled errors; the `X-Request-ID` header lets you correlate with server logs. |

### 1.9 SSE protocol

Endpoints under `/skills/generate*` and `/playground/chat` stream Server-Sent Events instead of returning the JSON envelope.

- `Content-Type: text/event-stream`. The handlers also set `Cache-Control: no-cache`, `Connection: keep-alive`, and `X-Accel-Buffering: no` so that nginx / proxies do not buffer.
- Each event is `data: <JSON>\n\n` (the `data:` payload is a JSON object with a `type` discriminator).
- A heartbeat of `event: keepalive` with empty `data:` is emitted every `SSE_KEEPALIVE_INTERVAL_MS` (default 15 000 ms). Ignore them.
- A normal end-of-stream is signalled by a terminal event (`generation_complete` for generation; `finish` for chat) followed by the proxy closing the connection.
- Aborts: cancelling the underlying HTTP request causes the backend to detect `c.req.raw.signal.aborted`, clear the keepalive timer, and stop the LLM call. Truncated streams have no special closing event.

Per-endpoint event shapes are listed in the relevant sections below.

### 1.10 Pagination

Endpoints that paginate use offset pagination via `page` (1-based) and `pageSize`. Responses carry:

```jsonc
{ "items": [...], "total": <int>, "page": <int>, "pageSize": <int>, "totalPages": <int> }
```

`pageSize` is clamped per-endpoint (search: 1–100 default 9; admin lists: 1–100 default 20; users directory: 1–50 default 10; notifications limit: 1–200 default 50).

### 1.11 Standard headers

| Header | Direction | Purpose |
|---|---|---|
| `Authorization: Bearer <token>` | Inbound | The caller's NyxID access token. Read by the proxy; sometimes forwarded to `ornn-api`. |
| `X-NyxID-Identity-Token` | Inbound (from proxy) | Verified identity JWT; primary input to `proxyAuthSetup`. |
| `X-NyxID-User-Id` / `X-NyxID-User-Email` / `X-NyxID-User-Name` | Inbound (from proxy, headers mode) | Scalar identity fallback when the JWT is absent. |
| `Content-Type: application/zip` (or `application/octet-stream`) | Inbound | Required for binary skill uploads. |
| `Content-Type: application/json` | Inbound | All other writes. |
| `X-Request-ID` | Outbound | Always set; echoes the inbound `X-Request-ID` if present, otherwise generated. Use it when reporting failures. |
| `X-Skill-Deprecated: true` | Outbound (on `GET /skills/:idOrName`) | Set when the resolved version is marked deprecated. |
| `X-Skill-Deprecation-Note: <urlencoded>` | Outbound (on `GET /skills/:idOrName`) | Optional human-readable note when the version is deprecated. |
| `Cache-Control: no-cache`, `Connection: keep-alive`, `X-Accel-Buffering: no` | Outbound (SSE) | Keep proxies from buffering the stream. |

CORS: only the origins listed in `ALLOWED_ORIGINS` are allowed. Cross-origin agents must use the NyxID proxy from a permitted origin or an SDK that signs / forwards through one.

---

## 2. Out-of-band endpoints

These four routes are *not* under `/api/v1/`; they exist for liveness, readiness, and OpenAPI introspection.

### 2.1 `GET /health` / `GET /livez`

**Process liveness probe.** No dependencies are checked.

**Auth: none.**

Response 200:

```jsonc
{
  "status": "ok",
  "service": "ornn-api",
  "version": "1.4.2",
  "timestamp": "2026-04-28T12:34:56.789Z"
}
```

`/health` is an alias retained for backward-compatibility; new K8s manifests should use `/livez`. Errors: none — the route returns 200 unconditionally as long as the process is alive enough to answer.

### 2.2 `GET /readyz`

**Kubernetes readiness probe.** Pings MongoDB with a 2-second timeout.

**Auth: none.**

Response 200 (Mongo reachable):

```jsonc
{ "status": "ready", "service": "ornn-api", "mongoLatencyMs": 12 }
```

Response 503 (Mongo unreachable):

```jsonc
{ "status": "not_ready", "reason": "mongo_unreachable" }
```

When 503, the pod is drained from the K8s service.

### 2.3 `GET /api/v1/openapi.json`

**Returns the auto-generated OpenAPI 3.0 schema** built from the Zod definitions in the route files. Useful for SDK generation and as a typed client target.

**Auth: none.**

Response 200: a complete OpenAPI 3.0 document. Schemas, parameters, request bodies, and responses are all derived from the same Zod schemas the runtime uses for validation, so it never drifts.

---

## 3. Skills CRUD

All endpoints in this section live under `/api/v1/`. The mounting in `bootstrap.ts` runs `proxyAuthSetup` and `nyxidOrgLookupMiddleware` before any handler, so every route has access to the caller's identity and a memoised org-membership getter.

### 3.1 Create skill — `POST /api/v1/skills`

Upload a new skill from a ZIP package.

**Auth: required.** **Permission: `ornn:skill:create`.**

| Where | Field | Type | Notes |
|---|---|---|---|
| Header | `Content-Type` | `application/zip` or `application/octet-stream` | Anything else → 400 `INVALID_CONTENT_TYPE` |
| Query | `skip_validation` | `"true"` | Optional. Skips format validation. Use sparingly. |
| Body | (binary) | ZIP bytes | Must contain a single root folder whose name matches `SKILL.md`'s `name`. |

Response 200:

```jsonc
{
  "data": {
    "guid": "skl_01HXY...",
    "name": "my-skill",
    "description": "...",
    "metadata": { "category": "plain", "tag": ["..."] },
    "tags": ["..."],
    "skillHash": "sha256:...",
    "presignedPackageUrl": "https://storage.../my-skill.zip?X-Amz-Signature=...",
    "isPrivate": true,
    "ownerId": "user_...",
    "createdBy": "user_...",
    "createdByEmail": "...",
    "createdByDisplayName": "...",
    "createdOn": "2026-04-28T12:00:00Z",
    "updatedOn": "2026-04-28T12:00:00Z",
    "sharedWithUsers": [],
    "sharedWithOrgs": [],
    "version": "1.0",
    "isDeprecated": false,
    "deprecationNote": null
  },
  "error": null
}
```

New skills are always created **private** with empty allow-lists. Use `PUT /skills/:id/permissions` to share.

| Code | Status | Cause |
|---|---|---|
| `INVALID_CONTENT_TYPE` | 400 | Wrong Content-Type. |
| `EMPTY_BODY` | 400 | Zero-byte body. |
| `PAYLOAD_TOO_LARGE` | 413 | Exceeds `MAX_PACKAGE_SIZE_BYTES`. |
| `VALIDATION_FAILED` / `FRONTMATTER_VALIDATION_FAILED` | 400 | Skill format check failed. Run `POST /skill-format/validate` for details. |
| `AUTH_MISSING` | 401 | Not authenticated. |
| `FORBIDDEN` | 403 | Missing `ornn:skill:create`. |

### 3.2 Import from GitHub — `POST /api/v1/skills/pull`

Create a new skill by cloning a public GitHub repo. The skill is recorded with a `source` block so it can be refreshed later (§3.3).

**Auth: required.** **Permission: `ornn:skill:create`.**

Request body (`application/json`):

```jsonc
{
  // Preferred — a single folder URL the user copied from the browser
  // address bar; the server parses out repo / ref / path.
  "githubUrl": "https://github.com/owner/repo/tree/main/path/to/skill",

  // Legacy / explicit form. Either provide `githubUrl` OR (`repo` plus
  // optional `ref`/`path`). `githubUrl` wins when both are sent.
  "repo": "owner/name",
  "ref": "main",                 // optional — branch, tag, or commit SHA. Default: repo default branch.
  "path": "skills/my-skill",     // optional — sub-directory inside repo. Default: repo root.

  "skip_validation": false       // optional. Skips the format validator on the pulled ZIP — useful when upstream doesn't strictly conform to Ornn's package layout.
}
```

The accepted `githubUrl` shapes are: `https://github.com/<owner>/<repo>/tree/<ref>/<path...>`, `https://github.com/<owner>/<repo>/tree/<ref>`, and `https://github.com/<owner>/<repo>` (defaults to the repo root). `blob/` URLs (which point at a single file) and non-`github.com` hosts are rejected with `INVALID_GITHUB_URL`.

Response 200: same shape as `POST /skills` — the freshly created `SkillDetail`. The skill's `source.lastSyncedCommit` records the commit SHA pulled at creation time.

| Code | Status | Cause |
|---|---|---|
| `MISSING_SOURCE` | 400 | Neither `githubUrl` nor `repo` was provided. |
| `INVALID_GITHUB_URL` | 400 | `githubUrl` couldn't be parsed (blob URL, non-github host, missing repo, etc.). `message` carries the specific reason. |
| `PULL_FAILED` | 400 | The repo couldn't be cloned, the path was empty, or the package failed to materialise. `message` carries the underlying cause. |
| `VALIDATION_FAILED` | 400 | Pulled package failed format validation (and `skip_validation` was not set). |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 | Same as §3.1. |

### 3.3 Refresh from source — `POST /api/v1/skills/:id/refresh`

Re-pull the skill's recorded GitHub source. Two modes selected by the request body:

- **Apply mode (default).** Pulls, validates (unless `skipValidation` is `true`), and publishes a new version when the bytes differ from the current latest.
- **Dry-run mode (`dryRun: true`).** Pulls, computes a structured diff against the current latest version, and returns the diff without publishing. Drives the "preview-then-confirm" UI flow on the detail-page Advanced Options panel — surface the diff to the user, then call again with `dryRun: false` to commit.

**Auth: required.** **Permission: `ornn:skill:update`.** **Owner OR platform admin** (`ornn:admin:skill`).

Path param: `:id` — skill GUID (not name).

Request body (`application/json`):

```jsonc
{
  "dryRun": false,         // optional. true → diff preview, no version bump. false / omitted → apply.
  "skipValidation": false  // optional (apply mode only). Skips the format validator on the pulled package.
}
```

Response 200 — apply mode: the refreshed `SkillDetail`. `source.lastSyncedCommit` and `source.lastSyncedAt` advance.

Response 200 — dry-run mode:

```jsonc
{
  "data": {
    "skill":           { "guid": "…", "name": "…" },
    "source":          { /* SkillSource, with lastSyncedCommit set to the commit that WOULD be pulled */ },
    "pendingVersion":  "1.3",            // version the SKILL.md frontmatter inside the pulled bytes declares
    "hasChanges":      true,             // false → upstream is byte-identical to current latest; nothing to bump
    "diff":            { /* same shape as §3.7 — { files: { added, removed, modified, unchangedCount } } */ }
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No skill with that GUID. |
| `NOT_SKILL_OWNER` | 403 | Caller is not the author and lacks `ornn:admin:skill`. |
| `NO_SOURCE` | 400 | Skill has no linked GitHub source. Attach one via §3.15 first. |
| `REFRESH_FAILED` | 400 | Source repo could not be re-fetched, or the resulting package failed validation (apply mode). |
| `REFRESH_PREVIEW_FAILED` | 400 | Dry-run pull failed (e.g. upstream folder removed). |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 | Standard. |

### 3.4 Get skill — `GET /api/v1/skills/:idOrName`

Fetch a single skill by GUID or by `name`.

**Auth: optional.** Anonymous callers see only public skills (private skills return 404 `SKILL_NOT_FOUND`).

Path param: `:idOrName` — skill GUID or kebab-case name.

| Query param | Type | Notes |
|---|---|---|
| `version` | `<major>.<minor>` | Optional. Returns the metadata + `presignedPackageUrl` for a specific version. Without it, returns the latest. |

Response 200: `SkillDetail` (same shape as §3.1's response). When the resolved version is deprecated, additional response headers:

- `X-Skill-Deprecated: true`
- `X-Skill-Deprecation-Note: <URL-encoded note>` (when set)

The endpoint records a `web` pull event for authenticated callers (no event for anonymous reads).

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No skill, hidden by visibility, or version not present. |

### 3.5 Get skill JSON — `GET /api/v1/skills/:idOrName/json`

Return the full skill package as inline JSON: every file path in the package mapped to its UTF-8 content. This is the canonical agent-side pull — it avoids the second hop to object storage.

**Auth: required.** **Permission: `ornn:skill:read`.**

Path param: `:idOrName`.

Response 200:

```jsonc
{
  "data": {
    "name": "my-skill",
    "description": "...",
    "metadata": { "category": "plain", "tag": ["..."] },
    "files": {
      "SKILL.md": "---\nname: my-skill\n...",
      "scripts/run.py": "import sys\n...",
      "references/usage.md": "..."
    }
  },
  "error": null
}
```

The endpoint records an `api` pull event when called by an authenticated caller.

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `PACKAGE_DOWNLOAD_FAILED` | 500 | Backend could not fetch the package from object storage. Retry with backoff. |
| `AUTH_MISSING` | 401 | Not authenticated. |
| `FORBIDDEN` | 403 | Missing `ornn:skill:read`. |

### 3.6 List versions — `GET /api/v1/skills/:idOrName/versions`

List every published version of the skill, newest first.

**Auth: optional.** Visibility rules mirror §3.4 — anonymous callers get 404 on private skills.

Path param: `:idOrName`.

Response 200:

```jsonc
{
  "data": {
    "items": [
      {
        "version": "1.3",
        "skillHash": "sha256:...",
        "createdBy": "user_...",
        "createdByEmail": "...",
        "createdByDisplayName": "...",
        "createdOn": "2026-04-28T12:00:00Z",
        "isDeprecated": false,
        "deprecationNote": null,
        "releaseNotes": "Switched parser to csv-parse"
      },
      { /* v1.2 ... */ }
    ]
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Same as §3.4. |

### 3.7 Diff versions — `GET /api/v1/skills/:idOrName/versions/:fromVersion/diff/:toVersion`

Structured file-level diff between two versions of the same skill.

**Auth: optional.** Visibility same as §3.4.

Path params:

- `:idOrName` — skill GUID or name.
- `:fromVersion` / `:toVersion` — version strings (`<major>.<minor>`).

Response 200:

```jsonc
{
  "data": {
    "skill": { "guid": "skl_...", "name": "my-skill" },
    "from": {
      "version": "1.2",
      "hash": "sha256:...",
      "createdOn": "2026-04-20T...",
      "isDeprecated": true,
      "releaseNotes": null
    },
    "to": {
      "version": "1.3",
      "hash": "sha256:...",
      "createdOn": "2026-04-27T...",
      "isDeprecated": false,
      "releaseNotes": "Switched parser to csv-parse"
    },
    "diff": {
      "added":   [{ "path": "references/why-csv-parse.md", "content": "..." }],
      "removed": [{ "path": "scripts/papaparse-helper.js", "content": "..." }],
      "modified": [
        { "path": "scripts/run.py", "before": "...", "after": "..." }
      ]
    }
  },
  "error": null
}
```

Content of modified files is included on both sides so a unified diff can be rendered client-side.

| Code | Status | Cause |
|---|---|---|
| `SAME_VERSION` | 400 | `from` and `to` are equal. |
| `SKILL_NOT_FOUND` | 404 | Skill missing or hidden. |
| `SKILL_VERSION_NOT_FOUND` | 404 | Either version is not present on the skill. |

### 3.8 Toggle version deprecation — `PATCH /api/v1/skills/:idOrName/versions/:version`

Mark a single version as deprecated or undo it. Deprecation is a warning, not a removal — the version remains resolvable.

**Auth: required.** **Permission: `ornn:skill:update`.** **Author OR platform admin.**

Path params: `:idOrName`, `:version` (`<major>.<minor>`).

Request body (`application/json`):

```jsonc
{ "isDeprecated": true, "deprecationNote": "Breaks with axios >= 1.7" }
```

`deprecationNote` is optional (max 1024 chars). Schema: Zod `z.object({ isDeprecated: z.boolean(), deprecationNote: z.string().max(1024).optional() })`.

Response 200:

```jsonc
{
  "data": {
    "skillGuid": "skl_...",
    "skillName": "my-skill",
    "version": "1.2",
    "isDeprecated": true,
    "deprecationNote": "Breaks with axios >= 1.7"
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `INVALID_DEPRECATION_PATCH` | 400 | Body failed Zod validation. |
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `SKILL_VERSION_NOT_FOUND` | 404 | Version not present. |
| `FORBIDDEN` | 403 | Caller is not the author / not platform admin. |
| `AUTH_MISSING` | 401 / `FORBIDDEN` 403 | Standard. |

### 3.9 Update skill — `PUT /api/v1/skills/:id`

Publish a new version (ZIP body) and / or flip the `isPrivate` flag (JSON body or multipart form).

**Auth: required.** **Permission: `ornn:skill:update`.** **Author OR platform admin.**

Path param: `:id` — GUID only (not name).

| Where | Field | Notes |
|---|---|---|
| Query | `skip_validation` | Optional `"true"`. |
| Header | `Content-Type` | One of `application/zip`, `application/octet-stream`, `multipart/form-data`, `application/json`. |
| Body (zip) | (binary) | New version ZIP. |
| Body (multipart) | `package` (file) | New version ZIP. Optional. |
| Body (multipart) | `isPrivate` | `"true"` or `"false"`. Optional. |
| Body (JSON) | `{ "isPrivate": <bool> }` | Visibility-only update. |

Response 200: refreshed `SkillDetail`. When the body contained a ZIP, a new `latestVersion` is published and the `version_*` records are advanced.

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `FORBIDDEN` | 403 | Caller is not the author / not platform admin. |
| `NO_UPDATE` | 400 | Neither a ZIP nor `isPrivate` was provided. |
| `PAYLOAD_TOO_LARGE` | 413 | Exceeds `MAX_PACKAGE_SIZE_BYTES`. |
| `VALIDATION_FAILED` / `FRONTMATTER_VALIDATION_FAILED` | 400 | New package failed validation. |
| `AUTH_MISSING` | 401 | Standard. |

### 3.10 Replace permissions — `PUT /api/v1/skills/:id/permissions`

Apply a new ACL state in one shot. **This is the only "share" endpoint.** There is no audit gate, no waiver, no review queue — the backend stores the desired state as-is. (Earlier designs proxied through `share_requests` with a waiver flow; that was removed in PR #198.)

**Auth: required.** **Permission: `ornn:skill:update`.** **Author OR platform admin.**

Path param: `:id` — skill GUID.

Request body (`application/json`):

```jsonc
{
  "isPrivate": true,
  "sharedWithUsers": ["user_abc", "user_def"],
  "sharedWithOrgs": ["org_xyz"]
}
```

Schema: Zod
```ts
z.object({
  isPrivate: z.boolean(),
  sharedWithUsers: z.array(z.string().min(1).max(128)).max(500).default([]),
  sharedWithOrgs:  z.array(z.string().min(1).max(128)).max(100).default([]),
})
```

`isPrivate: false` makes the skill fully public; the allow-lists are still persisted (so toggling back to private doesn't lose your collaborator list) but visibility ignores them while the skill is public.

Response 200:

```jsonc
{ "data": { "skill": <SkillDetail> }, "error": null }
```

The response shape is `{ skill }` — not `{ skill, waivers }`. There is no `waivers` array; the field has been removed from the contract.

| Code | Status | Cause |
|---|---|---|
| `INVALID_PERMISSIONS` | 400 | Body failed Zod validation (e.g. `sharedWithUsers.length > 500`). |
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `FORBIDDEN` | 403 | Caller is not the author / not platform admin. |
| `AUTH_MISSING` | 401 | Standard. |

### 3.11 Delete skill — `DELETE /api/v1/skills/:id`

Hard-delete the skill, all its versions, and all its storage objects.

**Auth: required.** **Permission: `ornn:skill:delete`.** **Author OR platform admin.**

Path param: `:id` — GUID only.

Response 200:

```jsonc
{ "data": { "success": true }, "error": null }
```

There is no soft-delete; subsequent reads return `SKILL_NOT_FOUND`. Audit records, analytics events, and notifications already emitted are *not* purged — they remain queryable as historical orphans.

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `FORBIDDEN` | 403 | Caller is not the author / not platform admin. |
| `AUTH_MISSING` | 401 | Standard. |

### 3.12 Tie / untie NyxID service — `PUT /api/v1/skills/:id/nyxid-service`

Set or clear the skill's tie to a NyxID catalog service.

**Auth: required.** **Permission: `ornn:skill:update`.** **Author OR platform admin.**

Path param: `:id` — skill GUID.

Request body (`application/json`):

```jsonc
{ "nyxidServiceId": "svc_abc..." }   // tie
{ "nyxidServiceId": null }           // untie
```

Eligibility:

| Caller | Service tier | Allowed? |
|---|---|---|
| Anyone (author/admin of the skill) | **admin** (`visibility: "public"`) | yes |
| Anyone (author/admin of the skill) | **personal** AND `created_by === caller` | yes |
| Anyone | **personal** AND `created_by !== caller` | **no** — `NYXID_SERVICE_NOT_ELIGIBLE` |

Side effect: tying to an admin service forces `isPrivate: false` atomically (system skills are always public). Tying to a personal service does **not** change privacy. Untying does not change privacy.

Response 200:

```jsonc
{
  "data": {
    "skill": {
      "guid": "skl_...",
      "name": "...",
      "isPrivate": false,
      "nyxidServiceId": "svc_abc...",
      "nyxidServiceSlug": "ornn-api",
      "nyxidServiceLabel": "Ornn API",
      "isSystemSkill": true,
      // ...rest of SkillDetail
    }
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `INVALID_NYXID_SERVICE_PATCH` | 400 | Body failed Zod validation. |
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `NYXID_SERVICE_NOT_FOUND` | 404 | Service id is missing or not visible to caller. |
| `NYXID_SERVICE_NOT_ELIGIBLE` | 403 | Tying to another user's personal service. |
| `FORBIDDEN` | 403 | Caller is not author / not platform admin. |

### 3.13 List skills tied to a service — `GET /api/v1/nyxid-services/:serviceId/skills`

Reverse lookup: every skill tied to a given catalog service.

**Auth: required.**

Authorization:

| Service tier | Who can browse |
|---|---|
| **admin** (`visibility: "public"`) | any authenticated caller |
| **personal** (`visibility: "private"`) | the service `created_by`, or platform admin (`ornn:admin:skill`) |

Service ids the caller cannot see (private + not owner / admin) collapse to 404 to avoid leaking existence.

| Query param | Notes |
|---|---|
| `page` | int ≥ 1, default 1 |
| `pageSize` | int 1–100, default 20 |

Response 200:

```jsonc
{
  "data": {
    "service": {
      "id": "svc_abc...",
      "slug": "ornn-api",
      "label": "Ornn API",
      "tier": "admin"
    },
    "items": [
      {
        "guid": "skl_...",
        "name": "...",
        "description": "...",
        "ownerId": "user_...",
        "createdBy": "user_...",
        "createdByEmail": "...",
        "createdByDisplayName": "...",
        "createdOn": "...",
        "updatedOn": "...",
        "isPrivate": false,
        "tags": ["..."],
        "nyxidServiceId": "svc_abc...",
        "nyxidServiceSlug": "ornn-api",
        "nyxidServiceLabel": "Ornn API",
        "isSystemSkill": true
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `NYXID_SERVICE_NOT_FOUND` | 404 | Service missing, hidden, or caller is a non-owner / non-admin of a personal service. |

### 3.14 Delete a single version — `DELETE /api/v1/skills/:idOrName/versions/:version`

Remove one non-latest, non-only version of a skill. The skill itself + every other version remain.

**Auth: required.** **Permission: `ornn:skill:delete`.** **Author OR platform admin.**

Path params: `:idOrName`, `:version`.

Response 200: `{ "data": { "success": true }, "error": null }`.

Refused for two cases:
- The version is the **only** version of the skill — use `DELETE /skills/:id` to remove the skill entirely.
- The version is the **current latest** — publish a newer version first (or de-publish via a different mechanism), then delete the older one.

Both refusals surface as a 400 with a descriptive code (`CANNOT_DELETE_LATEST`, `CANNOT_DELETE_ONLY_VERSION`, or similar — defined inside `skillService.deleteVersion` / `skillVersionRepo`).

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No such skill. |
| `SKILL_VERSION_NOT_FOUND` | 404 | Version not present. |
| `CANNOT_DELETE_LATEST` | 400 | Caller targeted the current `latestVersion`. |
| `CANNOT_DELETE_ONLY_VERSION` | 400 | Skill has only one version. |
| `FORBIDDEN` | 403 | Caller is not the author / not platform admin. |
| `AUTH_MISSING` | 401 | Standard. |

### 3.15 Set / clear GitHub source — `PUT /api/v1/skills/:id/source`

Attach (or clear) a GitHub source pointer on an existing skill **without pulling**. Lets a user link an originally hand-uploaded skill to its GitHub source first and trigger the actual sync separately via §3.3 (typically dry-run → confirm → apply). Pass `null` to unlink.

**Auth: required.** **Permission: `ornn:skill:update`.** **Owner OR platform admin** (`ornn:admin:skill`).

Path param: `:id` — skill GUID (not name).

Request body (`application/json`):

```jsonc
{
  // Folder URL on github.com. Same shapes accepted by §3.2's `githubUrl`:
  // /tree/<ref>/<path>, /tree/<ref>, or bare repo URL.
  // Pass `null` to remove the existing source pointer.
  "githubUrl": "https://github.com/owner/repo/tree/main/path/to/skill"
}
```

Response 200: the updated `SkillDetail`. The stored `source` block omits `lastSyncedAt` / `lastSyncedCommit` until the first sync (apply-mode refresh) — that's the documented "linked but never synced" state.

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | No skill with that GUID. |
| `NOT_SKILL_OWNER` | 403 | Caller is not the author and lacks `ornn:admin:skill`. |
| `INVALID_BODY` | 400 | `githubUrl` is missing or not `string \| null`. |
| `INVALID_GITHUB_URL` | 400 | URL couldn't be parsed (blob URL, non-github host, missing repo, etc.). |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 | Standard. |

---

## 4. Skill audit

Five endpoints. Audit is a **passive risk label** — running an audit produces a verdict that decorates the skill (and fans out a notification on yellow / red), but never blocks any operation. Sharing is decoupled from audit (§3.10).

Audit verdicts: `green`, `yellow`, `red`. Lifecycle: `running` → `completed` (or `failed`). Cache: a `completed` row younger than 30 days for the same `(skillGuid, version, skillHash)` is reused unless `force: true` is passed.

### 4.1 Get latest audit — `GET /api/v1/skills/:idOrName/audit`

Return the most recent audit record for the latest (or specified) version. Does **not** trigger a new audit.

**Auth: optional.** Visibility mirrors §3.4.

Path param: `:idOrName`. Query: `version` (optional `<major>.<minor>`).

Response 200:

```jsonc
{
  "data": {
    "_id": "aud_...",
    "skillGuid": "skl_...",
    "version": "1.3",
    "skillHash": "sha256:...",
    "status": "completed",
    "verdict": "yellow",
    "overallScore": 6.4,
    "scores": [
      { "dimension": "security", "score": 5, "rationale": "Reads env vars without scoping" },
      { "dimension": "code_quality", "score": 7, "rationale": "..." },
      { "dimension": "documentation", "score": 7, "rationale": "..." },
      { "dimension": "reliability", "score": 6, "rationale": "..." },
      { "dimension": "permission_scope", "score": 7, "rationale": "..." }
    ],
    "findings": [
      { "dimension": "security", "severity": "warning", "file": "scripts/run.py", "line": 12, "message": "..." }
    ],
    "model": "claude-3.5-sonnet",
    "createdAt": "2026-04-28T12:00:00Z",
    "completedAt": "2026-04-28T12:01:30Z",
    "triggeredBy": "user_..."
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Skill missing / hidden / version not present. |
| `AUDIT_NOT_FOUND` | 404 | Skill exists but has never been audited at the resolved version. |

### 4.2 Per-version audit summary — `GET /api/v1/skills/:idOrName/audit/summary-by-version`

For each version of the skill, return the most recent **completed** audit. Versions with no completed audit are omitted (callers treat the missing key as "not audited yet"). Drives the per-version verdict badges in the UI.

**Auth: optional.** Visibility mirrors §3.4.

Response 200:

```jsonc
{
  "data": {
    "byVersion": {
      "1.3": { "verdict": "yellow", "overallScore": 6.4, "completedAt": "2026-04-28T..." },
      "1.2": { "verdict": "green",  "overallScore": 8.1, "completedAt": "2026-04-21T..." }
    }
  },
  "error": null
}
```

(`running` rows do not surface here; they only appear in `/audit/history`.)

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Skill missing / hidden. |

### 4.3 Audit history — `GET /api/v1/skills/:idOrName/audit/history`

List every audit row stored for the skill (newest first), including `running` and `failed` rows. Use this for polling after a trigger.

**Auth: optional.** Visibility mirrors §3.4.

Path param: `:idOrName`. Query: `version` (optional — narrows to one version).

Response 200:

```jsonc
{
  "data": {
    "items": [
      { "_id": "aud_...", "version": "1.3", "status": "running",   "createdAt": "..." },
      { "_id": "aud_...", "version": "1.3", "status": "completed", "verdict": "yellow", "overallScore": 6.4, "completedAt": "..." },
      { "_id": "aud_...", "version": "1.2", "status": "failed",    "errorMessage": "LLM timeout", "createdAt": "..." }
    ]
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Skill missing / hidden. |

### 4.4 Trigger audit — `POST /api/v1/skills/:idOrName/audit`

Owner-side "Start Auditing". Inserts a `running` row immediately and kicks off the LLM pipeline in the background. Returns the `running` row.

**Auth: required.** Caller must be **the skill's author OR a platform admin** (`ornn:admin:skill`). No scalar permission gate — this is an ownership check.

Path param: `:idOrName`.

Request body (optional, `application/json`):

```jsonc
{ "force": false }
```

`force: true` bypasses the 30-day cache (always inserts a new row + runs the pipeline). `force: false` (default) reuses a recent `completed` row when one exists for the same `skillHash`.

Response 200:

```jsonc
{ "data": <AuditRecord at status: "running" or reused completed row>, "error": null }
```

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Skill missing / hidden. |
| `NOT_SKILL_OWNER` | 403 | Caller is neither the author nor a platform admin. |
| `AUTH_MISSING` | 401 | Standard. |

### 4.5 Admin force-trigger — `POST /api/v1/admin/skills/:idOrName/audit`

Same as §4.4 but bypasses the ownership check entirely. For platform admins running an audit on a skill they did not author.

**Auth: required.** **Permission: `ornn:admin:skill`.**

Body / response: identical to §4.4.

| Code | Status | Cause |
|---|---|---|
| `SKILL_NOT_FOUND` | 404 | Skill missing. |
| `FORBIDDEN` | 403 | Missing `ornn:admin:skill`. |
| `AUTH_MISSING` | 401 | Standard. |

---

## 5. Skill search

Two endpoints — registry-wide search and the registry-tab counts.

### 5.1 Search — `GET /api/v1/skill-search`

Keyword or semantic search across the skills the caller can see.

**Auth: optional.** Anonymous callers are forced to `scope = public` and cannot use semantic mode (returns 400).

| Query param | Type | Default | Notes |
|---|---|---|---|
| `query` | string ≤ 2000 | `""` | Empty = match all (within scope). |
| `mode` | `keyword` \| `semantic` | `keyword` | Semantic uses LLM ranking; requires auth and a non-empty query. |
| `scope` | `public` \| `private` \| `mixed` \| `shared-with-me` \| `mine` | `private` | Auth scopes. Anonymous callers are coerced to `public`. |
| `page` | int ≥ 1 | 1 | 1-based. |
| `pageSize` | int 1–100 | 9 | |
| `model` | string | platform default | LLM id override (semantic only). |
| `systemFilter` | `any` \| `only` \| `exclude` | `any` | "System skills" are skills tied to an admin/platform NyxID service (`isSystemSkill: true`, set by `PUT /skills/:id/nyxid-service`). `only` keeps just system skills; `exclude` removes them. |
| `sharedWithOrgs` | comma-separated org user_ids | — | Narrow by grant target. |
| `sharedWithUsers` | comma-separated user_ids | — | Narrow by grant target. |
| `createdByAny` | comma-separated user_ids | — | Narrow by author. |

Response 200:

```jsonc
{
  "data": {
    "searchMode": "keyword",
    "searchScope": "public",
    "total": 42,
    "totalPages": 5,
    "page": 1,
    "pageSize": 9,
    "items": [
      {
        "guid": "skl_...",
        "name": "my-skill",
        "description": "...",
        "ownerId": "user_...",
        "createdBy": "user_...",
        "createdByEmail": "...",
        "createdByDisplayName": "...",
        "createdOn": "...",
        "updatedOn": "...",
        "isPrivate": false,
        "tags": ["..."],
        "myAccessReason": "public",
        "isSystemForMe": true,
        "systemForService": { "id": "...", "slug": "...", "label": "..." },
        "permissionSummary": { "isPrivate": false, "sharedUserCount": 0, "sharedOrgCount": 0 }
      }
    ]
  },
  "error": null
}
```

`myAccessReason` is one of `owner`, `public`, `shared-direct`, `shared-via-org` and only present for authenticated callers. `sharedViaOrgId` accompanies `shared-via-org`.

| Code | Status | Cause |
|---|---|---|
| `INVALID_QUERY` | 400 | Query string failed Zod validation. |
| `QUERY_REQUIRED` | 400 | `mode=semantic` with empty `query`. |
| `AUTH_REQUIRED` | 400 | `mode=semantic` from an anonymous caller. |

### 5.2 Tag facets — `GET /api/v1/skill-facets/tags`

Distinct skill tags within a given scope, with per-tag counts. Drives sidebar tag filters.

**Auth: optional** for `public` / `system` / `mixed`; **required** for `mine` / `shared-with-me`.

| Query param | Values |
|---|---|
| `scope` | `public` \| `mine` \| `shared-with-me` \| `system` \| `mixed` (default `public`) |

Response 200:

```jsonc
{
  "data": {
    "items": [
      { "name": "translation", "count": 12 },
      { "name": "csv",         "count": 8 }
    ]
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `INVALID_SCOPE` | 400 | Scope value not in the enum. |
| `AUTH_REQUIRED` | 401 | `mine` / `shared-with-me` requested anonymously. |

### 5.3 Author facets — `GET /api/v1/skill-facets/authors`

Distinct skill authors within scope, with per-author counts. Drives the Public-tab author filter.

**Auth: optional** for `public` / `system` / `mixed`; **required** for `shared-with-me`.

| Query param | Values |
|---|---|
| `scope` | `public` \| `shared-with-me` \| `system` \| `mixed` (default `public`) |

Response 200:

```jsonc
{
  "data": {
    "items": [
      { "userId": "user_...", "email": "alice@…", "displayName": "Alice", "count": 5 }
    ]
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `INVALID_SCOPE` | 400 | Scope unsupported (e.g. `mine` — every skill there has the same author). |
| `AUTH_REQUIRED` | 401 | `shared-with-me` requested anonymously. |

### 5.4 System-service facets — `GET /api/v1/skill-facets/system-services`

NyxID services that have at least one tied system skill, with per-service skill counts. Powers the System-tab service filter.

**Auth: optional.**

Response 200:

```jsonc
{
  "data": {
    "items": [
      { "id": "svc_...", "slug": "ornn-api", "label": "Ornn API", "count": 1 }
    ]
  },
  "error": null
}
```

### 5.5 Registry counts — `GET /api/v1/skill-counts`

Single round-trip for the three registry-tab badges.

**Auth: optional.** Anonymous callers always see `mine: 0`, `sharedWithMe: 0`.

Response 200:

```jsonc
{
  "data": {
    "public": 124,
    "mine": 7,
    "sharedWithMe": 12
  },
  "error": null
}
```

The path is intentionally outside `/skills/` so it does not collide with `GET /skills/:id`. No errors specific to this endpoint.

---

## 6. Skill format

Two endpoints — the canonical format spec, and a pre-flight validator.

### 6.1 Format rules — `GET /api/v1/skill-format/rules`

Return the canonical skill package format spec as Markdown.

**Auth: none.**

Response 200:

```jsonc
{ "data": { "rules": "# Ornn Skill Package Format Rules\n\n..." }, "error": null }
```

Use this as the source-of-truth — it is exactly what the validator (§6.2) and the upload path enforce.

### 6.2 Validate ZIP — `POST /api/v1/skill-format/validate`

Validate a ZIP against the format rules without uploading.

**Auth: required.** **Permission: `ornn:skill:read`.**

Headers: `Content-Type: application/zip` (or `application/octet-stream`).

Body: ZIP bytes.

Response 200 — valid:

```jsonc
{ "data": { "valid": true }, "error": null }
```

Response 200 — invalid (note: HTTP is still 200; the envelope's `data.valid: false` is the signal):

```jsonc
{
  "data": {
    "valid": false,
    "violations": [
      { "rule": "VALIDATION_FAILED", "message": "SKILL.md missing 'metadata.category' field" }
    ]
  },
  "error": null
}
```

Validation is idempotent and side-effect-free; safe to call repeatedly in CI.

| Code | Status | Cause |
|---|---|---|
| `INVALID_CONTENT_TYPE` | 400 | Wrong Content-Type. |
| `EMPTY_BODY` | 400 | Zero-byte body. |
| `AUTH_MISSING` | 401 / `FORBIDDEN` 403 | Standard. |

---

## 7. Skill generation (SSE)

Three endpoints, all SSE. All require `ornn:skill:build`. All emit the same event family (§7.0).

### 7.0 Generation event shapes

```jsonc
// generation_start
{ "type": "generation_start" }

// token (incremental content)
{ "type": "token", "content": "partial output text" }

// generation_complete (terminal — full result)
{ "type": "generation_complete", "raw": "<generated skill as a JSON document string — see below>" }

// validation_error (auto-retry; pipeline keeps streaming)
{ "type": "validation_error", "message": "...", "retrying": true }

// error (terminal — fatal)
{ "type": "error", "message": "..." }

// keepalive (heartbeat — ignore)
{ "type": "keepalive" }
```

A normal stream ends with `generation_complete` followed by the proxy closing the connection. A fatal stream ends with `error`.

`raw` is a JSON **document string** (not a ZIP, not markdown). Parse it to get:

```jsonc
{
  "name": "kebab-case-name",
  "description": "...",
  "category": "plain" | "runtime-based",
  "outputType": "text" | "file",          // runtime-based only
  "tags": ["..."],
  "readmeBody": "<markdown body — build SKILL.md as frontmatter + this>",
  "runtimes": ["node"] | ["python"] | [],
  "dependencies": ["..."],
  "envVars": ["..."],
  "scripts":    [{ "filename": "main.js",   "content": "..." }],   // → scripts/
  "references": [{ "filename": "notes.md",  "content": "..." }],   // → references/
  "assets":     [{ "filename": "data.csv",  "content": "..." }]    // → assets/ (text only)
}
```

`raw` is the model's verbatim answer, so the model may omit any of the three file arrays (and the runtime arrays) — treat a missing array as empty. Nothing is persisted — assemble the package yourself and publish it with `POST /api/v1/skills` (§3.1). **In `simple` mode (§7.1) the server guarantees `category` is `plain`, there is no `outputType`, and each of `scripts` / `references` / `assets` / `runtimes` / `dependencies` / `envVars` is empty or absent** — an answer that violates that never reaches `generation_complete`.

### 7.1 Generate from prompt — `POST /api/v1/skills/generate`

Generate a fresh skill from a natural-language prompt. Two body shapes: single-shot and multi-turn. Both accept the same two optional fields:

| Field | Values | Default | Meaning |
|---|---|---|---|
| `mode` | `"simple"` \| `"advanced"` | `"advanced"` | Package shape. `advanced` = the model may emit `scripts[]`, `references[]`, `assets[]` (and pick `runtime-based`). `simple` = one `SKILL.md`, nothing else — the model is told to keep everything inline and the server **rejects** any answer that carries files, an `outputType` or a non-plain category (one corrective retry, then `error`). Omitted, `null` or `""` → the default; anything else → 400 `invalid_mode` before the quota reserve. |
| `modelId` | id from `GET /api/v1/me/models?surface=skillGen` (§11) | surface default | Admin-curated model to use. |

**Auth: required.** **Permission: `ornn:skill:build`.**

#### 7.1.a Single-shot (JSON or multipart)

```jsonc
// JSON
{
  "prompt": "Build a skill that converts CSV to JSON using csv-parse",
  "mode": "simple",              // optional — omit for "advanced"
  "modelId": "gpt-4.1-mini"      // optional
}
```

```text
# multipart/form-data
prompt=Build a skill that converts CSV to JSON ...
mode=simple                      # optional — plain form field, same semantics as JSON
modelId=gpt-4.1-mini             # optional
package=@existing-skill.zip      # optional — iterate on an existing package
```

When `package` is included, its file contents are extracted (SKILL.md + scripts/ + references/ + assets/) and included in the prompt as "existing skill content" — even in `simple` mode, where the existing `scripts/` are read as context but the answer must still be `SKILL.md`-only.

#### 7.1.b Multi-turn (JSON only)

```jsonc
{
  "messages": [
    { "role": "user",      "content": "Build a CSV-to-JSON skill" },
    { "role": "assistant", "content": "<previous generation output>" },
    { "role": "user",      "content": "Switch to csv-parse from papaparse" }
  ],
  "mode": "advanced"             // optional — applies to THIS turn; you may switch between turns
}
```

Same SSE event types, but the model has the prior turns as conversational context.

Retry behaviour differs between the two shapes. Single-shot re-asks the model once for **any** rejected first answer (not JSON, schema-invalid, or a `simple`-mode violation) — you see `validation_error` with `retrying: true` and the run may end on `error` with no `generation_complete`. Multi-turn does **not** retry a merely non-JSON answer (a refinement turn may legitimately be prose): it emits `validation_error` with `retrying: false` and still delivers that text in `generation_complete`, so re-validate `raw` before trusting it. The one multi-turn exception is a `simple`-mode violation, which gets the same single corrective retry and ends on `error` unless the retry is a valid, file-free skill.

Response: SSE stream as in §7.0. No JSON envelope.

| Code (in stream) | Cause |
|---|---|
| `MISSING_PROMPT` | Neither `prompt` nor `messages` present. |
| `invalid_mode` | `mode` is not `simple` or `advanced` (400 before the stream and before any quota reserve). |
| `INVALID_CONTENT_TYPE` | Wrong Content-Type — must be `application/json` or `multipart/form-data`. |
| `AUTH_MISSING` | 401 returned **before** the stream starts. |
| `FORBIDDEN` | 403 returned before the stream starts (missing `ornn:skill:build`). |

### 7.2 Generate from source — `POST /api/v1/skills/generate/from-source`

Generate a skill by analysing existing source code — either an inline snippet or a public GitHub repo. The prompt asks for a `plain`, file-free skill (the same shape `simple` mode produces), but this path does **not** enforce it server-side the way `simple` does — validate `raw` before publishing. There is no `mode` field here; one sent in the body is ignored, not rejected.

**Auth: required.** **Permission: `ornn:skill:build`.**

Body (`application/json`):

```jsonc
{
  "code":       "<inline source>",                 // EITHER this …
  "repoUrl":    "https://github.com/owner/repo",   // … OR this. Exactly one is required.
  "path":       "src/utils/summarizer.ts",         // optional — narrow inside repo
  "framework":  "express",                         // optional hint; auto-detected otherwise
  "description":"Wrap the summarize() function as a skill"
}
```

Response: SSE stream (§7.0).

| Code | Status / event | Cause |
|---|---|---|
| `MISSING_SOURCE` | 400 (pre-stream) | Neither `code` nor `repoUrl` provided. |
| `AMBIGUOUS_SOURCE` | 400 (pre-stream) | Both `code` and `repoUrl` provided. |
| `EMPTY_SOURCE` | 400 (pre-stream) | After fetching, source is empty. |
| `REPO_FETCH_FAILED` | 400 (pre-stream) | GitHub fetch failed. |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 (pre-stream) | Standard. |

### 7.3 Generate from OpenAPI — `POST /api/v1/skills/generate/from-openapi`

Generate a skill that wraps one or more endpoints from an OpenAPI 3 spec. Like §7.2 the prompt asks for a `plain`, file-free skill but the server does not enforce it here — validate `raw`; there is no `mode` field (ignored if sent).

**Auth: required.** **Permission: `ornn:skill:build`.**

Body (`application/json`):

```jsonc
{
  "spec":      "<OpenAPI YAML or JSON as a string>",  // required
  "endpoints": ["POST /v1/summary", "GET /v1/items"], // optional allow-list
  "description": "Wrap the summary endpoint as a skill"
}
```

Without `endpoints`, the generator covers every operation in the spec.

Response: SSE stream (§7.0).

| Code | Status / event | Cause |
|---|---|---|
| `MISSING_SPEC` | 400 (pre-stream) | `spec` missing or empty. |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 | Standard. |

---

## 8. Playground (SSE)

One endpoint. Server-side tool-use loop with sandbox execution.

### 8.0 Playground event shapes

```jsonc
{ "type": "text-delta",  "delta": "Sure, here is the result …" }

{ "type": "tool-call",   "toolCall": { "id": "tc_1", "name": "execute_script", "args": { "language": "python", "code": "..." } } }

{ "type": "tool-result", "toolCallId": "tc_1", "result": "stdout output" }

{ "type": "file-output", "file":   { "path": "out.csv", "content": "...", "size": 1024, "mimeType": "text/csv" } }

{ "type": "error",       "message": "..." }                          // fatal
{ "type": "finish",      "finishReason": "stop" }                    // terminal — normal end
{ "type": "keepalive" }                                              // ignore
```

Standard chat ends with `finish`. `tool-call` / `tool-result` pairs appear only for runtime-based skills (or when the LLM explicitly invokes `skill_search`).

### 8.1 Chat — `POST /api/v1/playground/chat`

**Auth: required.** **Permission: `ornn:playground:use`.**

Request body (`application/json`):

```jsonc
{
  "messages": [                            // 1–100 messages, validated by Zod
    {
      "role": "user",                      // "user" | "assistant" | "tool" | "system"
      "content": "Translate: Hello",
      "toolCalls":  [/* optional */],
      "toolCallId": "tc_..."               // optional — for "tool" role
    }
  ],
  "skillId": "<guid or kebab-case name>",  // optional — without it, "blank" agent
  "envVars": { "OPENAI_API_KEY": "..." }   // optional — injected into sandbox for runtime skills
}
```

Schema:

```ts
z.object({
  messages: z.array(z.object({
    role: z.enum(["user", "assistant", "tool", "system"]),
    content: z.string(),
    toolCalls: z.array(z.object({
      id: z.string(),
      name: z.string(),
      args: z.record(z.unknown()),
    })).optional(),
    toolCallId: z.string().optional(),
  })).min(1).max(100),
  skillId: z.string().optional(),
  envVars: z.record(z.string()).optional(),
})
```

Response: SSE stream (§8.0). When `skillId` resolves to a real skill, a `playground` pull event is recorded for analytics (fire-and-forget; failures never surface).

The backend runs up to 5 rounds of tool-use; when the LLM emits a `function_call` to `execute_script` or `skill_search`, the backend executes it (no client approval), feeds the result back as a `tool` message, and continues streaming.

| Code | Status / event | Cause |
|---|---|---|
| `VALIDATION_ERROR` | 400 (pre-stream) | Body failed Zod validation. |
| `AUTH_MISSING` / `FORBIDDEN` | 401 / 403 (pre-stream) | Standard. |
| `error` | terminal stream event | Chat error during the LLM / sandbox loop. |

---

## 9. Notifications

Four endpoints. All require auth. All scoped to the caller — no cross-user reads.

Two notification categories are emitted today; both come from the audit pipeline:

| Category | Sent to | Trigger |
|---|---|---|
| `audit.completed` | The skill **owner** | Every audit completion. Body distinguishes `green` from `yellow`/`red` and links to the audit history page. |
| `audit.risky_for_consumer` | Every consumer of a `yellow`/`red`-verdict skill — every user in `sharedWithUsers`, plus the membership of every org in `sharedWithOrgs` (resolved via NyxID at fan-out time) | Same audit completion. Skipped for `green`. |

There are no other categories; share / waiver