# Capability Service API

Capability Service publishes versioned permission catalogues for logical
services and sites. Use its public discovery endpoint to load a published
project's primitive actions, preset expansions and role defaults into your
integration. The receiving application remains responsible for authentication,
resource access and enforcement.

API base: `https://api.capability.service.m7.org/v1/`.
Manage projects, catalogue definitions, access, immutable revisions and public
visibility in the [Capability application](https://capability.service.m7.org/).

## Public discovery

| Route | Required query | Optional query | Authentication |
| --- | --- | --- | --- |
| GET `/v1/capabilities.json` | `project_id` | `revision` | None for an active project whose Owner enabled public discovery. |

```bash
curl --fail-with-body --silent --show-error \
  --get 'https://api.capability.service.m7.org/v1/capabilities.json' \
  --data-urlencode 'project_id=PROJECT_UUID'
```

Replace `PROJECT_UUID` with your catalogue project's non-nil dashed UUID.
Public discovery is off by default. A private, archived or missing project
returns HTTP 404. Publication of definitions grants no access to the service's
management tools or to a consumer's resources.

## Responses and versions

A successful discovery response is the raw JSON catalogue, rather than a
`status/comment/data` envelope. An optional positive `revision` selects an
immutable snapshot; omission loads the latest coherent catalogue. Versions
and definition IDs are scoped to the project.

Errors use an envelope with `status: 0`, `comment` and `data.code`. HTTP 400
means malformed query fields or values; HTTP 404 means the project is not
publicly available or the requested revision is absent; HTTP 503 means the
catalogue is unavailable. Inspect both HTTP and body status. There is no
pagination for this document. Responses use `Cache-Control: no-store` and
public cross-origin discovery allows `Access-Control-Allow-Origin: *`.

## Guides

- [Discovery fields, snapshots and definition resolution](https://m7.org/docs/api/api.capability.service.m7.org/discovery.md)
- [Publication, credentials and workspace boundaries](https://m7.org/docs/api/api.capability.service.m7.org/authorization.md)