Capabilities API

Base path: /api/workspaces/{workspaceId}/capabilities

Capability invocation is the primary way to interact with extension logic. The platform routes each call to the correct extension based on the registry.

Authorization: Requires ADMIN role or workspace membership.

Invoke a Capability

POST /api/workspaces/{workspaceId}/capabilities/{capabilityKey}
Content-Type: application/json

Path Parameters

Parameter	Description
workspaceId	Workspace UUID
capabilityKey	Dot-separated capability key (e.g. crm.product.search)

Request Body

Any JSON object. The shape is defined by the extension handler for that capability key.

Example

curl -X POST http://localhost:8080/api/workspaces/ws-uuid/capabilities/crm.product.search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"query": "laptop", "limit": 10}'

Response 200 OK

{
  "code": "SUCCESS",
  "data": {
    "results": [
      { "id": "prod-1", "name": "Laptop Pro", "price": 1299.00 }
    ],
    "total": 1
  }
}

---

Capability Key Convention

Keys follow a dot-separated prefix pattern:

{domain}.{resource}.{action}

Examples:

Key	Description
crm.product.search	Search products in the CRM extension
crm.deal.create	Create a new deal
chat.conversation.list	List conversations
chat.message.send	Send a message

The key is built from:

• @CapabilityGroup(prefix = "crm.product") on the handler class
• @Capability(key = "search") on the method

→ Combined: crm.product.search

---

Routing Logic

1. Platform looks up (workspaceId, capabilityKey) in ext_capability_registry
2. Finds the extension's runtimeType and endpoint
3. Dispatches:
   • IN_PROCESS: Reflects into the PF4J plugin, finds the @CapabilityGroup/@Capability method, invokes it
   • EXTERNAL_SERVICE: HTTP POST to {serviceBaseUrl}/capabilities/{capabilityKey}

---

Error Responses

Scenario	HTTP Status	code
Capability key not found	404	NOT_FOUND
Extension disabled	403	EXTENSION_DISABLED
Handler threw CapabilityException	400/500	handler-defined error code
Unauthorized	403	FORBIDDEN