# Capabilities

> Publish, list, fetch, edit and deprecate capabilities. Sellers write; anyone with a key can read what discovery would show.

### `POST /v1/capabilities`

Scope `capabilities:write` (provider key). Publishes a capability. `providerId` comes from your key.

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | shown in discovery |
| `description` | string | yes | searched and ranked on |
| `protocol` | `"rest"` \| `"mcp"` | yes | |
| `priceMinor` | string | yes | cents per call |
| `category` | string | yes | |
| `endpoint` | string | one of | the URL buyers call |
| `address` | object | one of | `{kind:"url", url}` or `{kind:"package", command, args, version}`. Give exactly one of `endpoint` or `address` |
| `toolName` | string | `mcp` only | **required** for `mcp`, **refused** for `rest` |
| `schema` | object | no | JSON Schema of the request body or tool arguments |
| `tags` | string[] | no | |
| `latencyP50Ms` | number | no | advertised median latency |
| `currency` | `"USD"` | no | default `USD` |
| `version` | string | no | your version label |

A **package** address must use an approved launcher (`npx`) and pin an exact version in **both** `version` and `args` (`["-y","@acme/ocr-mcp@1.4.2"]`).

```json
// 200
{ "capability": { "id": "cap_…", "status": "active", "…": "…" }, "version": { "id": "…", "endpoint": "…", "address": { "…": "…" }, "hash": "…" } }
```

### `GET /v1/capabilities`

Scope `capabilities:read`, **provider keys only**. Your own listings, including **deprecated** ones: `{ capabilities: [{ capability, version }] }`. A workspace key gets `403`. Buyers use [discovery](https://docs.zanora.dev/api/discovery.md).

### `GET /v1/capabilities/:id`

Scope `capabilities:read`. One capability, with `provider` and a `discoverable` flag. `version` (the address) is included only if discovery would show this capability (active, from a verified seller), or if you're its seller. Otherwise the capability is described but has no address to call.

### `POST /v1/capabilities/:id`

Scope `capabilities:write`, owner only. **Edits a live listing** and keeps its id. The body is a patch: send only what changes.

| Field | Notes |
|---|---|
| `priceMinor`, `currency` | effective from the next price quote |
| `name`, `description`, `category`, `tags` | re-indexed for discovery |
| `schema` | publishes a new version |
| `latencyP50Ms` | |

There's no field for the address, protocol or tool name: those can't change. A capability that isn't `active` refuses edits. Returns `{ capability, changed: ["priceMinor", …], version? }`.

### `POST /v1/capabilities/:id/deprecate`

Scope `capabilities:write`, owner only. No body. Removes the capability from discovery. Existing ids still resolve.