REST API

Every Prism handler is callable over plain HTTP with a Bearer key — no MCP client required. Authenticate with a sandbox key (ck_…) or an MCP OAuth token (mcp_…), POST a JSON body, and get a typed result back. The same auth, RBAC, organization scoping, and rate limits as the streaming MCP endpoint apply on every call.

Call a handler — the canonical envelope

POST to /api/mcp/tools/<tool_name>/ with the Prism coordinates in the body. This path returns the canonical { "success", "data" } envelope on every branch — success and error alike — so a client can branch on one field. Here is prism_entity_crud listing healthcare claims:

curl -X POST "https://{tenant}.cognethics.com/api/mcp/tools/prism_entity_crud/" \
  -H "Authorization: Bearer ck_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "list",
    "app": "healthcare",
    "entity": "claim",
    "arguments": { "page": 1, "page_size": 50 }
  }'

Response:

{
  "success": true,
  "data": {
    "items": [ { "id": "...", "status": "open" } ],
    "page": 1,
    "page_size": 50,
    "total": 128
  }
}

The same call from Python — pure requests, no SDK:

import os, requests

resp = requests.post(
    f"https://{os.environ['COGNETHICS_TENANT']}.cognethics.com/api/mcp/tools/prism_entity_crud/",
    headers={
        "Authorization": f"Bearer {os.environ['COGNETHICS_DEV_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "operation": "list",
        "app": "healthcare",
        "entity": "claim",
        "arguments": {"page": 1, "page_size": 50},
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["data"]["items"])

The enveloped variant — bare result on success

/api/v1/dev/call/ takes an enveloped request — { "name", "arguments" } — and returns the bare tool result on success (no { "success" } wrapper), or a { "error", "tool_name" } map on failure. Use it when you want the raw payload and will treat a non-2xx status as the error signal:

curl -X POST "https://{tenant}.cognethics.com/api/v1/dev/call/" \
  -H "Authorization: Bearer ck_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prism_entity_crud",
    "arguments": {
      "operation": "list",
      "app": "healthcare",
      "entity": "claim",
      "arguments": { "page": 1, "page_size": 50 }
    }
  }'

Response (the bare result):

{
  "items": [ { "id": "...", "status": "open" } ],
  "page": 1,
  "page_size": 50,
  "total": 128
}

Both doors run the same execution core — identical RBAC, organization scoping, persona policy, and audit. They differ only in the response shape. New integrations should prefer the canonical /api/mcp/tools/ envelope; /api/v1/dev/call/ is the thin, wrapper-free variant.

The response contract

The canonical envelope (/api/mcp/tools/) follows PrismResponse in the OpenAPI spec:

Status codes

Discover handlers

Two lenses over the same registry. Use the catalog and introspect endpoints for runtime / agent discovery; use the OpenAPI descriptor below for static codegen.

Browse the tool catalog with optional category / search filters:

curl -H "Authorization: Bearer ck_REPLACE_ME" \
  "https://{tenant}.cognethics.com/api/v1/dev/tools/?search=claim"

Drill into apps, entities, operations, and exact parameter schemas with /api/v1/dev/introspect/:

curl -H "Authorization: Bearer ck_REPLACE_ME" \
  "https://{tenant}.cognethics.com/api/v1/dev/introspect/?dimension=apps&mega_tool=entity_crud"

OpenAPI descriptor

The full handler surface is published as a live OpenAPI 3.0.3 document at /.well-known/openapi.json. Every handler appears as a distinctly-named operation under POST /prism/{mega_tool}/{app}/{entity}/{operation}, tagged by mega-tool and app, with the handler's parameter schema as its request body and the canonical PrismResponse as its 200. The servers[0].url is stamped to the host you fetch it from, so a generated client targets the right tenant out of the box.

Download it and generate a typed client with any OpenAPI tool:

curl -o prism.openapi.json \
  https://{tenant}.cognethics.com/.well-known/openapi.json

openapi-generator-cli generate \
  -i prism.openapi.json -g python -o ./prism-client

Try it out

The Swagger UI below loads the live spec from /.well-known/openapi.json. Authorize with your Bearer key, expand an operation, and call it in-browser.

Rate limits

The REST surface enforces the same authentication, RBAC, organization scoping, and rate limits as the streaming MCP endpoint — there is no weaker path in. Requests are subject to a per-tenant ceiling and an IP-level guard against repeated failed authentication. When a limit is reached you receive a 429 with a Retry-After header; back off and retry after the indicated interval.

Next: browse the handler catalog, read the MCP quickstart, or explore worked recipes.