Prudai Developer API: discovery
The specification and the scope catalogue, open and without login.
Base URL https://api.prudai.com/v1. Logging in is in Login, scopes in Scopes and permissions, errors in Errors. Overview.
| Method | Path | What it does | State |
|---|---|---|---|
GET | /v1/capabilities | Read available features and activation guidance | In production |
POST | /v1/capabilities/{id}/disable | Turn a feature or setting off | Coming soon |
POST | /v1/capabilities/{id}/enable | Turn a feature or setting on | Coming soon |
POST | /v1/capabilities/{id}/request | Request a paid feature or extra product | Coming soon |
GET | /v1/guide | Read the caller’s agent guide | In production |
GET | /v1/integrations | Read integration availability and connection guidance | In production |
GET | /v1/openapi.json | Read the implemented public API contract | In production |
GET | /v1/scopes | Read the public scope catalogue | In production |
GET | /v1/skills | List the Prudai skills available to the caller | In production |
GET | /v1/skills/{name} | Read one available Prudai skill | In production |
Read available features and activation guidance
GET /v1/capabilities
Uses current product entitlements and feature gates for this organisation and user. Enabled describes current entitlement and configuration status; each operation still checks user and object rights. scope_granted independently describes access through this credential. Activation is guidance only; this operation changes no setting. enable.kind is self for an existing app setting (exact POST, scope and product), connect for a consent flow from GET /v1/integrations, and request for paid features or extra products (human-reviewed POST, never direct entitlement changes). Unknown costs are explicitly unknown and are never a promise of free activation.
- State: in production.
- Scope:
prudai:capabilities:read - Approval:
none, no extra step.
Parameters
product
Exact entitled product slug. Omit to use all products available to the caller. pattern^[a-z][a-z0-9-]{0,79}$
Responses
| Status | Meaning |
|---|---|
200 | Feature metadata in the task envelope. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s "https://api.prudai.com/v1/capabilities" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo capabilities list[ { "id": "string", "product": "string", "title": "string", "description": "string", "enabled": false, "reason": "string", "scope": "string", "scope_granted": false, "enable": { "kind": "self", "method": "POST", "path": "string", "scope": "string", "params": { "product": "leo" }, "url": "https://voorbeeld.nl", "approval": "none", "costs": "unknown", "approver": "string" }, "disable": { "kind": "self", "method": "POST", "path": "string", "scope": "string", "params": { "product": "leo" }, "url": "https://voorbeeld.nl", "approval": "none", "costs": "unknown", "approver": "string" }, "costs": "unknown" }]Turn a feature or setting off
POST /v1/capabilities/{id}/disable
Changes only an existing app setting through its existing service and role checks. Organisation settings require the same owner or administrator role as the app; personal settings affect only the caller. Unsupported settings, paid capabilities and integrations cannot be enabled or disabled here. No entitlement is granted. Personal and signed-in user tokens only; service credentials are rejected. Idempotency-Key is mandatory. dryRun=true validates and previews without changing settings, creating an approval request or granting any capability.
Only the toggles (writing-style, organization-social, feed-quiz) have an off switch: they keep their data. The settings that hold your own content (source-settings, publisher-subscriptions, organization-prompt, escalation-settings) return 422 validation_error here, because switching them off would overwrite that content; clear one with enable and the exact new value instead.
- State: coming soon, not in production yet.
- Scope:
prudai:capabilities:write - Approval:
confirm, the user confirms exactly this call. - Dry run:
?dryRun=trueshows what would happen and stores nothing. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
idrequired
Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160dryRun
Validate and preview without changing settings or creating an approval request. default:falseIdempotency-Keyrequired
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern^[\x21-\x7E]+$x-prudai-approval
Approved one-use request id. Repeat the exact method, path, query and body. The grant is consumed before execution; obtain a new approval after a failed execution. Idempotency-Key is excluded from the approval fingerprint. pattern^apr_[A-Za-z0-9]{24}$
Body
JSON, required.
product
Exact product slug. Runtime product and staff restrictions still apply. One of:leo,leo-fiscaal,zia,vera,bever,maia,irmasettings
Waarden voor de gekozen instelling zoals hierboven beschreven. Andere velden worden geweigerd. Laat weg of geef een leeg object bij de drie aan/uit-schakelaars en bij elke uitzetactie.
Responses
| Status | Meaning |
|---|---|
200 | Validated dry-run preview or the recorded idempotent result. |
202 | Human approval is required; no setting or entitlement has been changed. |
400 | Invalid input or missing Idempotency-Key. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown or unavailable capability or setting. |
409 | Capability needs another activation kind, or the setting cannot be changed. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s -X POST "https://api.prudai.com/v1/capabilities/<id>/disable" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "product": "leo", "settings": { "disabledSourceIds": [ "example-source" ] } }'prudai leo capabilities disableTurn a feature or setting on
POST /v1/capabilities/{id}/enable
Changes only an existing app setting through its existing service and role checks. Organisation settings require the same owner or administrator role as the app; personal settings affect only the caller. Unsupported settings, paid capabilities and integrations cannot be enabled or disabled here. No entitlement is granted. Personal and signed-in user tokens only; service credentials are rejected. Idempotency-Key is mandatory. dryRun=true validates and previews without changing settings, creating an approval request or granting any capability.
- State: coming soon, not in production yet.
- Scope:
prudai:capabilities:write - Approval:
confirm, the user confirms exactly this call. - Dry run:
?dryRun=trueshows what would happen and stores nothing. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
idrequired
Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160dryRun
Validate and preview without changing settings or creating an approval request. default:falseIdempotency-Keyrequired
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern^[\x21-\x7E]+$x-prudai-approval
Approved one-use request id. Repeat the exact method, path, query and body. The grant is consumed before execution; obtain a new approval after a failed execution. Idempotency-Key is excluded from the approval fingerprint. pattern^apr_[A-Za-z0-9]{24}$
Body
JSON, required.
product
Exact product slug. Runtime product and staff restrictions still apply. One of:leo,leo-fiscaal,zia,vera,bever,maia,irmasettings
Waarden voor de gekozen instelling zoals hierboven beschreven. Andere velden worden geweigerd. Laat weg of geef een leeg object bij de drie aan/uit-schakelaars en bij elke uitzetactie.
Responses
| Status | Meaning |
|---|---|
200 | Validated dry-run preview or the recorded idempotent result. |
202 | Human approval is required; no setting or entitlement has been changed. |
400 | Invalid input or missing Idempotency-Key. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown or unavailable capability or setting. |
409 | Capability needs another activation kind, or the setting cannot be changed. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s -X POST "https://api.prudai.com/v1/capabilities/<id>/enable" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "product": "leo", "settings": { "disabledSourceIds": [ "example-source" ] } }'prudai leo capabilities enableRequest a paid feature or extra product
POST /v1/capabilities/{id}/request
Records an activation request in the existing human-approval store. Never changes entitlements, starts a subscription or makes a payment. Only a Prudai platform administrator can grant plan capabilities. Costs remain unknown unless an authoritative price is available. Returns the upgrade link https://account.prudai.com/console. Approval or replay never activates the feature. Personal and signed-in user tokens only; service credentials are rejected. Idempotency-Key is mandatory. dryRun=true validates and previews without changing settings, creating an approval request or granting any capability.
- State: coming soon, not in production yet.
- Scope:
prudai:capabilities:request - Approval:
review, a second person or role approves. - Dry run:
?dryRun=trueshows what would happen and stores nothing. - Idempotency: send
Idempotency-Key; the same key with the same body does not run the action twice.
Parameters
idrequired
Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160dryRun
Validate and preview without changing settings or creating an approval request. default:falseIdempotency-Keyrequired
Client-chosen key, retained for 24 hours. Reusing it for different arguments returns 422 idempotency_key_reused. min length 8 · max length 255 · pattern^[\x21-\x7E]+$x-prudai-approval
Approved one-use request id. Repeat the exact method, path, query and body. The grant is consumed before execution; obtain a new approval after a failed execution. Idempotency-Key is excluded from the approval fingerprint. pattern^apr_[A-Za-z0-9]{24}$
Body
JSON, required.
productrequired
Exact product slug. Runtime product and staff restrictions still apply. One of:leo,leo-fiscaal,zia,vera,bever,maia,irmareason
Optional reason shown to the human reviewer; never interpreted as permission to activate or pay. max length 1000
Responses
| Status | Meaning |
|---|---|
200 | Validated dry-run preview or the recorded idempotent result. |
202 | Human approval is required; no setting or entitlement has been changed. |
400 | Invalid input or missing Idempotency-Key. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | Unknown or unavailable capability or setting. |
409 | Capability needs another activation kind, or the setting cannot be changed. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s -X POST "https://api.prudai.com/v1/capabilities/<id>/request" \ -H "Authorization: Bearer $PRUDAI_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "product": "leo", "reason": "string" }'prudai leo capabilities requestRead the caller's agent guide
GET /v1/guide
A short factual guide generated from the same product, scope and integration sources as discovery. Includes device login, approval requests and follow-up calls. Explains self, connect and request activation with examples; org entitlements remain under Prudai platform-admin control and payment always requires a person. Any valid credential may read this guide without an additional scope. It contains no customer content. Send Accept text/markdown for the Markdown text directly; application/json returns the same text under data.markdown in the task envelope.
- State: in production.
- Scope: no separate scope; logging in with your key or token is still required.
- Approval:
none, no extra step.
Responses
| Status | Meaning |
|---|---|
200 | Agent guide in the requested representation. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
Fields in data (200)
markdown
Response format: text/markdown.
curl -s "https://api.prudai.com/v1/guide" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo guide{ "markdown": "string"}Read integration availability and connection guidance
GET /v1/integrations
Lists available integrations and the current user or organisation status through their existing integration gates. Does not connect, disconnect or grant consent. Consent links are app routes that require the user’s authenticated browser session; credentials and provider tokens are never returned. An unavailable status check is reported as unknown rather than disconnected.
- State: in production.
- Scope:
prudai:integrations:read - Approval:
none, no extra step.
Parameters
product
Exact entitled product slug. Omit to use all products available to the caller. pattern^[a-z][a-z0-9-]{0,79}$
Responses
| Status | Meaning |
|---|---|
200 | Integration metadata and connection steps in the task envelope. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s "https://api.prudai.com/v1/integrations" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo integrations[ {}]Read the implemented public API contract
GET /v1/openapi.json
Public discovery without credentials. Returns the OpenAPI document directly, so spec registries and CLI generators can consume it. Paths contain implemented/live operations; x-prudai-planned-operations lists the planned operation ids, methods and paths with their planned status. This document describes public API metadata only, never tenant data.
- State: in production.
- Scope: none, open without login.
- Approval:
none, no extra step.
Responses
| Status | Meaning |
|---|---|
200 | An OpenAPI 3.1 document (a documented raw-response exception). |
304 | The public metadata snapshot has not changed (empty body). |
Fields in the response (200)
openapi
3.1.0infopathscomponentsx-prudai-planned-operationsx-prudai-planned-operations[].operationIdx-prudai-planned-operations[].methodx-prudai-planned-operations[].pathx-prudai-planned-operations[].x-prudai-status
planned
curl -s "https://api.prudai.com/v1/openapi.json"prudai leo openapi.json{ "openapi": "3.1.0", "info": {}, "paths": {}, "components": {}, "x-prudai-planned-operations": [ { "operationId": "string", "method": "string", "path": "string", "x-prudai-status": "planned" } ]}Read the public scope catalogue
GET /v1/scopes
Public discovery without credentials. Returns the same generated scope catalogue as the console; issuable and explicit_only describe availability and wildcard matching. The catalogue describes scopes and operations, not the caller’s grants.
- State: in production.
- Scope: none, open without login.
- Approval:
none, no extra step.
Responses
| Status | Meaning |
|---|---|
200 | Generated scope catalogue in the task envelope. |
304 | The public metadata snapshot has not changed (empty body). |
Fields in data (200)
schema
1wildcardsproducts
curl -s "https://api.prudai.com/v1/scopes"prudai leo scopes{ "schema": 1, "wildcards": {}, "products": [ {} ]}List the Prudai skills available to the caller
GET /v1/skills
Read-only skill discovery using the same product and capability gates as chat. Only the Prudai namespace is currently available; organisation skills will be additive. Omit product to list skills across the caller’s entitled products. The cursor is opaque and bound to that selection. Instructions are returned by getSkill.
- State: in production.
- Scope:
prudai:skills:read - Approval:
none, no extra step.
Parameters
product
Exact entitled product slug. Omit to use all products available to the caller. pattern^[a-z][a-z0-9-]{0,79}$limit
default:100· min 1 · max 100cursor
max length 200
Responses
| Status | Meaning |
|---|---|
200 | Skills in the task envelope; completeness and next describe pagination. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
curl -s "https://api.prudai.com/v1/skills" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo skills list[ { "namespace": "prudai", "name": "string", "title": "string", "description": "string", "products": [ "string" ] }]Read one available Prudai skill
GET /v1/skills/{name}
Returns registry frontmatter and instructions through the same product, capability, role and callable-tool gates as the app loader. The specialization focus filters the list only; it does not restrict reading an available skill by name.
- State: in production.
- Scope:
prudai:skills:read - Approval:
none, no extra step.
Parameters
namerequired
min length 3 · max length 40 · pattern^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$product
Exact entitled product slug. Omit to use all products available to the caller. pattern^[a-z][a-z0-9-]{0,79}$
Responses
| Status | Meaning |
|---|---|
200 | The available skill and instructions in the task envelope. |
401 | Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment. |
403 | Authenticated, but not allowed (missing scope, product not on the key or organisation, organisation suspended, Developer API switched off for the organisation, IP not on the allowlist, depth not permitted, licence does not permit redistribution). |
404 | The skill does not exist or is unavailable to the caller. |
422 | Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body). |
Fields in data (200)
namespace
prudainametitledescriptionproductsfrontmatterbody
curl -s "https://api.prudai.com/v1/skills/<name>" \ -H "Authorization: Bearer $PRUDAI_TOKEN"prudai leo skills get{ "namespace": "prudai", "name": "string", "title": "string", "description": "string", "products": [ "string" ], "frontmatter": {}, "body": "string"}