# Ornn API Reference

Companion to `SKILL.md`. 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.

---

## 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`, `POST /skillsets` |
| `ornn:skill:update` | `ornn-user` | `PUT /skills/:id`, `PUT /skills/:id/permissions`, `POST /skills/:id/refresh`, `PATCH /skills/:idOrName/versions/:version`, `PUT /skillsets/:id`, `PUT /skillsets/:id/permissions` |
| `ornn:skill:delete` | `ornn-user` | `DELETE /skills/:id`, `DELETE /skills/:idOrName/versions/:version`, `DELETE /skillsets/:id` |
| `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. |
| `skill_dependency_not_found` | 404 | A `depends-on` ref in a dependency closure doesn't resolve or isn't visible (#968). |
| `dependency_cycle` | 409 | The dependency closure graph loops back on itself (#968). |
| `dependency_conflict` | 409 | One skill is pinned to two versions within the same closure (#968). |
| `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.6a Resolve dependency closure — `GET /api/v1/skills/:idOrName/closure`

Resolve the full **transitive** dependency closure of a skill version (#968). A skill declares direct dependencies in SKILL.md frontmatter under `metadata.depends-on` (an array of `<name-or-guid>@<major.minor>` or `<name>@<dist-tag>` refs — no semver ranges, no self-references). This endpoint walks that graph and returns every transitive dependency.

**Auth: optional.** Anonymous callers resolve against public skills only; a public skill that transitively depends on a private skill you can't read surfaces that node as `skill_dependency_not_found` (existence is not leaked).

Path param: `:idOrName`. Query param: `version` (optional) — literal `<major>.<minor>` or a dist-tag; defaults to the skill's latest.

Items come back in **deps-first topological order** — every dependency precedes the dependents that pin it, so installing in array order is always safe. Shared nodes (diamonds) appear exactly once.

Response 200:

```jsonc
{
  "data": {
    "items": [
      { "guid": "skl_...", "name": "pdf-tools",  "version": "1.0", "skillHash": "sha256:...", "depth": 1 },
      { "guid": "skl_...", "name": "report-base", "version": "2.3", "skillHash": "sha256:...", "depth": 0 }
    ]
  },
  "error": null
}
```

| Code | Status | Cause |
|---|---|---|
| `dependency_cycle` | 409 | The dependency graph loops back on itself. |
| `dependency_conflict` | 409 | One skill is pinned to two versions within the closure. |
| `skill_dependency_not_found` | 404 | A dependency ref doesn't resolve or isn't visible. |
| `skill_not_found` | 404 | The root skill / version is unknown (or not visible). |

The same closure is validated at **publish time** (`POST /skills`, `PUT /skills/:id`): a `depends-on` ref that won't resolve, forms a cycle, or conflicts fails the publish before the version is committed.

SDK: `client.resolveClosure(idOrName, { version })` and `client.pullClosure(idOrName, { version })` (TypeScript); `client.resolve_closure(...)` and `client.pull_closure(...)` (Python). `pullClosure` / `pull_closure` resolves the closure and downloads each package in topological order.

### 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.

---

## 5a. Skillsets (#969)

A **skillset** is a named, versioned, owned, visibility-scoped meta-package that references N member skills and carries a `kind`. One call (`/closure`) resolves + delivers the whole set — including each member's dependency closure (§3.6a). Ownership / visibility / immutable-versioning mirror skills; permission scopes **reuse** `ornn:skill:{create,read,update,delete}` (a dedicated `ornn:skillset:*` split is a tracked follow-up).

- `kind` enum: `generic` (default) | `consensus-supported`. The latter is an author **claim** that the members are an independent, comparable set — not a guarantee. Ornn delivers the set; the agent runs any consensus in its own runtime.
- `members`: 2..N skill refs, each `<name-or-guid>@<major.minor>` or `<name>@<dist-tag>` (same grammar as `depends-on`). No nested skillsets. Validated on publish (each must resolve to a readable skill version; union closure conflict-free).
- `instructions` (master prompt, #978): **REQUIRED**, versioned markdown telling an agent **HOW** to use the set (orchestration, ordering, which member to pick when). 1..8000 chars (trimmed; whitespace-only rejected). Distinct from `description` (short ≤1024 summary). **Required on BOTH create and publish, with NO carry-forward** — unlike `description`/`kind`/`tags` (a publish may omit them to inherit the prior version), every version must restate its own master prompt. Stored opaque (no rendering / sanitization / templating / linting / search-indexing). Surfaced verbatim on the detail read and as a root field on `/closure`.

### 5a.1 Create skillset — `POST /api/v1/skillsets`

Requires `ornn:skill:create`. Created **private** by default. JSON body:

```jsonc
{
  "name": "review-set",
  "description": "A curated comparison set.",
  "instructions": "Run pdf-tools first, then feed its output to csv-tools…",  // REQUIRED, 1..8000 chars
  "kind": "consensus-supported",   // optional, default "generic"
  "tags": ["review"],              // optional
  "members": ["pdf-tools@1.0", "csv-tools@2.1"],   // 2..N
  "version": "1.0"                 // optional, default "1.0"
}
```

Response 201 + `Location: /api/v1/skillsets/:guid`. Member validation runs before any write — a missing member → `skill_dependency_not_found` (404), a conflicting union closure → `dependency_conflict` (409). Duplicate name → `skillset_name_exists` (409). A missing/empty/whitespace-only `instructions` → `400` validation error.

### 5a.2 Get skillset — `GET /api/v1/skillsets/:idOrName`

**Auth: optional** (anon sees public only; private → `skillset_not_found`). Query `version` (optional). Returns `{ guid, name, description, instructions, kind, tags, members, version, latestVersion, isPrivate, createdBy, sharedWithUsers, sharedWithOrgs, createdOn, updatedOn }` — `instructions` is the version's master prompt.

### 5a.3 List versions — `GET /api/v1/skillsets/:idOrName/versions`

**Auth: optional** (visibility matches the detail read). Returns `{ items: [{ version, kind, memberCount, createdBy, createdOn }] }`, newest first.

### 5a.4 Resolve closure — `GET /api/v1/skillsets/:idOrName/closure`

**Auth: optional.** One-call resolve: the union of all member skills **plus** each member's transitive dependency closure (§3.6a), deduplicated and topo-sorted (deps-first). Query `version` (optional). The success body carries the version's master prompt as a **root sibling** of `items`: `{ "data": { "instructions": "…", "items": [ … ] }, "error": null }` (the skill `/skills/:id/closure` body stays `{ items }`, unchanged). Same error codes as §3.6a: `dependency_cycle` / `dependency_conflict` (409), `skill_dependency_not_found` (404), plus `skillset_not_found` (404) for an unknown/invisible root. A public skillset whose member transitively pins a private skill surfaces `skill_dependency_not_found` for that node to anonymous callers (no leak).

### 5a.5 Publish new version — `PUT /api/v1/skillsets/:id`

Requires `ornn:skill:update` + author/admin. JSON body `{ members, version, instructions, description?, kind?, tags? }` — `instructions` is **REQUIRED** here too (no carry-forward; each version restates its own master prompt). Appends an immutable `guid@version` and advances `latestVersion`; prior versions never mutate. Re-publishing an existing version → `skillset_version_exists` (409).

### 5a.6 Replace permissions — `PUT /api/v1/skillsets/:id/permissions`

Requires `ornn:skill:update` + author/admin. JSON body `{ isPrivate, sharedWithUsers, sharedWithOrgs }` (same shape as skills). An owner may only share into orgs they belong to.

### 5a.7 Delete skillset — `DELETE /api/v1/skillsets/:id`

Requires `ornn:skill:delete` + author/admin. Cascades all versions. Returns `{ data: { success: true } }`.

### 5a.8 Search skillsets — `GET /api/v1/skillset-search`

**Auth: optional** (anon → public scope). Query: `kind`, `scope`, `tags` (CSV, AND-match), `page`/`pageSize` or `cursor`/`limit`. Plain keyword/filter discovery — no semantic ranking, no facets, no popularity ranking. Cursor pagination per §1.10.

SDK: `client.createSkillset` / `getSkillset` / `publishSkillset` / `setSkillsetPermissions` / `deleteSkillset` / `getSkillsetClosure` / `searchSkillsets` (TypeScript); `create_skillset` / `get_skillset` / `publish_skillset` / `set_skillset_permissions` / `delete_skillset` / `resolve_skillset_closure` / `search_skillsets` (Python).

---

## 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.m