API Reference

Look up a capability by its URN. The URN is the URL path itself — just navigate to the URN. The registry finds the most specific registered capability that matches.

Parameters

The URL path after / is the full capability URN.

Example

GET /cap:op=extract;format=pdf

200 OK
Content-Type: application/json

{
  "urn": "cap:format=pdf;in=\"media:pdf;bytes\";op=extract;out=\"media:text;utf8\"",
  "title": "PDF Text Extractor",
  "description": "Extracts text from PDF documents",
  "arguments": { ... },
  "output": { ... }
}

Responses

Status	Description
200	Capability found
404	No matching capability

Returns all registered capabilities. Each entry includes the URN and title.

Example

GET /api/capabilities

200 OK
Content-Type: application/json

[
  {
    "urn": "cap:format=pdf;in=\"media:pdf;bytes\";op=extract;out=\"media:text;utf8\"",
    "title": "PDF Text Extractor"
  },
  {
    "urn": "cap:in=\"media:text;utf8\";language=es;op=translate;out=\"media:text;utf8\"",
    "title": "Spanish Translator"
  }
]

Find all capabilities that match a request URN. Results are ordered by specificity, highest first. The most specific match is first in the array.

Query parameters

Parameter	Description
q	The request URN to match against

Example

GET /api/capabilities/match?q=cap:op=extract

200 OK
Content-Type: application/json

[
  {
    "urn": "cap:format=pdf;in=\"media:pdf;bytes\";op=extract;out=\"media:text;utf8\"",
    "specificity": 8
  },
  {
    "urn": "cap:format=epub;in=\"media:epub;bytes\";op=extract;out=\"media:text;utf8\"",
    "specificity": 8
  },
  {
    "urn": "cap:in=\"media:bytes\";op=extract;out=\"media:text;utf8\"",
    "specificity": 6
  }
]

The matching uses the same algorithm as the libraries. The request URN is the pattern, and each registered capability is tested as an instance. Capabilities that pass are returned with their specificity score.

Responses

Status	Description
200	Results (may be an empty array)
400	Invalid URN in query parameter

Register a new capability in the registry. Requires authentication.

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Request body

A capability definition JSON object.

POST /api/admin/capabilities
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "urn": "cap:in=\"media:text;utf8\";op=summarize;out=\"media:text;utf8\"",
  "title": "Text Summarizer",
  "description": "Generates summaries of text content",
  "arguments": {
    "required": [
      {
        "name": "input",
        "type": "string",
        "description": "Text to summarize"
      }
    ],
    "optional": [
      {
        "name": "max_length",
        "type": "number",
        "description": "Maximum summary length in characters"
      }
    ]
  },
  "output": {
    "type": "text",
    "media": "media:text;utf8",
    "description": "Summarized text"
  }
}

Responses

Status	Description
201	Capability registered
400	Invalid definition (malformed URN, missing fields)
401	Missing or invalid authentication
409	Capability with this URN already exists