Skip to content

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.

MethodPathWhat it doesState
GET/v1/capabilitiesRead available features and activation guidanceIn production
POST/v1/capabilities/{id}/disableTurn a feature or setting offComing soon
POST/v1/capabilities/{id}/enableTurn a feature or setting onComing soon
POST/v1/capabilities/{id}/requestRequest a paid feature or extra productComing soon
GET/v1/guideRead the caller’s agent guideIn production
GET/v1/integrationsRead integration availability and connection guidanceIn production
GET/v1/openapi.jsonRead the implemented public API contractIn production
GET/v1/scopesRead the public scope catalogueIn production
GET/v1/skillsList the Prudai skills available to the callerIn production
GET/v1/skills/{name}Read one available Prudai skillIn 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 query · string
    Exact entitled product slug. Omit to use all products available to the caller. pattern ^[a-z][a-z0-9-]{0,79}$

Responses

StatusMeaning
200Feature metadata in the task envelope.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
curl -s "https://api.prudai.com/v1/capabilities" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo capabilities list
Response 200
[
{
"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=true shows what would happen and stores nothing.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • id path · string required
    Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160
  • dryRun query · boolean
    Validate and preview without changing settings or creating an approval request. default: false
  • Idempotency-Key header · string required
    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 header · string
    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 string
    Exact product slug. Runtime product and staff restrictions still apply. One of: leo, leo-fiscaal, zia, vera, bever, maia, irma
  • settings object
    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

StatusMeaning
200Validated dry-run preview or the recorded idempotent result.
202Human approval is required; no setting or entitlement has been changed.
400Invalid input or missing Idempotency-Key.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
404Unknown or unavailable capability or setting.
409Capability needs another activation kind, or the setting cannot be changed.
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
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"
]
}
}'
CLI (coming soon)
prudai leo capabilities disable

Turn 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=true shows what would happen and stores nothing.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • id path · string required
    Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160
  • dryRun query · boolean
    Validate and preview without changing settings or creating an approval request. default: false
  • Idempotency-Key header · string required
    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 header · string
    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 string
    Exact product slug. Runtime product and staff restrictions still apply. One of: leo, leo-fiscaal, zia, vera, bever, maia, irma
  • settings object
    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

StatusMeaning
200Validated dry-run preview or the recorded idempotent result.
202Human approval is required; no setting or entitlement has been changed.
400Invalid input or missing Idempotency-Key.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
404Unknown or unavailable capability or setting.
409Capability needs another activation kind, or the setting cannot be changed.
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
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"
]
}
}'
CLI (coming soon)
prudai leo capabilities enable

Request 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=true shows what would happen and stores nothing.
  • Idempotency: send Idempotency-Key; the same key with the same body does not run the action twice.

Parameters

  • id path · string required
    Exact id from GET /v1/capabilities; product requests use product:<slug>. max length 160
  • dryRun query · boolean
    Validate and preview without changing settings or creating an approval request. default: false
  • Idempotency-Key header · string required
    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 header · string
    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 string required
    Exact product slug. Runtime product and staff restrictions still apply. One of: leo, leo-fiscaal, zia, vera, bever, maia, irma
  • reason string
    Optional reason shown to the human reviewer; never interpreted as permission to activate or pay. max length 1000

Responses

StatusMeaning
200Validated dry-run preview or the recorded idempotent result.
202Human approval is required; no setting or entitlement has been changed.
400Invalid input or missing Idempotency-Key.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
404Unknown or unavailable capability or setting.
409Capability needs another activation kind, or the setting cannot be changed.
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
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"
}'
CLI (coming soon)
prudai leo capabilities request

Read 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

StatusMeaning
200Agent guide in the requested representation.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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 string

Response format: text/markdown.

curl
curl -s "https://api.prudai.com/v1/guide" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo guide
Response 200
{
"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 query · string
    Exact entitled product slug. Omit to use all products available to the caller. pattern ^[a-z][a-z0-9-]{0,79}$

Responses

StatusMeaning
200Integration metadata and connection steps in the task envelope.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
curl -s "https://api.prudai.com/v1/integrations" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo integrations
Response 200
[
{}
]

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

StatusMeaning
200An OpenAPI 3.1 document (a documented raw-response exception).
304The public metadata snapshot has not changed (empty body).

Fields in the response (200)

  • openapi string
    3.1.0
  • info object
  • paths object
  • components object
  • x-prudai-planned-operations array<object>
  • x-prudai-planned-operations[].operationId string
  • x-prudai-planned-operations[].method string
  • x-prudai-planned-operations[].path string
  • x-prudai-planned-operations[].x-prudai-status any
    planned
curl
curl -s "https://api.prudai.com/v1/openapi.json"
CLI (coming soon)
prudai leo openapi.json
Response 200
{
"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

StatusMeaning
200Generated scope catalogue in the task envelope.
304The public metadata snapshot has not changed (empty body).

Fields in data (200)

  • schema any
    1
  • wildcards object
  • products array<object>
curl
curl -s "https://api.prudai.com/v1/scopes"
CLI (coming soon)
prudai leo scopes
Response 200
{
"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 query · string
    Exact entitled product slug. Omit to use all products available to the caller. pattern ^[a-z][a-z0-9-]{0,79}$
  • limit query · integer
    default: 100 · min 1 · max 100
  • cursor query · string
    max length 200

Responses

StatusMeaning
200Skills in the task envelope; completeness and next describe pagination.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
422Well-formed request with invalid values (for example an unknown reasoning_effort, empty messages, or an Idempotency-Key reused with a different body).
curl
curl -s "https://api.prudai.com/v1/skills" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo skills list
Response 200
[
{
"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

  • name path · string required
    min length 3 · max length 40 · pattern ^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$
  • product query · string
    Exact entitled product slug. Omit to use all products available to the caller. pattern ^[a-z][a-z0-9-]{0,79}$

Responses

StatusMeaning
200The available skill and instructions in the task envelope.
401Missing, malformed, unknown, expired or revoked key, or a key used against the wrong environment.
403Authenticated, 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).
404The skill does not exist or is unavailable to the caller.
422Well-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 string
    prudai
  • name string
  • title string
  • description string
  • products array<string>
  • frontmatter object
  • body string
curl
curl -s "https://api.prudai.com/v1/skills/<name>" \
-H "Authorization: Bearer $PRUDAI_TOKEN"
CLI (coming soon)
prudai leo skills get
Response 200
{
"namespace": "prudai",
"name": "string",
"title": "string",
"description": "string",
"products": [
"string"
],
"frontmatter": {},
"body": "string"
}