Skip to main content
Main content

Developer Portal

API reference

Every endpoint of the Vouli IQ Public API, generated from its OpenAPI 3.1.0 document — parameters, schemas, scopes and examples in curl, TypeScript and Python. Each read endpoint has a Try-it panel that calls the API from this page with a key you paste; use a vk_test_ sandbox key.

Version
2026-09-12
Base URL
https://www.vouliiq.com/api/v1
Operations
43

Getting started

Send the key as a bearer token and pin the dated version. A vk_test_ key reads a fixed set of synthetic rows and never touches tenant data.

Authorization: Bearer vk_test_XXXXXXXX_your_secret
Vouli-Version: 2026-09-12
  • Rate limits: per-key token bucket (capacity = per-minute limit, refill = limit/60 per second) plus a rolling 24h cap.
  • Pagination: cursor-based; limit 1–100 (default 25); pass next_cursor back as cursor.
  • Errors are always { error: { type, code, message, request_id } } — branch on code.

Command line

The TypeScript SDK includes a small vouli CLI. It reads the key from VOULI_API_KEY, never prints it, and knows the same resources as the SDK (board_documents, board_packs, board_votes, compliance, decisions, documents, gaps, incidents, insights, inventory, kpis, metric_values, metrics, milestones, obligations, risks, roadmap, scorecard, scores, signals, talent, vendor). Add --json for the raw envelope. Until registry publication, run it from the repository's sdk/vouli-iq directory after building it.

# The CLI ships inside the TypeScript SDK (bin: vouli). Key from the environment; never printed.
export VOULI_API_KEY=vk_test_…

vouli whoami
vouli list board_documents --limit 10
vouli list board_documents --limit 10 --cursor <next_cursor>
vouli get compliance
vouli list board_documents --json

Meta

Discovery: the index and this document.

GET/

Discover the resources this API version exposes.

Unauthenticated index: the current dated version, the versions still served, every resource with its required scope, and where to find the spec and the SDKs.

Authentication
None — this endpoint is public.
Required scope
—
Rate limit
Not rate limited per key.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The API index.
200 response of GET /
FieldTypeDescription
object"api_index"
api_version"2026-09-12"
supported_versionsarray of string
openapi_urlstring
documentation_url?string
resourcesarray of object
operations?array of objectEvery write and management operation, with the scope it needs.

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1" \
  -H "Vouli-Version: 2026-09-12"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1', {
  method: 'GET',
  headers: {
    'Vouli-Version': '2026-09-12',
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1",
    method="GET",
    headers={"Vouli-Version": "2026-09-12"},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Try it

Send GET / from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1

GET/openapi.json

Fetch this OpenAPI 3.1 document.

Unauthenticated. Generated from the same schemas the handlers enforce, so it cannot drift from the API.

Authentication
None — this endpoint is public.
Required scope
—
Rate limit
Not rate limited per key.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The OpenAPI 3.1 document.

object

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/openapi.json" \
  -H "Vouli-Version: 2026-09-12"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/openapi.json', {
  method: 'GET',
  headers: {
    'Vouli-Version': '2026-09-12',
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/openapi.json",
    method="GET",
    headers={"Vouli-Version": "2026-09-12"},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Try it

Send GET /openapi.json from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/openapi.json

MCP

Model Context Protocol server: the same resources as read-only tools for AI assistants.

POST/mcp

Model Context Protocol (MCP) server: read-only tools for AI assistants.

Streamable HTTP transport, JSON-RPC 2.0, one message per POST, single application/json responses (no SSE stream: GET and DELETE answer 405 with Allow: POST; no session id). Methods: initialize, notifications/initialized (202, no body), ping, tools/list, tools/call. Authentication, the plan gate, the per-key rate limit and the sandbox are the same as every other operation here; each tool requires its resource's scope and returns the same envelope as the matching GET, as structuredContent and as JSON text. Tool errors (a missing scope, a read failure) are results with isError: true; unknown methods are -32601, bad arguments -32602.

Authentication
Authorization: Bearer vk_…
Required scope
any valid key
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Not declared idempotent.

Parameters

Parameters of POST /mcp
NameInTypeDescription
MCP-Protocol-Versionheaderstringone of: 2025-06-18, 2025-03-26, 2024-11-05Sent by a client after initialize. An unsupported value is a 400.

Request body (application/json, required)

Request body of POST /mcp
FieldTypeDescription
jsonrpc"2.0"
id?string | integerOmit for a notification.
methodstringone of: initialize, notifications/initialized, ping, tools/list, tools/call
params?object
{
  "jsonrpc": "2.0",
  "id": "example_id",
  "method": "initialize",
  "params": {}
}

Responses

  • 200 A JSON-RPC 2.0 response: a result, or an error for an unknown method or invalid params.
  • 202 A notification (or a client response) was accepted. No body.
  • 400 Parse error (-32700), an invalid or batched message (-32600), or an unsupported MCP-Protocol-Version.
  • 401 No key, or the key does not verify. Carries WWW-Authenticate: Bearer.
  • 403 The plan does not include API access, the subscription is not live, or the request came from a foreign browser origin.
  • 413 Body over 64 KB.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
200 response of POST /mcp
FieldTypeDescription
jsonrpc"2.0"

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/mcp" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"example_id","method":"initialize","params":{}}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/mcp', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 'example_id',
    method: 'initialize',
    params: {},
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/mcp",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Content-Type": "application/json"},
    data=json.dumps({
        "jsonrpc": "2.0",
        "id": "example_id",
        "method": "initialize",
        "params": {},
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Board

GET/board/votes

List board votes — metadata only.

Board and circular votes with their timing and status. Never the motion, tallies, ballots or names; the outcome only when the board allows it; committee votes only when the board allows committee data. read:board by name. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:board
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /board/votes
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly records in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /board/votes
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of BoardVote · BoardVote
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "board_vote",
    "id": "00000000-0000-4000-8000-000000001801",
    "kind": "meeting",
    "status": "closed",
    "committee": null,
    "opens_at": "2026-08-01T09:00:00.000Z",
    "closes_at": "2026-09-01T09:00:00.000Z",
    "closed_at": "2026-09-01T09:00:00.000Z",
    "outcome": null,
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "board_vote",
    "id": "00000000-0000-4000-8000-000000001802",
    "kind": "circular",
    "status": "open",
    "committee": "[SANDBOX] audit",
    "opens_at": "2026-08-01T09:00:00.000Z",
    "closes_at": "2026-09-15T09:00:00.000Z",
    "closed_at": null,
    "outcome": null,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/board/votes?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.board_votes({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.board_votes(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /board/votes from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/board/votes

GET/board/documents

List board documents' signature status — never their text.

Minutes and written resolutions with version, status and how many of the required signatures are recorded. Never the body or who signed. read:board by name. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:board
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /board/documents
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly records in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /board/documents
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of BoardDocument · BoardDocument
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "board_document",
    "id": "00000000-0000-4000-8000-000000001811",
    "kind": "minutes",
    "version": 1,
    "status": "approved",
    "signer_count": 5,
    "signed_count": 2,
    "approved_at": "2026-09-01T09:00:00.000Z",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "board_document",
    "id": "00000000-0000-4000-8000-000000001812",
    "kind": "written_resolution",
    "version": 2,
    "status": "signed",
    "signer_count": 4,
    "signed_count": 4,
    "approved_at": "2026-08-01T09:00:00.000Z",
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/board/documents?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.board_documents({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.board_documents(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /board/documents from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/board/documents

GET/board/packs

List board packs' status — never their content.

Board packs with their status and scope. The title is null unless the board allows titles to leave Vouli IQ. read:board by name. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:board
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /board/packs
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly records in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /board/packs
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of BoardPack · BoardPack
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "board_pack",
    "id": "00000000-0000-4000-8000-000000001821",
    "status": "finalised",
    "scope": "board",
    "title": null,
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "board_pack",
    "id": "00000000-0000-4000-8000-000000001822",
    "status": "draft",
    "scope": "board",
    "title": "[SANDBOX] Q3 board pack",
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/board/packs?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.board_packs({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.board_packs(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /board/packs from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/board/packs

Compliance

GET/compliance

Retrieve the active compliance posture.

Overall posture per regime and jurisdiction. Individual obligations are a separate, paginated list at /compliance/obligations.

Authentication
Authorization: Bearer vk_…
Required scope
read:compliance
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The current object, or null.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /compliance
FieldTypeDescription
object"compliance_posture"
api_version"2026-09-12"
dataCompliancePosture | null · CompliancePostureThe current object, or null when the org has none yet.
has_morefalse
next_cursornull
Sandbox example of data
{
  "object": "compliance_posture",
  "id": "00000000-0000-4000-8000-000000000601",
  "version_number": 2,
  "overall_posture": "PARTIAL",
  "primary_jurisdictions": [
    "EU",
    "UK",
    "IN"
  ],
  "regimes": [
    {
      "regime_id": "eu-ai-act",
      "posture": "PARTIAL",
      "open_obligations": 4
    }
  ],
  "executive_summary": "[SANDBOX] Four EU AI Act obligations are open, two of them high priority.",
  "generated_at": "2026-09-01T09:00:00.000Z"
}

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/compliance" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const result = await vouli.compliance();
console.log(result.data);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

result = vouli.compliance()
print(result["data"])

Try it

Send GET /compliance from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/compliance

GET/compliance/obligations

List compliance obligations, newest first.

Every tracked obligation with its regime, jurisdiction, priority band, owner and target date. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:compliance
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /compliance/obligations
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
regime_idquerystringOnly obligations arising from this regime.
statusquerystringOnly obligations in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /compliance/obligations
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Obligation · Obligation
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "obligation",
    "id": "00000000-0000-4000-8000-000000000701",
    "obligation_key": "SANDBOX-O-001",
    "regime_id": "eu-ai-act",
    "regime_name": "EU AI Act",
    "jurisdiction": "EU",
    "title": "[SANDBOX] Maintain technical documentation for each high-risk system.",
    "priority_band": "HIGH",
    "status": "open",
    "owner_role": "Head of Compliance",
    "target_date": "2026-12-01",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "obligation",
    "id": "00000000-0000-4000-8000-000000000702",
    "obligation_key": "SANDBOX-O-002",
    "regime_id": "dpdp",
    "regime_name": "India DPDP Act",
    "jurisdiction": "IN",
    "title": "[SANDBOX] Register a grievance officer and publish the contact route.",
    "priority_band": "MEDIUM",
    "status": "in_progress",
    "owner_role": null,
    "target_date": null,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/compliance/obligations?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.obligations({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.obligations(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /compliance/obligations from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/compliance/obligations

Decisions

GET/decisions

List the Decision Memory register (Enterprise).

Recorded decisions with status, date, owner and tags, and the decision and rationale text (leave it out with exclude_text=true). read:decisions by name. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:decisions
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /decisions
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
exclude_textquerystringone of: true, falsetrue leaves the decision and rationale text out.
statusquerystringOnly decisions in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /decisions
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Decision · Decision
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "decision",
    "id": "00000000-0000-4000-8000-000000001831",
    "title": "[SANDBOX] Adopt a model-approval gate for credit models",
    "status": "active",
    "decision_date": "2026-08-28",
    "owner": "[SANDBOX] CRO",
    "tags": [
      "governance"
    ],
    "supersedes_id": null,
    "decision": "[SANDBOX] Every credit model change needs CRO sign-off.",
    "rationale": "[SANDBOX] Two drift incidents in Q2.",
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "decision",
    "id": "00000000-0000-4000-8000-000000001832",
    "title": "[SANDBOX] Pause the chatbot pilot",
    "status": "reversed",
    "decision_date": "2026-07-01",
    "owner": null,
    "tags": [],
    "supersedes_id": null,
    "decision": null,
    "rationale": null,
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/decisions?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.decisions({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.decisions(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /decisions from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/decisions

Documents

GET/documents

List knowledge-base documents — metadata only, newest first.

Every document in the AI knowledge base, whether a person or an API key added it, with its status and passage count. Metadata only: content, passages and files are never returned. Requires read:documents by name. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:documents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /documents
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringone of: uploading, pending, processing, ready, failedOnly documents in this state.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /documents
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Document · Document
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "document",
    "id": "00000000-0000-4000-8000-000000001701",
    "title": "[SANDBOX] AI acceptable-use policy",
    "filename": "ai-policy.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 182311,
    "status": "ready",
    "chunk_count": 14,
    "error": null,
    "created_via": "api",
    "external_ref": "sandbox-policy-1",
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "document",
    "id": "00000000-0000-4000-8000-000000001702",
    "title": "[SANDBOX] Q2 board risk report",
    "filename": "q2-risk.docx",
    "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "size_bytes": 54012,
    "status": "pending",
    "chunk_count": 0,
    "error": null,
    "created_via": "dashboard",
    "external_ref": null,
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/documents?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.documents({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.documents(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /documents from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/documents

POST/documents

Add a document to the AI knowledge base (descriptor, or the file inline up to 4 MB).

Two-step: send the descriptor; the answer carries a signed URL (valid 2 hours) to PUT the exact bytes to, then call POST /documents/{id}/process. Inline (≤ 4 MB): ?inline=1, the file as the body with its own Content-Type and the Vouli-Filename and Vouli-Sha256 headers — stored, checked and processed in one call. Larger inline bodies are a 413 use_two_step_upload. Counts against the plan's document quota; 60 uploads an hour per key. The checks are format and integrity checks only (type, size, sha256, a byte sniff); the content is not scanned. Requires an Idempotency-Key.

Authentication
Authorization: Bearer vk_…
Required scope
write:documents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /documents
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /documents
FieldTypeDescription
external_ref?stringYour reference, unique in the organisation: a second create with it is a 409 document_exists.
filenamestringFile name, with its extension (the type is resolved from it and the MIME).
mimestringMIME type: PDF, DOCX, PPTX, XLSX, CSV, TXT or Markdown.
sha256stringsha256 of the file (checked before anything is extracted).
sizeinteger (1–20971520)Exact size in bytes (checked against the uploaded file).
title?stringTitle shown in the knowledge base. Defaults to the file name.
{
  "external_ref": "example_external_ref",
  "filename": "example_filename",
  "mime": "example_mime",
  "sha256": "example_sha256",
  "size": 1,
  "title": "example_title"
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /documents
FieldTypeDescription
object"document"
api_version"2026-09-12"
dataDocument · Document
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/documents" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"example_external_ref","filename":"example_filename","mime":"example_mime","sha256":"example_sha256","size":1,"title":"example_title"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/documents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_ref: 'example_external_ref',
    filename: 'example_filename',
    mime: 'example_mime',
    sha256: 'example_sha256',
    size: 1,
    title: 'example_title',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/documents",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "external_ref": "example_external_ref",
        "filename": "example_filename",
        "mime": "example_mime",
        "sha256": "example_sha256",
        "size": 1,
        "title": "example_title",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

POST/documents/{id}/process

Check and process an uploaded document.

Checks, in order, that the file exists at its reserved place, that its size and sha256 match the descriptor, and its bytes (a file that fails is removed), then extracts, chunks and embeds it exactly as a dashboard upload. Answers with the final status (ready, or failed with a step-labelled reason). Requires an Idempotency-Key; send an empty body or {}.

Authentication
Authorization: Bearer vk_…
Required scope
write:documents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /documents/{id}/process
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json)

object

{}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of POST /documents/{id}/process
FieldTypeDescription
object"document"
api_version"2026-09-12"
dataDocument · Document
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000/process" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000/process', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000/process",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({}).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

GET/documents/{id}

Retrieve one document's metadata and status.

Status, passage count and error of one document — never its content. An id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
read:documents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /documents/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /documents/{id}
FieldTypeDescription
object"document"
api_version"2026-09-12"
dataDocument · Document
has_morefalse
next_cursornull

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000",
    method="GET",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12"},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Try it

Send GET /documents/{id} from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/documents/

DELETE/documents/{id}

Delete a document from the knowledge base.

Removes the file first (checked), then the document and its passages. A document id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
write:documents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of DELETE /documents/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of DELETE /documents/{id}
FieldTypeDescription
object"document_deleted"
api_version"2026-09-12"
dataDocumentDeleted · DocumentDeleted
has_morefalse
next_cursornull

Examples

curl

curl -X DELETE "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/documents/00000000-0000-4000-8000-000000000000",
    method="DELETE",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4())},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Incidents

GET/incidents

List AI incidents, newest first.

The AI Incident Command register: every declared incident with its type, severity, status, owner and notification clock. Requires the plan that includes Incident Command. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:incidents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /incidents
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
severityquerystringone of: low, medium, high, criticalOnly incidents at this severity.
statusquerystringone of: open, investigating, contained, resolved, post_review, closedOnly incidents in this lifecycle state.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /incidents
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Incident · Incident
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "incident",
    "id": "00000000-0000-4000-8000-000000001201",
    "title": "[SANDBOX] Credit model drifted outside its approved fairness band",
    "description": "[SANDBOX] Approval-rate gap between cohorts exceeded the approved threshold for two days.",
    "incident_type": "bias_harm",
    "severity": "high",
    "status": "investigating",
    "affected_systems": "[SANDBOX] Credit decisioning",
    "jurisdictions": "EU",
    "owner": "[SANDBOX] Head of Model Risk",
    "notification_required": true,
    "notification_deadline": "2026-09-04T09:00:00.000Z",
    "notified_at": null,
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "incident",
    "id": "00000000-0000-4000-8000-000000001202",
    "title": "[SANDBOX] Support agent quoted an unpublished refund policy",
    "description": null,
    "incident_type": "agent_failure",
    "severity": "medium",
    "status": "resolved",
    "affected_systems": null,
    "jurisdictions": null,
    "owner": null,
    "notification_required": false,
    "notification_deadline": null,
    "notified_at": null,
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/incidents?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.incidents({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.incidents(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /incidents from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/incidents

POST/incidents

Declare an AI incident.

Declares an incident in Incident Command, starting its timeline and notification clock. Requires an Idempotency-Key.

Authentication
Authorization: Bearer vk_…
Required scope
write:incidents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /incidents
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /incidents
FieldTypeDescription
affected_systems?stringSystems the incident touched.
description?stringLonger account.
incident_type?stringone of: model_failure, bias_harm, data_exposure, agent_failure, regulatory_inquiry, shadow_ai_breach, otherKind of incident. Defaults to other.
jurisdictions?stringJurisdictions whose notification rules apply.
notification_deadline?string | null (date-time)When the notification is due (ISO-8601).
notification_required?booleanWhether a regulator or stakeholder must be notified.
owner?stringAccountable incident owner (a name or role).
severity?stringone of: low, medium, high, criticalDefaults to medium.
status?stringone of: open, investigating, contained, resolved, post_review, closedDefaults to open.
titlestringWhat happened, in one line.
{
  "affected_systems": "example_affected_systems",
  "description": "example_description",
  "incident_type": "model_failure",
  "jurisdictions": "example_jurisdictions",
  "notification_deadline": "2026-01-01T00:00:00.000Z",
  "notification_required": true,
  "owner": "example_owner",
  "severity": "low",
  "status": "open",
  "title": "example_title"
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /incidents
FieldTypeDescription
object"incident"
api_version"2026-09-12"
dataIncident · Incident
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/incidents" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"affected_systems":"example_affected_systems","description":"example_description","incident_type":"model_failure","jurisdictions":"example_jurisdictions","notification_deadline":"2026-01-01T00:00:00.000Z","notification_required":true,"owner":"example_owner","severity":"low","status":"open","title":"example_title"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/incidents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    affected_systems: 'example_affected_systems',
    description: 'example_description',
    incident_type: 'model_failure',
    jurisdictions: 'example_jurisdictions',
    notification_deadline: '2026-01-01T00:00:00.000Z',
    notification_required: true,
    owner: 'example_owner',
    severity: 'low',
    status: 'open',
    title: 'example_title',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/incidents",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "affected_systems": "example_affected_systems",
        "description": "example_description",
        "incident_type": "model_failure",
        "jurisdictions": "example_jurisdictions",
        "notification_deadline": "2026-01-01T00:00:00.000Z",
        "notification_required": True,
        "owner": "example_owner",
        "severity": "low",
        "status": "open",
        "title": "example_title",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

PATCH/incidents/{id}

Change an incident.

Changes the fields given; a status change is logged on the incident timeline. An incident id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
write:incidents
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of PATCH /incidents/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Request body (application/json, required)

Request body of PATCH /incidents/{id}
FieldTypeDescription
affected_systems?string | nullSystems the incident touched.
description?string | nullLonger account.
incident_type?stringone of: model_failure, bias_harm, data_exposure, agent_failure, regulatory_inquiry, shadow_ai_breach, otherKind of incident.
jurisdictions?string | nullJurisdictions whose notification rules apply.
notification_deadline?string | null (date-time)When the notification is due (ISO-8601).
notification_required?booleanWhether a regulator or stakeholder must be notified.
owner?string | nullAccountable incident owner (a name or role).
severity?stringone of: low, medium, high, criticalSeverity.
status?stringone of: open, investigating, contained, resolved, post_review, closedLifecycle state.
title?stringWhat happened, in one line.
{
  "affected_systems": "example_affected_systems",
  "description": "example_description",
  "incident_type": "model_failure",
  "jurisdictions": "example_jurisdictions",
  "notification_deadline": "2026-01-01T00:00:00.000Z",
  "notification_required": true,
  "owner": "example_owner",
  "severity": "low",
  "status": "open",
  "title": "example_title"
}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of PATCH /incidents/{id}
FieldTypeDescription
object"incident"
api_version"2026-09-12"
dataIncident · Incident
has_morefalse
next_cursornull

Examples

curl

curl -X PATCH "https://www.vouliiq.com/api/v1/incidents/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"affected_systems":"example_affected_systems","description":"example_description","incident_type":"model_failure","jurisdictions":"example_jurisdictions","notification_deadline":"2026-01-01T00:00:00.000Z","notification_required":true,"owner":"example_owner","severity":"low","status":"open","title":"example_title"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/incidents/00000000-0000-4000-8000-000000000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    affected_systems: 'example_affected_systems',
    description: 'example_description',
    incident_type: 'model_failure',
    jurisdictions: 'example_jurisdictions',
    notification_deadline: '2026-01-01T00:00:00.000Z',
    notification_required: true,
    owner: 'example_owner',
    severity: 'low',
    status: 'open',
    title: 'example_title',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/incidents/00000000-0000-4000-8000-000000000000",
    method="PATCH",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "affected_systems": "example_affected_systems",
        "description": "example_description",
        "incident_type": "model_failure",
        "jurisdictions": "example_jurisdictions",
        "notification_deadline": "2026-01-01T00:00:00.000Z",
        "notification_required": True,
        "owner": "example_owner",
        "severity": "low",
        "status": "open",
        "title": "example_title",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Insights

GET/insights

List AI insights — metadata and the stored headline, flagged ai_generated.

Each generated insight's module, type, time, quality score and stored headline (≤ 500 characters), always flagged ai_generated: true with the model information link. read:insights by name. Cursor-paginated on generated_at.

Authentication
Authorization: Bearer vk_…
Required scope
read:insights
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /insights
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
modulequerystringOnly insights from this module.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /insights
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Insight · Insight
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "insight",
    "id": "00000000-0000-4000-8000-000000001841",
    "module": "M6",
    "insight_type": "brief",
    "generated_at": "2026-09-01T09:00:00.000Z",
    "quality_score": 0.84,
    "summary": "[SANDBOX] Risk exposure is concentrated in two credit models.",
    "ai_generated": true,
    "model_card_url": "https://www.vouliiq.com/trust/ai-governance"
  },
  {
    "object": "insight",
    "id": "00000000-0000-4000-8000-000000001842",
    "module": "M57",
    "insight_type": "okr:brief",
    "generated_at": "2026-08-01T09:00:00.000Z",
    "quality_score": null,
    "summary": null,
    "ai_generated": true,
    "model_card_url": "https://www.vouliiq.com/trust/ai-governance"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/insights?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.insights({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.insights(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /insights from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/insights

KPIs

GET/kpis

List KPIs (key results) with their targets and latest actuals, newest first.

Every key result in the OKR & KPI Engine with its unit, direction, target and current value — the targets an external system pushes actuals to (REST: POST /kpis/checkins). Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:kpis
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /kpis
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
codequerystringOnly the key result with this code.
statusquerystringone of: draft, active, achieved, missed, retiredOnly key results in this lifecycle state.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /kpis
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Kpi · Kpi
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "kpi",
    "id": "00000000-0000-4000-8000-000000001301",
    "code": "SANDBOX-O1-KR1",
    "objective_id": "00000000-0000-4000-8000-000000001300",
    "statement": "[SANDBOX] Lift the share of AI use cases with a named accountable owner to 90%.",
    "metric_name": "[SANDBOX] Use cases with an accountable owner",
    "unit": "%",
    "direction": "increase",
    "baseline_value": 42,
    "target_value": 90,
    "current_value": 61,
    "current_as_of": "2026-09-01T09:00:00.000Z",
    "measurement_frequency": "monthly",
    "status": "active",
    "created_at": "2026-09-01T09:00:00.000Z",
    "updated_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "kpi",
    "id": "00000000-0000-4000-8000-000000001302",
    "code": "SANDBOX-O1-KR2",
    "objective_id": "00000000-0000-4000-8000-000000001300",
    "statement": "[SANDBOX] Cut median model-approval cycle time to 10 days.",
    "metric_name": "[SANDBOX] Median approval cycle time",
    "unit": "days",
    "direction": "decrease",
    "baseline_value": 34,
    "target_value": 10,
    "current_value": null,
    "current_as_of": null,
    "measurement_frequency": "quarterly",
    "status": "active",
    "created_at": "2026-08-01T09:00:00.000Z",
    "updated_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/kpis?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.kpis({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.kpis(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /kpis from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/kpis

POST/kpis/checkins

Push KPI actuals — up to 500 data points, all or nothing.

Records actuals against key results (by id or code) from an external system — a warehouse, a BI tool, a monitoring pipeline. Every point is validated first; one bad point refuses the whole batch and nothing is written. Each key result's current value follows its LATEST period, so back-filling history never rolls it backwards. Requires an Idempotency-Key.

Authentication
Authorization: Bearer vk_…
Required scope
write:kpis
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /kpis/checkins
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /kpis/checkins
FieldTypeDescription
checkinsarray of object1–500 data points. All are validated before any is written; one bad point refuses the batch.
{
  "checkins": [
    {
      "evidence_ref": "example_evidence_ref",
      "key_result_code": "example_key_result_code",
      "key_result_id": "00000000-0000-4000-8000-000000000000",
      "note": "example_note",
      "period_start": "example_period_start",
      "source": "telemetry",
      "value": 1
    }
  ]
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 512 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /kpis/checkins
FieldTypeDescription
object"kpi_checkin_batch"
api_version"2026-09-12"
dataKpiCheckinBatch · KpiCheckinBatch
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/kpis/checkins" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"checkins":[{"evidence_ref":"example_evidence_ref","key_result_code":"example_key_result_code","key_result_id":"00000000-0000-4000-8000-000000000000","note":"example_note","period_start":"example_period_start","source":"telemetry","value":1}]}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/kpis/checkins', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    checkins: [
      {
        evidence_ref: 'example_evidence_ref',
        key_result_code: 'example_key_result_code',
        key_result_id: '00000000-0000-4000-8000-000000000000',
        note: 'example_note',
        period_start: 'example_period_start',
        source: 'telemetry',
        value: 1,
      },
    ],
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/kpis/checkins",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "checkins": [
            {
                "evidence_ref": "example_evidence_ref",
                "key_result_code": "example_key_result_code",
                "key_result_id": "00000000-0000-4000-8000-000000000000",
                "note": "example_note",
                "period_start": "example_period_start",
                "source": "telemetry",
                "value": 1,
            },
        ],
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Metrics

GET/metrics

List approved metric definitions — the governed meaning of each KPI.

Every metric whose current version was approved under maker-checker (or imported from the KPI register and awaiting review — approval_basis: migration), with its unit, grain, thresholds and freshness SLA. Requires the read:metrics scope by name: read:all does not grant it. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:metrics
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /metrics
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /metrics
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Metric · Metric
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "metric",
    "id": "00000000-0000-4000-8000-000000001601",
    "key": "sandbox.ai_use_case_owner_pct",
    "version": 2,
    "name": "[SANDBOX] Use cases with an accountable owner",
    "description": "[SANDBOX] Share of live AI use cases with a named owner.",
    "formula": "[SANDBOX] owned_use_cases / live_use_cases",
    "unit": "%",
    "currency": null,
    "grain": "month",
    "aggregation": "last",
    "direction": "increase",
    "steward_role": "[SANDBOX] Chief Risk Officer",
    "valid_min": 0,
    "valid_max": 100,
    "rag_green_at": 80,
    "rag_red_at": 50,
    "freshness_sla_hours": 744,
    "approval_basis": "maker_checker",
    "approved_at": "2026-09-01T09:00:00.000Z",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "metric",
    "id": "00000000-0000-4000-8000-000000001602",
    "key": "sandbox.model_approval_days",
    "version": 1,
    "name": "[SANDBOX] Median model-approval cycle time",
    "description": null,
    "formula": null,
    "unit": "days",
    "currency": null,
    "grain": "quarter",
    "aggregation": "last",
    "direction": "decrease",
    "steward_role": null,
    "valid_min": 0,
    "valid_max": null,
    "rag_green_at": 10,
    "rag_red_at": 30,
    "freshness_sla_hours": null,
    "approval_basis": "migration",
    "approved_at": "2026-08-01T09:00:00.000Z",
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/metrics?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.metrics({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.metrics(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /metrics from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/metrics

GET/metrics/values

Read a metric’s values point-in-time: as of a date, as known at a date.

Values are bitemporal. valid_from is the business time a value describes; recorded_at is when Vouli IQ learned it, and a correction is a later recorded_at for the same valid_from. as_of returns the one value in force then; start/end return a series (one value per valid_from); known_at answers as it was known at that time. Flagged values are excluded unless include_flagged=true. Cursor-paginated on valid_from.

Authentication
Authorization: Bearer vk_…
Required scope
read:metrics
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /metrics/values
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
as_ofquerystringReturn the ONE value in force at this business time (default: now, when no from/to is given).
dimensionquerystringDimension of the series; omit for the headline series.
endquerystringSeries end (business time, inclusive).
include_flaggedquerystringone of: true, falsetrue also returns values flagged out_of_range or unit_mismatch.
keyquerystringThe metric to read. Omit for the value in force of every approved metric (one row each).
known_atquerystringAnswer as it was known at this system time — "what we said then". Default: as known now.
startquerystringSeries start (business time, inclusive). Give start/end for a series instead of one value.
updated_sincequerystringIncremental sync: every value row RECORDED at or after this instant — corrections included, unresolved — newest first. Takes precedence over as_of / start / end.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /metrics/values
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of MetricValue · MetricValue
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "metric_value",
    "id": "00000000-0000-4000-8000-000000001611",
    "metric_key": "sandbox.ai_use_case_owner_pct",
    "definition_id": "00000000-0000-4000-8000-000000001601",
    "dimension_key": "",
    "value": 61,
    "unit": "%",
    "valid_from": "2026-08-31T00:00:00.000Z",
    "recorded_at": "2026-09-01T09:00:00.000Z",
    "source_kind": "event_api",
    "source_ref": "[SANDBOX] push source",
    "source_run_id": null,
    "quality": "ok"
  },
  {
    "object": "metric_value",
    "id": "00000000-0000-4000-8000-000000001612",
    "metric_key": "sandbox.ai_use_case_owner_pct",
    "definition_id": "00000000-0000-4000-8000-000000001601",
    "dimension_key": "",
    "value": 55,
    "unit": "%",
    "valid_from": "2026-07-31T00:00:00.000Z",
    "recorded_at": "2026-08-01T09:00:00.000Z",
    "source_kind": "manual",
    "source_ref": "[SANDBOX] manual entry",
    "source_run_id": null,
    "quality": "ok"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/metrics/values?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.metric_values({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.metric_values(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /metrics/values from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/metrics/values

Risks

GET/risks

List the AI risk register, newest first.

The org’s risk register with inherent and residual severity, owner, modelled exposure and target date. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:risks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /risks
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
severityquerystringone of: CRITICAL, HIGH, MEDIUM, LOWOnly risks at this inherent severity.
statusquerystringone of: Open, InProgress, Mitigated, Accepted, ClosedOnly risks in this lifecycle state.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /risks
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Risk · Risk
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "risk",
    "id": "00000000-0000-4000-8000-000000000201",
    "risk_id": "SANDBOX-R-001",
    "dimension": "Oversight",
    "description": "[SANDBOX] No named accountable owner for model approvals.",
    "severity": "CRITICAL",
    "residual_severity": "HIGH",
    "status": "Open",
    "source": "sovereign_red",
    "owner_name": "[SANDBOX] Chief Risk Officer",
    "financial_exposure_min": 250000,
    "financial_exposure_max": 1200000,
    "target_date": "2026-12-31",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "risk",
    "id": "00000000-0000-4000-8000-000000000202",
    "risk_id": "SANDBOX-R-002",
    "dimension": "Value",
    "description": "[SANDBOX] Benefit claims for two initiatives are unevidenced.",
    "severity": "HIGH",
    "residual_severity": "MEDIUM",
    "status": "InProgress",
    "source": "ai_generated",
    "owner_name": "[SANDBOX] CFO",
    "financial_exposure_min": 80000,
    "financial_exposure_max": 300000,
    "target_date": null,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/risks?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.risks({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.risks(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /risks from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/risks

POST/risks

Add a risk to the register.

Records a risk exactly as the Risk Register's "add risk" form does (source user_added, status Open, the untreated baseline set from the severity and likelihood given). Requires an Idempotency-Key.

Authentication
Authorization: Bearer vk_…
Required scope
write:risks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /risks
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /risks
FieldTypeDescription
descriptionstringWhat the risk is, in at least 20 characters.
dimension?stringSOVEREIGN dimension, if known. Defaults to OTHER.
likelihoodstringone of: RARE, UNLIKELY, POSSIBLE, LIKELY, ALMOST_CERTAINLikelihood.
mitigation_action?stringWhat is being done about it.
owner_name?stringAccountable owner (a name or role, not a user id).
severitystringone of: CRITICAL, HIGH, MEDIUM, LOWInherent severity.
target_date?stringTarget mitigation date.
titlestringShort name of the risk.
{
  "description": "example_description",
  "dimension": "example_dimension",
  "likelihood": "RARE",
  "mitigation_action": "example_mitigation_action",
  "owner_name": "example_owner_name",
  "severity": "CRITICAL",
  "target_date": "example_target_date",
  "title": "example_title"
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /risks
FieldTypeDescription
object"risk"
api_version"2026-09-12"
dataRisk · Risk
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/risks" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"description":"example_description","dimension":"example_dimension","likelihood":"RARE","mitigation_action":"example_mitigation_action","owner_name":"example_owner_name","severity":"CRITICAL","target_date":"example_target_date","title":"example_title"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/risks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'example_description',
    dimension: 'example_dimension',
    likelihood: 'RARE',
    mitigation_action: 'example_mitigation_action',
    owner_name: 'example_owner_name',
    severity: 'CRITICAL',
    target_date: 'example_target_date',
    title: 'example_title',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/risks",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "description": "example_description",
        "dimension": "example_dimension",
        "likelihood": "RARE",
        "mitigation_action": "example_mitigation_action",
        "owner_name": "example_owner_name",
        "severity": "CRITICAL",
        "target_date": "example_target_date",
        "title": "example_title",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

PATCH/risks/{id}

Change a risk.

Changes the fields given, through the same rules as the app: lowering or clearing a severity or likelihood, or closing, accepting or mitigating a CRITICAL risk, needs a severity_change_reason and is recorded as evidence. A risk id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
write:risks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of PATCH /risks/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Request body (application/json, required)

Request body of PATCH /risks/{id}
FieldTypeDescription
likelihood?stringone of: RARE, UNLIKELY, POSSIBLE, LIKELY, ALMOST_CERTAINLikelihood.
mitigation_action?string | nullWhat is being done about it.
owner_name?string | nullAccountable owner (a name or role).
residual_gap_reason?string | nullStanding explanation for a residual below the untreated baseline.
residual_severity?string | nullone of: CRITICAL, HIGH, MEDIUM, LOW, nullSeverity after mitigation.
severity?stringone of: CRITICAL, HIGH, MEDIUM, LOWInherent severity.
severity_change_reason?string | nullRequired when the change LOWERS or clears a severity or likelihood, or closes, accepts or mitigates a CRITICAL risk (at least 20 characters). Recorded as evidence.
status?stringone of: Open, InProgress, Mitigated, Accepted, ClosedLifecycle state.
target_date?string | nullTarget mitigation date.
title?string | nullShort name of the risk.
{
  "likelihood": "RARE",
  "mitigation_action": "example_mitigation_action",
  "owner_name": "example_owner_name",
  "residual_gap_reason": "example_residual_gap_reason",
  "residual_severity": "CRITICAL",
  "severity": "CRITICAL",
  "severity_change_reason": "example_severity_change_reason",
  "status": "Open",
  "target_date": "example_target_date",
  "title": "example_title"
}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of PATCH /risks/{id}
FieldTypeDescription
object"risk"
api_version"2026-09-12"
dataRisk · Risk
has_morefalse
next_cursornull

Examples

curl

curl -X PATCH "https://www.vouliiq.com/api/v1/risks/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"likelihood":"RARE","mitigation_action":"example_mitigation_action","owner_name":"example_owner_name","residual_gap_reason":"example_residual_gap_reason","residual_severity":"CRITICAL","severity":"CRITICAL","severity_change_reason":"example_severity_change_reason","status":"Open","target_date":"example_target_date","title":"example_title"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/risks/00000000-0000-4000-8000-000000000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    likelihood: 'RARE',
    mitigation_action: 'example_mitigation_action',
    owner_name: 'example_owner_name',
    residual_gap_reason: 'example_residual_gap_reason',
    residual_severity: 'CRITICAL',
    severity: 'CRITICAL',
    severity_change_reason: 'example_severity_change_reason',
    status: 'Open',
    target_date: 'example_target_date',
    title: 'example_title',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/risks/00000000-0000-4000-8000-000000000000",
    method="PATCH",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "likelihood": "RARE",
        "mitigation_action": "example_mitigation_action",
        "owner_name": "example_owner_name",
        "residual_gap_reason": "example_residual_gap_reason",
        "residual_severity": "CRITICAL",
        "severity": "CRITICAL",
        "severity_change_reason": "example_severity_change_reason",
        "status": "Open",
        "target_date": "example_target_date",
        "title": "example_title",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Roadmap

GET/roadmap

Retrieve the active transformation roadmap.

The active roadmap and its phases. Its milestones are a separate, paginated list at /roadmap/milestones.

Authentication
Authorization: Bearer vk_…
Required scope
read:roadmap
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The current object, or null.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /roadmap
FieldTypeDescription
object"roadmap"
api_version"2026-09-12"
dataRoadmap | null · RoadmapThe current object, or null when the org has none yet.
has_morefalse
next_cursornull
Sandbox example of data
{
  "object": "roadmap",
  "id": "00000000-0000-4000-8000-000000000401",
  "version_number": 3,
  "executive_summary": "[SANDBOX] Three-phase plan: stabilise oversight, then prove value, then scale.",
  "framework_blend": {
    "NIST AI RMF": 0.6,
    "ISO/IEC 42001": 0.4
  },
  "phases": [
    {
      "phase": "Phase 1",
      "objective": "[SANDBOX] Stand up the governance spine."
    },
    {
      "phase": "Phase 2",
      "objective": "[SANDBOX] Evidence the value of three initiatives."
    }
  ],
  "milestones_count": 2,
  "generated_at": "2026-09-01T09:00:00.000Z"
}

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/roadmap" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const result = await vouli.roadmap();
console.log(result.data);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

result = vouli.roadmap()
print(result["data"])

Try it

Send GET /roadmap from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/roadmap

GET/roadmap/milestones

List milestones of the active roadmap, newest first.

Delivery milestones under the active roadmap, with owner, RAG band and progress. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:roadmap
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /roadmap/milestones
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly milestones in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /roadmap/milestones
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Milestone · Milestone
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "milestone",
    "id": "00000000-0000-4000-8000-000000000501",
    "roadmap_id": "00000000-0000-4000-8000-000000000401",
    "milestone_key": "SANDBOX-M-001",
    "title": "[SANDBOX] Appoint an accountable owner for model approvals.",
    "phase": "Phase 1",
    "sequence": 1,
    "status": "in_progress",
    "rag_status": "AMBER",
    "progress_pct": 40,
    "owner_role": "Chief Risk Officer",
    "target_date": "2026-11-30",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "milestone",
    "id": "00000000-0000-4000-8000-000000000502",
    "roadmap_id": "00000000-0000-4000-8000-000000000401",
    "milestone_key": "SANDBOX-M-002",
    "title": "[SANDBOX] Publish the model inventory to the board.",
    "phase": "Phase 2",
    "sequence": 1,
    "status": "not_started",
    "rag_status": "GREEN",
    "progress_pct": 0,
    "owner_role": "CIO",
    "target_date": null,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/roadmap/milestones?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.milestones({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.milestones(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /roadmap/milestones from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/roadmap/milestones

Scores

GET/scores

List completed assessment scores, newest first.

The org’s assessment history — score, verdict and confidence per completed cycle — so a BI tool, GRC platform or warehouse can cite Vouli IQ as the instrument of record. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:scores
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /scores
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /scores
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Score · Score
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "score",
    "id": "00000000-0000-4000-8000-000000000101",
    "overall_score": 61.5,
    "adjusted_score": 58.2,
    "verdict": "REMEDIATION",
    "confidence": 0.82,
    "methodology_version": "2.0-weighted (SANDBOX)",
    "completed_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "score",
    "id": "00000000-0000-4000-8000-000000000102",
    "overall_score": 54,
    "adjusted_score": 50.1,
    "verdict": "REMEDIATION",
    "confidence": 0.77,
    "methodology_version": "2.0-weighted (SANDBOX)",
    "completed_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/scores?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.scores({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.scores(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /scores from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/scores

GET/scorecard

Retrieve the most recent completed SOVEREIGN scorecard.

The current scorecard with its completeness and evidence ratios. data is null before the first completed assessment.

Authentication
Authorization: Bearer vk_…
Required scope
read:scorecard
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The current object, or null.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /scorecard
FieldTypeDescription
object"scorecard"
api_version"2026-09-12"
dataScorecard | null · ScorecardThe current object, or null when the org has none yet.
has_morefalse
next_cursornull
Sandbox example of data
{
  "object": "scorecard",
  "id": "00000000-0000-4000-8000-000000000101",
  "overall_score": 61.5,
  "adjusted_score": 58.2,
  "verdict": "REMEDIATION",
  "confidence": 0.82,
  "completeness": 0.94,
  "evidence_ratio": 0.61,
  "methodology_version": "2.0-weighted (SANDBOX)",
  "frameworks_applied": [
    "NIST AI RMF",
    "ISO/IEC 42001"
  ],
  "completed_at": "2026-09-01T09:00:00.000Z"
}

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/scorecard" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const result = await vouli.scorecard();
console.log(result.data);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

result = vouli.scorecard()
print(result["data"])

Try it

Send GET /scorecard from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/scorecard

Signals

GET/signals

List the current signal set.

The deterministic numbers the Board Cockpit tiles render — one current row per signal type. Superseded values are not returned. Values read from a connected system (signal_type live.*, module_id MCP) are included only when an admin has turned on "share via API" for every connection they came from. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:signals
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /signals
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
typequerystringOnly the signal of this canonical type.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /signals
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Signal · Signal
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "signal",
    "id": "00000000-0000-4000-8000-000000000301",
    "signal_type": "maturity.overall",
    "module_id": "M1",
    "numeric_value": 61.5,
    "rag": "AMBER",
    "source_version": "2.0-weighted (SANDBOX)",
    "as_of": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "signal",
    "id": "00000000-0000-4000-8000-000000000302",
    "signal_type": "risk.exposure_usd",
    "module_id": "M6",
    "numeric_value": 1500000,
    "rag": "RED",
    "source_version": null,
    "as_of": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/signals?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.signals({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.signals(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /signals from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/signals

Talent

GET/talent

Retrieve the active talent readiness assessment.

Overall readiness and the recommended build / buy / borrow mix. Individual gaps are a separate, paginated list at /talent/gaps.

Authentication
Authorization: Bearer vk_…
Required scope
read:talent
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The current object, or null.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /talent
FieldTypeDescription
object"talent_readiness"
api_version"2026-09-12"
dataTalentReadiness | null · TalentReadinessThe current object, or null when the org has none yet.
has_morefalse
next_cursornull
Sandbox example of data
{
  "object": "talent_readiness",
  "id": "00000000-0000-4000-8000-000000001001",
  "version_number": 1,
  "overall_readiness": "DEVELOPING",
  "executive_summary": "[SANDBOX] Governance capability is the binding constraint, not engineering.",
  "build_buy_borrow": {
    "build": 0.4,
    "buy": 0.35,
    "borrow": 0.25
  },
  "generated_at": "2026-09-01T09:00:00.000Z"
}

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/talent" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const result = await vouli.talent();
console.log(result.data);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

result = vouli.talent()
print(result["data"])

Try it

Send GET /talent from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/talent

GET/talent/gaps

List talent gaps, newest first.

Every open capability gap with the headcount needed, priority band and recommended path. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:talent
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /talent/gaps
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly gaps in this status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /talent/gaps
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of TalentGap · TalentGap
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "talent_gap",
    "id": "00000000-0000-4000-8000-000000001101",
    "gap_key": "SANDBOX-G-001",
    "role_title": "[SANDBOX] AI Assurance Lead",
    "function_area": "Risk & Compliance",
    "headcount_needed": 1,
    "priority_band": "HIGH",
    "recommended_path": "BUY",
    "status": "open",
    "owner_role": "CHRO",
    "target_date": "2026-11-15",
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "talent_gap",
    "id": "00000000-0000-4000-8000-000000001102",
    "gap_key": "SANDBOX-G-002",
    "role_title": "[SANDBOX] MLOps Engineer",
    "function_area": "Engineering",
    "headcount_needed": 2,
    "priority_band": "MEDIUM",
    "recommended_path": "BUILD",
    "status": "in_progress",
    "owner_role": null,
    "target_date": null,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/talent/gaps?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.gaps({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.gaps(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /talent/gaps from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/talent/gaps

Vendor

GET/vendor

Retrieve the active AI vendor portfolio posture.

Portfolio-level posture and cross-vendor risks. The vendor inventory is a separate, paginated list at /vendor/inventory.

Authentication
Authorization: Bearer vk_…
Required scope
read:vendor
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Responses

  • 200 The current object, or null.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /vendor
FieldTypeDescription
object"vendor_portfolio"
api_version"2026-09-12"
dataVendorPortfolio | null · VendorPortfolioThe current object, or null when the org has none yet.
has_morefalse
next_cursornull
Sandbox example of data
{
  "object": "vendor_portfolio",
  "id": "00000000-0000-4000-8000-000000000801",
  "version_number": 1,
  "portfolio_posture": "CONCENTRATED",
  "executive_summary": "[SANDBOX] Two of three model vendors share one upstream provider.",
  "cross_vendor_risks": [
    "[SANDBOX] Shared upstream provider concentration."
  ],
  "recommended_actions": [
    {
      "action": "[SANDBOX] Qualify a second inference provider.",
      "priority": "HIGH"
    }
  ],
  "generated_at": "2026-09-01T09:00:00.000Z"
}

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/vendor" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const result = await vouli.vendor();
console.log(result.data);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

result = vouli.vendor()
print(result["data"])

Try it

Send GET /vendor from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

GET /api/v1/vendor

GET/vendor/inventory

List the AI vendor inventory, newest first.

Every vendor in the AI supply chain with its risk band, intake recommendation, contract end and annual cost. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
read:vendor
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /vendor/inventory
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.
statusquerystringOnly vendors in this review status.
updated_sincequerystringOnly rows created or changed at or after this instant — an ISO-8601 date (midnight UTC) or timestamp. Use it for incremental sync: store the time you started a sync and pass it next time.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /vendor/inventory
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of Vendor · Vendor
has_morebooleanTrue when another page exists.
next_cursorstring | nullOpaque cursor for the next page. Pass it back as ?cursor=. Null when has_more is false.
Sandbox example of data
[
  {
    "object": "vendor",
    "id": "00000000-0000-4000-8000-000000000901",
    "vendor_key": "SANDBOX-V-001",
    "vendor_name": "[SANDBOX] Northwind Models",
    "category": "Foundation model API",
    "ai_role": "inference",
    "initial_risk_band": "HIGH",
    "initial_recommendation": "RENEGOTIATE",
    "status": "under_review",
    "contract_end": "2027-03-31",
    "annual_cost_usd": 420000,
    "created_at": "2026-09-01T09:00:00.000Z"
  },
  {
    "object": "vendor",
    "id": "00000000-0000-4000-8000-000000000902",
    "vendor_key": "SANDBOX-V-002",
    "vendor_name": "[SANDBOX] Contoso Vector",
    "category": "Vector database",
    "ai_role": "retrieval",
    "initial_risk_band": "MEDIUM",
    "initial_recommendation": "RETAIN",
    "status": "approved",
    "contract_end": null,
    "annual_cost_usd": 60000,
    "created_at": "2026-08-01T09:00:00.000Z"
  }
]

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/vendor/inventory?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript SDK

import { VouliIQ } from '@vouli-iq/sdk';

const vouli = new VouliIQ({ apiKey: process.env.VOULI_API_KEY! });

const page = await vouli.inventory({ limit: 10 });
console.log(page.data, page.has_more, page.next_cursor);

Python SDK

import os
from vouli_iq import VouliIQ

vouli = VouliIQ(api_key=os.environ["VOULI_API_KEY"])

page = vouli.inventory(limit=10)
print(page["data"], page["has_more"], page["next_cursor"])

Try it

Send GET /vendor/inventory from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/vendor/inventory

POST/vendor/inventory

Add a vendor to the AI vendor inventory.

Adds a vendor the organisation already contracts with. vendor_key is unique in the organisation: a second create for the same key is a 409. Requires an Idempotency-Key.

Authentication
Authorization: Bearer vk_…
Required scope
write:vendor
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /vendor/inventory
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /vendor/inventory
FieldTypeDescription
ai_role?string | nullThe vendor’s role in the AI stack.
annual_cost_usd?number | null (0–…)Annual contract value, USD.
categorystringWhat the vendor supplies.
contract_end?string | nullContract end date.
contract_start?string | nullContract start date.
initial_recommendation?string | nullone of: consolidate, negotiate, maintain, exit, onboard, nullRecommendation at intake.
initial_risk_bandstringone of: CRITICAL, HIGH, MEDIUM, LOWRisk band at intake.
notes?string | nullWorking notes.
renewal_owner_role?string | nullRole accountable for the renewal.
status?stringone of: active, under_review, negotiating, sunsetting, exited, blockedReview status. Defaults to active.
vendor_keystringStable identifier, unique in the organisation (e.g. "openai").
vendor_namestringVendor name.
{
  "ai_role": "example_ai_role",
  "annual_cost_usd": 0,
  "category": "example_category",
  "contract_end": "example_contract_end",
  "contract_start": "example_contract_start",
  "initial_recommendation": "consolidate",
  "initial_risk_band": "CRITICAL",
  "notes": "example_notes",
  "renewal_owner_role": "example_renewal_owner_role",
  "status": "active",
  "vendor_key": "example_vendor_key",
  "vendor_name": "example_vendor_name"
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /vendor/inventory
FieldTypeDescription
object"vendor"
api_version"2026-09-12"
dataVendor · Vendor
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/vendor/inventory" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ai_role":"example_ai_role","annual_cost_usd":0,"category":"example_category","contract_end":"example_contract_end","contract_start":"example_contract_start","initial_recommendation":"consolidate","initial_risk_band":"CRITICAL","notes":"example_notes","renewal_owner_role":"example_renewal_owner_role","status":"active","vendor_key":"example_vendor_key","vendor_name":"example_vendor_name"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/vendor/inventory', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ai_role: 'example_ai_role',
    annual_cost_usd: 0,
    category: 'example_category',
    contract_end: 'example_contract_end',
    contract_start: 'example_contract_start',
    initial_recommendation: 'consolidate',
    initial_risk_band: 'CRITICAL',
    notes: 'example_notes',
    renewal_owner_role: 'example_renewal_owner_role',
    status: 'active',
    vendor_key: 'example_vendor_key',
    vendor_name: 'example_vendor_name',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/vendor/inventory",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "ai_role": "example_ai_role",
        "annual_cost_usd": 0,
        "category": "example_category",
        "contract_end": "example_contract_end",
        "contract_start": "example_contract_start",
        "initial_recommendation": "consolidate",
        "initial_risk_band": "CRITICAL",
        "notes": "example_notes",
        "renewal_owner_role": "example_renewal_owner_role",
        "status": "active",
        "vendor_key": "example_vendor_key",
        "vendor_name": "example_vendor_name",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

PATCH/vendor/inventory/{id}

Change a vendor’s working state.

Changes the team-owned fields (status, contract dates, renewal owner role, annual cost, notes). A vendor id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
write:vendor
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of PATCH /vendor/inventory/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Request body (application/json, required)

Request body of PATCH /vendor/inventory/{id}
FieldTypeDescription
annual_cost_usd?number | null (0–…)Annual contract value, USD.
contract_end?string | nullContract end date.
contract_start?string | nullContract start date.
notes?string | nullWorking notes.
renewal_owner_role?string | nullRole accountable for the renewal.
status?stringone of: active, under_review, negotiating, sunsetting, exited, blockedReview status.
{
  "annual_cost_usd": 0,
  "contract_end": "example_contract_end",
  "contract_start": "example_contract_start",
  "notes": "example_notes",
  "renewal_owner_role": "example_renewal_owner_role",
  "status": "active"
}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of PATCH /vendor/inventory/{id}
FieldTypeDescription
object"vendor"
api_version"2026-09-12"
dataVendor · Vendor
has_morefalse
next_cursornull

Examples

curl

curl -X PATCH "https://www.vouliiq.com/api/v1/vendor/inventory/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"annual_cost_usd":0,"contract_end":"example_contract_end","contract_start":"example_contract_start","notes":"example_notes","renewal_owner_role":"example_renewal_owner_role","status":"active"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/vendor/inventory/00000000-0000-4000-8000-000000000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    annual_cost_usd: 0,
    contract_end: 'example_contract_end',
    contract_start: 'example_contract_start',
    notes: 'example_notes',
    renewal_owner_role: 'example_renewal_owner_role',
    status: 'active',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/vendor/inventory/00000000-0000-4000-8000-000000000000",
    method="PATCH",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "annual_cost_usd": 0,
        "contract_end": "example_contract_end",
        "contract_start": "example_contract_start",
        "notes": "example_notes",
        "renewal_owner_role": "example_renewal_owner_role",
        "status": "active",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Audit

GET/audit

Export the audit log, oldest first (Enterprise).

The organisation's audit trail as SIEM-ready events — the same feed as Settings → SIEM export — oldest first, so a collector can poll it incrementally: keep the last next_cursor and pass it back. since and until bound the window. Enterprise plan only; read:all does not grant it. Every pull is itself audited. limit 1–1000 (default 100).

Authentication
Authorization: Bearer vk_…
Required scope
read:audit
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /audit
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page (strictly after that event).
limitqueryinteger (1–1000)Events to return, 1–1000. Defaults to 100.
formatquerystringone of: json, ndjsonjson (the list envelope, default) or ndjson (one event per line; the next cursor is in X-Next-Cursor).
sincequerystringEvents at or after this instant (ignored when cursor is given — the cursor is the finer bound).
untilquerystringEvents strictly before this instant.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /audit
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of AuditEvent · AuditEvent
has_moreboolean
next_cursorstring | null

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/audit?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/audit?limit=10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/audit?limit=10",
    method="GET",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12"},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Try it

Send GET /audit from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/audit

Events

POST/events

Push signed metric events from your own systems (Event API).

Send up to 100 events (500 metric points) to a push source you created in Settings → Grounding → Push sources. Authenticate with an API key holding write:events (when the source allows keys) or sign the request: Vouli-Source: <source id>, Vouli-Timestamp: <unix seconds>, Vouli-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>. The timestamp must be within ±5 minutes and each signature is accepted once. An event whose (external_id, type) the source sent before is counted as a duplicate and not written twice. Metric points become observations; a key with an approved metric definition that accepts the Event API is also stored in that governed series. Pushed values reach the signal bus near-real-time (seconds), and the AI only for sources an admin set to "use in AI". Requires an Idempotency-Key. org_id, source and any authorship field are refused by name at any depth.

Authentication
Authorization: Bearer vk_…
Required scope
write:events
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /events
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.
Vouli-Sourcerequiredheaderstring (uuid)The push source id (Settings → Grounding → Push sources). Required in both modes; with an API key it must be a source in the key's organisation that allows keys.
Vouli-TimestampheaderstringSigned mode: the current unix time in seconds. Must be within ±300 s.
Vouli-SignatureheaderstringSigned mode: v1=<hex HMAC-SHA256(secret, "<Vouli-Timestamp>.<raw body>")>; several comma-separated v1= values during a rotation. Each signature is accepted once (a replay is 409 signature_replayed).

Request body (application/json, required)

Request body of POST /events
FieldTypeDescription
eventsarray of object1–100 events, 500 metric points in total. Validated before anything is written.
strict?booleantrue: a metric key with no approved definition refuses the whole batch (422 unmapped_metric). Default false: it is listed in unmapped_keys.
{
  "events": [
    {
      "entity": {
        "attributes": {},
        "external_id": "example_external_id",
        "kind": "kpi"
      },
      "external_id": "example_external_id",
      "metrics": [
        {
          "dimension": "example_dimension",
          "key": "example_key",
          "unit": "example_unit",
          "value": 1
        }
      ],
      "occurred_at": "2026-01-01T00:00:00.000Z",
      "type": "example_type"
    }
  ],
  "strict": true
}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 Missing or invalid credential; in signed mode invalid_signature or timestamp_out_of_window (an unknown source answers exactly like a wrong secret).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 unknown_source: no push source with this id in the key's organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 512 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 422 unmapped_metric (strict: true and a key without an approved definition); nothing written.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of POST /events
FieldTypeDescription
object"event_batch"
api_version"2026-09-12"
dataEventBatch · EventBatch
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/events" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"entity":{"attributes":{},"external_id":"example_external_id","kind":"kpi"},"external_id":"example_external_id","metrics":[{"dimension":"example_dimension","key":"example_key","unit":"example_unit","value":1}],"occurred_at":"2026-01-01T00:00:00.000Z","type":"example_type"}],"strict":true}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      {
        entity: {
          attributes: {},
          external_id: 'example_external_id',
          kind: 'kpi',
        },
        external_id: 'example_external_id',
        metrics: [
          {
            dimension: 'example_dimension',
            key: 'example_key',
            unit: 'example_unit',
            value: 1,
          },
        ],
        occurred_at: '2026-01-01T00:00:00.000Z',
        type: 'example_type',
      },
    ],
    strict: true,
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/events",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "events": [
            {
                "entity": {
                    "attributes": {},
                    "external_id": "example_external_id",
                    "kind": "kpi",
                },
                "external_id": "example_external_id",
                "metrics": [
                    {
                        "dimension": "example_dimension",
                        "key": "example_key",
                        "unit": "example_unit",
                        "value": 1,
                    },
                ],
                "occurred_at": "2026-01-01T00:00:00.000Z",
                "type": "example_type",
            },
        ],
        "strict": True,
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Webhooks

GET/webhooks/subscriptions

List webhook subscriptions, newest first.

Every endpoint registered for this organisation, by the dashboard or by a key. The signing secret is never listed. Cursor-paginated.

Authentication
Authorization: Bearer vk_…
Required scope
manage:webhooks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Safe to retry — reads never change data.

Parameters

Parameters of GET /webhooks/subscriptions
NameInTypeDescription
cursorquerystringOpaque cursor from a previous response’s next_cursor. A cursor this API did not issue is rejected with 400 invalid_cursor.
limitqueryinteger (1–100)Rows to return, 1–100. Defaults to 25.

Responses

  • 200 A page of results.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
200 response of GET /webhooks/subscriptions
FieldTypeDescription
object"list"
api_version"2026-09-12"
dataarray of WebhookSubscription · WebhookSubscription
has_moreboolean
next_cursorstring | null

Examples

curl

curl -X GET "https://www.vouliiq.com/api/v1/webhooks/subscriptions?limit=10" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/webhooks/subscriptions?limit=10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/webhooks/subscriptions?limit=10",
    method="GET",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12"},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Try it

Send GET /webhooks/subscriptions from this browser

Use a vk_test_ sandbox key: it returns synthetic data only. The key stays in this tab's memory — it is never saved, and it is gone when you reload.

Parameters
GET /api/v1/webhooks/subscriptions

POST/webhooks/subscriptions

Register a webhook endpoint.

Registers an https endpoint and returns its signing secret ONCE. The URL must resolve to a public address (no localhost, private, link-local or metadata addresses, no http://). Requires an Idempotency-Key; a replay of the same request returns the subscription with secret: null.

Authentication
Authorization: Bearer vk_…
Required scope
manage:webhooks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /webhooks/subscriptions
NameInTypeDescription
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json, required)

Request body of POST /webhooks/subscriptions
FieldTypeDescription
active?booleanStart paused with false. Defaults to true.
description?string | nullFree-text label.
event_types?array of stringEvents to deliver. Omit or [] for every subscribable event.
urlstring (uri)https endpoint. Private, loopback, link-local and non-https addresses are refused.
{
  "active": true,
  "description": "example_description",
  "event_types": [
    "example_event_types"
  ],
  "url": "example_url"
}

Responses

  • 201 Created. The record as stored.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
201 response of POST /webhooks/subscriptions
FieldTypeDescription
object"webhook_subscription"
api_version"2026-09-12"
dataWebhookSubscription · WebhookSubscription
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"description":"example_description","event_types":["example_event_types"],"url":"example_url"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/webhooks/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    active: true,
    description: 'example_description',
    event_types: [
      'example_event_types',
    ],
    url: 'example_url',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/webhooks/subscriptions",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "active": True,
        "description": "example_description",
        "event_types": [
            "example_event_types",
        ],
        "url": "example_url",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

PATCH/webhooks/subscriptions/{id}

Pause, resume or change a webhook endpoint.

Changes the URL (re-checked), the event list, the description or active. A subscription id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
manage:webhooks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of PATCH /webhooks/subscriptions/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Request body (application/json, required)

Request body of PATCH /webhooks/subscriptions/{id}
FieldTypeDescription
active?booleanfalse pauses deliveries; true resumes them.
description?string | nullFree-text label.
event_types?array of stringReplace the event list. [] for every event.
url?string (uri)New https endpoint (the same address checks apply).
{
  "active": true,
  "description": "example_description",
  "event_types": [
    "example_event_types"
  ],
  "url": "example_url"
}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of PATCH /webhooks/subscriptions/{id}
FieldTypeDescription
object"webhook_subscription"
api_version"2026-09-12"
dataWebhookSubscription · WebhookSubscription
has_morefalse
next_cursornull

Examples

curl

curl -X PATCH "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"description":"example_description","event_types":["example_event_types"],"url":"example_url"}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    active: true,
    description: 'example_description',
    event_types: [
      'example_event_types',
    ],
    url: 'example_url',
  }),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000",
    method="PATCH",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({
        "active": True,
        "description": "example_description",
        "event_types": [
            "example_event_types",
        ],
        "url": "example_url",
    }).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

DELETE/webhooks/subscriptions/{id}

Delete a webhook endpoint.

Removes the endpoint and its queued deliveries. A subscription id from another organisation is a 404.

Authentication
Authorization: Bearer vk_…
Required scope
manage:webhooks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of DELETE /webhooks/subscriptions/{id}
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyheaderstringOptional. Same replay semantics as on POST, for 24h.

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of DELETE /webhooks/subscriptions/{id}
FieldTypeDescription
object"webhook_subscription_deleted"
api_version"2026-09-12"
dataWebhookSubscriptionDeleted · WebhookSubscriptionDeleted
has_morefalse
next_cursornull

Examples

curl

curl -X DELETE "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)"

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
  },
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000",
    method="DELETE",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4())},
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

POST/webhooks/subscriptions/{id}/test

Send a signed test `ping` to one endpoint, now.

Sends one ping event through the real delivery path — the same SSRF checks and the same X-Vouli-Signature (HMAC-SHA256 over the exact body) as every event — and reports what the receiver answered. Works on a paused endpoint. Requires an Idempotency-Key; send an empty body or {}.

Authentication
Authorization: Bearer vk_…
Required scope
manage:webhooks
Rate limit
Per key. X-RateLimit-* on every response; a 429 carries Retry-After.
Idempotency
Send an Idempotency-Key; a retry with the same key replays the first response for 24h.

Parameters

Parameters of POST /webhooks/subscriptions/{id}/test
NameInTypeDescription
idrequiredpathstring (uuid)The record id. An id that is not in this organisation (including one from another organisation) is a 404.
Idempotency-KeyrequiredheaderstringREQUIRED. A unique string you generate per logical request (a UUID), resent unchanged on every retry. The first response is replayed for 24h (with Idempotency-Replayed: true); the same key with a different body is a 409 idempotency_key_reused.

Request body (application/json)

object

{}

Responses

  • 200 Done. The record as it now stands.
  • 400 Malformed request: a bad limit, a cursor we did not issue, an unknown filter value, or an unsupported version.
  • 401 No key presented, or the key does not verify (revoked, expired, mistyped).
  • 403 The key verified but the plan does not include API access, or the key lacks the resource’s scope.
  • 404 No such record in this organisation.
  • 409 Idempotency conflict (key reused with another body, or still in flight), or a duplicate record (resource_conflict).
  • 413 Body over 64 KB.
  • 415 Body sent with a Content-Type other than application/json.
  • 429 Per-key rate limit exhausted. Wait Retry-After seconds.
  • 500 Something failed on our side. The request_id identifies this exact request.
  • 503 The idempotency store or the module is unavailable; nothing was done. Retry with the same Idempotency-Key.
200 response of POST /webhooks/subscriptions/{id}/test
FieldTypeDescription
object"webhook_test_delivery"
api_version"2026-09-12"
dataWebhookTestDelivery · WebhookTestDelivery
has_morefalse
next_cursornull

Examples

curl

curl -X POST "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000/test" \
  -H "Authorization: Bearer $VOULI_API_KEY" \
  -H "Vouli-Version: 2026-09-12" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript

// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
    'Vouli-Version': '2026-09-12',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(res.status, await res.json());

Python

# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid

req = urllib.request.Request(
    "https://www.vouliiq.com/api/v1/webhooks/subscriptions/00000000-0000-4000-8000-000000000000/test",
    method="POST",
    headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
    data=json.dumps({}).encode(),
)
with urllib.request.urlopen(req) as res:
    print(res.status, json.loads(res.read()))

Webhook events

Outbound events, signed with HMAC-SHA256: verify the timestamped X-Vouli-Signature-V2 (refuse it outside a 300-second window); the older X-Vouli-Signature is still sent. Respond 2xx to acknowledge; anything else is retried with backoff.

  • assessment.completed A maturity assessment finished and a new SOVEREIGN scorecard is available.
  • verdict.changed The org’s headline verdict band changed versus the previous assessment.
  • roadmap.updated The active roadmap or one of its milestones changed.
  • risk.created A new risk was added to the register.
  • risk.severity_changed An existing risk’s severity was re-rated.
  • compliance.posture_changed A new compliance assessment went live and the overall posture, or a regime’s posture, moved versus the previous version (one event per movement; never on the first assessment or when nothing moved).
  • evidence.pack_filed An Evidence Vault pack was assembled and filed (stored ready with every item). manifest_sha256 is the sha256 of the manifest’s canonical JSON (keys sorted).
  • board.vote_opened A board or circular resolution was put to a vote. Ids and timing only — never the motion. Committee votes only when the board allows them.
  • board.vote_closed A vote closed or was cancelled. The outcome is included only when the board allows it (and after any embargo); never tallies, names or the motion.
  • board.signature_requested A board document (minutes, a written resolution, a declaration) was approved and sent for signature. The signer count, never who.
  • board.pack_published A board pack was finalised. Ids and scope only — never its title or content.
  • decision.recorded A decision was recorded in Decision Memory. Ids, status and date only.
  • insight.generated An AI insight was generated and stored. Ids and the module only — flagged ai_generated.
  • kpi.threshold_breached A governed metric's current value crossed into RED. The key, version and threshold — the measured value only when the board allows KPI values (include_kpi_values, default off). No name or description.

Schemas

Error

Every 4xx and 5xx response has exactly this shape.

Error schema
FieldTypeDescription
errorobject

Score

Score schema
FieldTypeDescription
adjusted_scorenumber | null (0–100)Score after finding-pressure adjustment.
completed_atstring (date-time)When the assessment was completed.
confidencenumber | null (0–1)Confidence in the score, 0–1.
idstring (uuid)Assessment id.
methodology_versionstringScoring methodology the score was computed under.
object"score"
overall_scorenumber | null (0–100)Raw SOVEREIGN score, 0–100.
verdictstring | nullone of: CRISIS, EMERGENCY, REMEDIATION, OPTIMIZATION, EXCELLENCE, nullBanded verdict for the score.

Scorecard

Scorecard schema
FieldTypeDescription
adjusted_scorenumber | null (0–100)Score after finding-pressure adjustment.
completed_atstring (date-time)When the assessment was completed.
completenessnumber | null (0–1)Share of questions answered.
confidencenumber | null (0–1)Confidence in the score, 0–1.
evidence_rationumber | null (0–1)Share of answers backed by evidence.
frameworks_appliedarray of stringFrameworks the assessment was mapped against.
idstring (uuid)Assessment id.
methodology_versionstringScoring methodology the score was computed under.
object"scorecard"
overall_scorenumber | null (0–100)Raw SOVEREIGN score, 0–100.
verdictstring | nullone of: CRISIS, EMERGENCY, REMEDIATION, OPTIMIZATION, EXCELLENCE, nullBanded verdict for the score.

Risk

Risk schema
FieldTypeDescription
created_atstring (date-time)When the risk was registered.
descriptionstringWhat the risk is.
dimensionstring | nullSOVEREIGN dimension the risk sits in.
financial_exposure_maxnumber | nullHigh end of modelled exposure, USD.
financial_exposure_minnumber | nullLow end of modelled exposure, USD.
idstring (uuid)Risk row id.
object"risk"
owner_namestring | nullAccountable owner.
residual_severitystring | nullone of: CRITICAL, HIGH, MEDIUM, LOW, nullSeverity after mitigation.
risk_idstringHuman-readable risk reference, unique within the org.
severitystring | nullone of: CRITICAL, HIGH, MEDIUM, LOW, nullInherent severity.
sourcestring | nullHow the risk entered the register.
statusstringone of: Open, InProgress, Mitigated, Accepted, ClosedWhere the risk is in its lifecycle.
target_datestring | null (date)Target mitigation date.

Signal

Signal schema
FieldTypeDescription
as_ofstring (date-time)When this value became the current one.
idstring (uuid)Signal row id.
module_idstringModule that published the signal, e.g. "M1".
numeric_valuenumber | nullThe headline number, when the signal is numeric.
object"signal"
ragstring | nullone of: RED, AMBER, GREEN, nullRed/amber/green band for the signal.
signal_typestringCanonical signal type, e.g. "maturity.overall".
source_versionstring | nullMethodology version the value was produced under.

Roadmap

Roadmap schema
FieldTypeDescription
executive_summarystring | nullBoard-level summary of the plan.
framework_blend?anyFramework weighting used to shape the phases.
generated_atstring (date-time)When the roadmap was generated.
idstring (uuid)Roadmap id.
milestones_countinteger | nullNumber of milestones under this roadmap.
object"roadmap"
phases?anyOrdered phases with their objectives.
version_numberintegerMonotonic version of the roadmap.

Milestone

Milestone schema
FieldTypeDescription
created_atstring (date-time)When the milestone was created.
idstring (uuid)Milestone id.
milestone_keystringStable key for the milestone.
object"milestone"
owner_rolestringRole accountable for delivery.
phasestringRoadmap phase the milestone sits in.
progress_pctnumberPercent complete, 0–100.
rag_statusstringRed/amber/green delivery band.
roadmap_idstring (uuid)Roadmap the milestone belongs to.
sequenceintegerOrder within the phase.
statusstringMilestone status.
target_datestring | null (date)Target completion date.
titlestringMilestone title.

CompliancePosture

CompliancePosture schema
FieldTypeDescription
executive_summarystringBoard-level summary of the posture.
generated_atstring (date-time)When the assessment was generated.
idstring (uuid)Compliance assessment id.
object"compliance_posture"
overall_posturestringOverall compliance posture band.
primary_jurisdictionsarray of stringJurisdictions in scope.
regimes?anyPer-regime posture detail.
version_numberintegerMonotonic version of the assessment.

Obligation

Obligation schema
FieldTypeDescription
created_atstring (date-time)When the obligation was recorded.
idstring (uuid)Obligation id.
jurisdictionstringJurisdiction the obligation arises in.
object"obligation"
obligation_keystringStable key for the obligation.
owner_rolestring | nullRole accountable for the obligation.
priority_bandstringPriority band for sequencing.
regime_idstringRegime identifier, e.g. "eu-ai-act".
regime_namestringHuman-readable regime name.
statusstringWhere the obligation stands.
target_datestring | null (date)Target compliance date.
titlestringWhat must be done.

VendorPortfolio

VendorPortfolio schema
FieldTypeDescription
cross_vendor_risksarray of stringRisks that span more than one vendor.
executive_summarystringBoard-level summary of the portfolio.
generated_atstring (date-time)When the assessment was generated.
idstring (uuid)Vendor assessment id.
object"vendor_portfolio"
portfolio_posturestringOverall posture of the AI vendor portfolio.
recommended_actions?anyRecommended portfolio actions.
version_numberintegerMonotonic version of the assessment.

Vendor

Vendor schema
FieldTypeDescription
ai_rolestring | nullThe vendor’s role in the AI stack.
annual_cost_usdnumber | nullAnnual contract value, USD.
categorystringWhat the vendor supplies.
contract_endstring | null (date)Contract end date.
created_atstring (date-time)When the vendor entered the inventory.
idstring (uuid)Vendor inventory row id.
initial_recommendationstring | nullRecommendation at intake.
initial_risk_bandstringRisk band at intake.
object"vendor"
statusstringWhere the vendor stands in the review cycle.
vendor_keystringStable key for the vendor.
vendor_namestringVendor name.

TalentReadiness

TalentReadiness schema
FieldTypeDescription
build_buy_borrow?anyBuild / buy / borrow mix recommended.
executive_summarystringBoard-level summary of readiness.
generated_atstring (date-time)When the assessment was generated.
idstring (uuid)Talent assessment id.
object"talent_readiness"
overall_readinessstringOverall talent readiness band.
version_numberintegerMonotonic version of the assessment.

TalentGap

TalentGap schema
FieldTypeDescription
created_atstring (date-time)When the gap was recorded.
function_areastringFunction the role sits in.
gap_keystringStable key for the gap.
headcount_neededintegerHeadcount required to close the gap.
idstring (uuid)Talent gap id.
object"talent_gap"
owner_rolestring | nullRole accountable for closing the gap.
priority_bandstringPriority band for sequencing.
recommended_pathstringRecommended way to close the gap.
role_titlestringRole that is missing or under-staffed.
statusstringWhere closing the gap stands.
target_datestring | null (date)Target close date.

Incident

Incident schema
FieldTypeDescription
affected_systemsstring | nullSystems the incident touched.
created_atstring (date-time)When the incident was declared.
descriptionstring | nullLonger account of the incident.
idstring (uuid)Incident id.
incident_typestringone of: model_failure, bias_harm, data_exposure, agent_failure, regulatory_inquiry, shadow_ai_breach, otherKind of AI incident.
jurisdictionsstring | nullJurisdictions whose notification rules apply.
notification_deadlinestring | null (date-time)When the notification is due.
notification_requiredbooleanWhether a regulator or stakeholder must be notified.
notified_atstring | null (date-time)When the notification was recorded as made.
object"incident"
ownerstring | nullAccountable incident owner.
severitystringone of: low, medium, high, criticalSeverity of the incident.
statusstringone of: open, investigating, contained, resolved, post_review, closedWhere the incident is in its lifecycle.
titlestringWhat happened, in one line.
updated_atstring (date-time)When the incident last changed.

Kpi

Kpi schema
FieldTypeDescription
baseline_valuenumber | nullWhere the metric started.
codestringStable code, unique in the organisation (e.g. "O1-KR2") — accepted as key_result_code.
created_atstring (date-time)When the key result was created.
current_as_ofstring | null (date-time)When the current value was recorded.
current_valuenumber | nullLatest actual (the latest period’s check-in).
directionstringone of: increase, decrease, maintainWhich way is good.
idstring (uuid)Key result id — what POST /kpis/checkins takes as key_result_id.
measurement_frequencystringone of: weekly, monthly, quarterly, annualHow often an actual is expected.
metric_namestringWhat is measured.
object"kpi"
objective_idstring (uuid)Objective the key result rolls up to.
statementstringThe key result as written.
statusstringone of: draft, active, achieved, missed, retiredLifecycle state of the key result.
target_valuenumberValue that counts as 100% attainment.
unitstringUnit of the value: %, USD, days, ratio, index, count…
updated_atstring (date-time)When the key result last changed (a new actual included).

Metric

Metric schema
FieldTypeDescription
aggregationstringone of: last, sum, avg, min, max, countHow values roll up over the grain.
approval_basisstringone of: maker_checker, migrationmaker_checker: approved by someone other than its proposer. migration: imported from the KPI register, awaiting review.
approved_atstring | null (date-time)When this version was approved.
created_atstring (date-time)When this version was proposed.
currencystring | nullISO 4217 currency, when the unit is money.
descriptionstring | nullWhat the metric means.
directionstringone of: increase, decrease, maintainWhich way is good.
formulastring | nullHow it is computed (documentary; not executed).
freshness_sla_hoursinteger | nullA value older than this is stale.
grainstringone of: instant, day, week, month, quarter, yearTime grain a value describes.
idstring (uuid)Definition id (this version).
keystringStable metric key, e.g. "revenue.arr" — what /metrics/values?key= takes.
namestringWhat the metric is called.
object"metric"
rag_green_atnumber | nullGREEN threshold (direction-aware).
rag_red_atnumber | nullRED threshold (direction-aware).
steward_rolestring | nullRole accountable for the definition.
unitstringUnit of every value.
valid_maxnumber | nullValues above this are stored flagged (out_of_range).
valid_minnumber | nullValues below this are stored flagged (out_of_range).
versioninteger (1–…)Version of the definition in force. A restatement is a new version.

MetricValue

MetricValue schema
FieldTypeDescription
definition_idstring (uuid)The definition version in force when the value was recorded.
dimension_keystringDimension of the series ("" for the headline series), e.g. "region=EMEA".
idstring (uuid)Value row id.
metric_keystringThe metric this value belongs to.
object"metric_value"
qualitystringone of: ok, out_of_range, unit_mismatch, quarantinedok, or why it is flagged (flagged values are only returned with include_flagged=true).
recorded_atstring (date-time)System time: when Vouli learned the value. A later recorded_at for the same valid_from is a correction.
source_kindstringone of: manual, v1_checkin, mcp_mapping, event_api, import, live_bridge, warehouseHow the value arrived.
source_refstring | nullWhich source: a connection id, a key result id, a user reference.
source_run_idstring | null (uuid)The sync or push run that produced it.
unitstringUnit of the value.
valid_fromstring (date-time)Business time: the as-of instant the value describes.
valuenumberThe value, in the definition’s unit.

Document

Document schema
FieldTypeDescription
chunk_countintegerSearchable passages stored.
created_atstring (date-time)When it was added.
created_viastringone of: dashboard, apiWhether a person or an API key added it.
errorstring | nullWhy processing failed, step-labelled.
external_refstring | nullYour reference, unique in the organisation.
filenamestringThe file name as uploaded.
idstring (uuid)Document id.
mime_typestringThe resolved file type.
object"document"
size_bytesintegerSize in bytes.
statusstringone of: uploading, pending, processing, ready, faileduploading (a file still being sent from the app), pending (awaiting the file or processing), processing, ready (searchable by the AI), failed (see error).
titlestringTitle shown in the knowledge base.
updated_atstring (date-time)When it last changed.
upload?object | nullOnly in the answer to a two-step create: where to upload the file (null in an idempotent replay). Never listed.

BoardVote

BoardVote schema
FieldTypeDescription
closed_atstring | null (date-time)When it closed or was cancelled.
closes_atstring (date-time)When voting closes.
committeestring | nullThe committee code for a committee vote (listed only when the board allows committee data), else null.
created_atstring (date-time)When the vote was created.
idstring (uuid)Vote id.
kindstringone of: meeting, circularA vote at a meeting, or a circular resolution between meetings.
object"board_vote"
opens_atstring (date-time)When voting opened.
outcomestring | nullone of: carried, not_carried, no_quorum, nullPresent only when the board allows outcomes to leave Vouli IQ; else null.
statusstringone of: open, closed, cancelledWhere the vote stands.

BoardDocument

BoardDocument schema
FieldTypeDescription
approved_atstring | null (date-time)When it was sent for signature.
created_atstring (date-time)When it was created.
idstring (uuid)Board document id.
kindstringone of: minutes, written_resolutionMinutes or a written resolution.
object"board_document"
signed_countintegerSignatures recorded.
signer_countintegerSigners required.
statusstringdraft, approved (out for signature), signed or superseded.
versionintegerVersion of the document (a correction is a new version).

BoardPack

BoardPack schema
FieldTypeDescription
created_atstring (date-time)When the pack was created.
idstring (uuid)Board pack id.
object"board_pack"
scopestring"board", or the committee code for a committee pack (listed only when the board allows committee data).
statusstringdraft, finalised, presented or archived.
titlestring | nullNull unless the board allows titles to leave Vouli IQ (titles often name a transaction).
updated_atstring (date-time)When it last changed.

Decision

Decision schema
FieldTypeDescription
created_atstring (date-time)When it was recorded.
decisionstring | nullThe decision text (null with exclude_text=true).
decision_datestring | null (date)When it was decided.
idstring (uuid)Decision id.
object"decision"
ownerstring | nullAccountable owner (a name or role).
rationalestring | nullWhy (null with exclude_text=true).
statusstringactive, superseded, reversed …
supersedes_idstring | null (uuid)The decision this one replaces.
tagsarray of stringTags.
titlestringWhat was decided, in one line.
updated_atstring (date-time)When it last changed.

Insight

Insight schema
FieldTypeDescription
ai_generatedtrueAlways true: this is AI output; review it before relying on it.
generated_atstring (date-time)When it was generated.
idstring (uuid)Insight id.
insight_typestringThe kind of output.
model_card_urlstringWhere the AI governance and model information is published.
modulestringThe module that generated it, e.g. "M6".
object"insight"
quality_scorenumber | nullThe deterministic quality score, 0–1, when computed.
summarystring | nullThe stored headline (≤ 500 characters), when the output has one.

CreateRiskBody

CreateRiskBody schema
FieldTypeDescription
descriptionstringWhat the risk is, in at least 20 characters.
dimension?stringSOVEREIGN dimension, if known. Defaults to OTHER.
likelihoodstringone of: RARE, UNLIKELY, POSSIBLE, LIKELY, ALMOST_CERTAINLikelihood.
mitigation_action?stringWhat is being done about it.
owner_name?stringAccountable owner (a name or role, not a user id).
severitystringone of: CRITICAL, HIGH, MEDIUM, LOWInherent severity.
target_date?stringTarget mitigation date.
titlestringShort name of the risk.

UpdateRiskBody

UpdateRiskBody schema
FieldTypeDescription
likelihood?stringone of: RARE, UNLIKELY, POSSIBLE, LIKELY, ALMOST_CERTAINLikelihood.
mitigation_action?string | nullWhat is being done about it.
owner_name?string | nullAccountable owner (a name or role).
residual_gap_reason?string | nullStanding explanation for a residual below the untreated baseline.
residual_severity?string | nullone of: CRITICAL, HIGH, MEDIUM, LOW, nullSeverity after mitigation.
severity?stringone of: CRITICAL, HIGH, MEDIUM, LOWInherent severity.
severity_change_reason?string | nullRequired when the change LOWERS or clears a severity or likelihood, or closes, accepts or mitigates a CRITICAL risk (at least 20 characters). Recorded as evidence.
status?stringone of: Open, InProgress, Mitigated, Accepted, ClosedLifecycle state.
target_date?string | nullTarget mitigation date.
title?string | nullShort name of the risk.

CreateIncidentBody

CreateIncidentBody schema
FieldTypeDescription
affected_systems?stringSystems the incident touched.
description?stringLonger account.
incident_type?stringone of: model_failure, bias_harm, data_exposure, agent_failure, regulatory_inquiry, shadow_ai_breach, otherKind of incident. Defaults to other.
jurisdictions?stringJurisdictions whose notification rules apply.
notification_deadline?string | null (date-time)When the notification is due (ISO-8601).
notification_required?booleanWhether a regulator or stakeholder must be notified.
owner?stringAccountable incident owner (a name or role).
severity?stringone of: low, medium, high, criticalDefaults to medium.
status?stringone of: open, investigating, contained, resolved, post_review, closedDefaults to open.
titlestringWhat happened, in one line.

UpdateIncidentBody

UpdateIncidentBody schema
FieldTypeDescription
affected_systems?string | nullSystems the incident touched.
description?string | nullLonger account.
incident_type?stringone of: model_failure, bias_harm, data_exposure, agent_failure, regulatory_inquiry, shadow_ai_breach, otherKind of incident.
jurisdictions?string | nullJurisdictions whose notification rules apply.
notification_deadline?string | null (date-time)When the notification is due (ISO-8601).
notification_required?booleanWhether a regulator or stakeholder must be notified.
owner?string | nullAccountable incident owner (a name or role).
severity?stringone of: low, medium, high, criticalSeverity.
status?stringone of: open, investigating, contained, resolved, post_review, closedLifecycle state.
title?stringWhat happened, in one line.

KpiCheckinBatch

KpiCheckinBatch schema
FieldTypeDescription
acceptedintegerHow many data points were recorded (always all of them).
checkinsarray of objectOne entry per data point, in request order.
object"kpi_checkin_batch"

RecordKpiCheckinsBody

RecordKpiCheckinsBody schema
FieldTypeDescription
checkinsarray of object1–500 data points. All are validated before any is written; one bad point refuses the batch.

CreateVendorBody

CreateVendorBody schema
FieldTypeDescription
ai_role?string | nullThe vendor’s role in the AI stack.
annual_cost_usd?number | null (0–…)Annual contract value, USD.
categorystringWhat the vendor supplies.
contract_end?string | nullContract end date.
contract_start?string | nullContract start date.
initial_recommendation?string | nullone of: consolidate, negotiate, maintain, exit, onboard, nullRecommendation at intake.
initial_risk_bandstringone of: CRITICAL, HIGH, MEDIUM, LOWRisk band at intake.
notes?string | nullWorking notes.
renewal_owner_role?string | nullRole accountable for the renewal.
status?stringone of: active, under_review, negotiating, sunsetting, exited, blockedReview status. Defaults to active.
vendor_keystringStable identifier, unique in the organisation (e.g. "openai").
vendor_namestringVendor name.

EventBatch

EventBatch schema
FieldTypeDescription
acceptedintegerEvents written.
duplicatesintegerEvents whose (external_id, type) this source sent before: counted, not re-written.
idstring (uuid)The push run id (it appears in the source's receipts).
object"event_batch"
receivedintegerEvents in the request.
rejectedarray of objectPoints stored but flagged by the metric definition's quality rules.
signals_publishedintegerSignals that changed because of this push (published only on a material change).
unmapped_keysarray of stringMetric keys with no approved definition that accepts the Event API: stored as observations only.

IngestEventsBody

IngestEventsBody schema
FieldTypeDescription
eventsarray of object1–100 events, 500 metric points in total. Validated before anything is written.
strict?booleantrue: a metric key with no approved definition refuses the whole batch (422 unmapped_metric). Default false: it is listed in unmapped_keys.

CreateDocumentBody

CreateDocumentBody schema
FieldTypeDescription
external_ref?stringYour reference, unique in the organisation: a second create with it is a 409 document_exists.
filenamestringFile name, with its extension (the type is resolved from it and the MIME).
mimestringMIME type: PDF, DOCX, PPTX, XLSX, CSV, TXT or Markdown.
sha256stringsha256 of the file (checked before anything is extracted).
sizeinteger (1–20971520)Exact size in bytes (checked against the uploaded file).
title?stringTitle shown in the knowledge base. Defaults to the file name.

ProcessDocumentBody

object

UpdateVendorBody

UpdateVendorBody schema
FieldTypeDescription
annual_cost_usd?number | null (0–…)Annual contract value, USD.
contract_end?string | nullContract end date.
contract_start?string | nullContract start date.
notes?string | nullWorking notes.
renewal_owner_role?string | nullRole accountable for the renewal.
status?stringone of: active, under_review, negotiating, sunsetting, exited, blockedReview status.

WebhookSubscription

WebhookSubscription schema
FieldTypeDescription
activebooleanFalse while the endpoint is paused: nothing is delivered to it.
created_atstring (date-time)When it was registered.
created_viastringone of: dashboard, apiWhether a signed-in admin or an API key registered it.
descriptionstring | nullFree-text label.
event_typesarray of stringEvents delivered to it. Empty means every subscribable event.
idstring (uuid)Subscription id.
object"webhook_subscription"
secret?string | nullThe signing secret — present ONCE, in the response to the create call (and null in an idempotent replay of it). Store it to verify X-Vouli-Signature.
updated_atstring (date-time)When it last changed.
urlstringThe https endpoint deliveries are POSTed to.

CreateWebhookSubscriptionBody

CreateWebhookSubscriptionBody schema
FieldTypeDescription
active?booleanStart paused with false. Defaults to true.
description?string | nullFree-text label.
event_types?array of stringEvents to deliver. Omit or [] for every subscribable event.
urlstring (uri)https endpoint. Private, loopback, link-local and non-https addresses are refused.

UpdateWebhookSubscriptionBody

UpdateWebhookSubscriptionBody schema
FieldTypeDescription
active?booleanfalse pauses deliveries; true resumes them.
description?string | nullFree-text label.
event_types?array of stringReplace the event list. [] for every event.
url?string (uri)New https endpoint (the same address checks apply).

WebhookSubscriptionDeleted

WebhookSubscriptionDeleted schema
FieldTypeDescription
deletedtrue
idstring (uuid)The deleted subscription.
object"webhook_subscription_deleted"

WebhookTestDelivery

WebhookTestDelivery schema
FieldTypeDescription
deliveredbooleanTrue when the receiver answered 2xx.
event_idstringThe id inside the signed body — what a receiver de-duplicates on.
event_type"ping"
idstring (uuid)Delivery id (it appears in the delivery log).
object"webhook_test_delivery"
outcomestringone of: delivered, rejected, unreachable, blockeddelivered (2xx), rejected (the receiver answered non-2xx), unreachable (no answer) or blocked (the address is private or not https).
response_status_codeinteger | nullThe receiver’s HTTP status, when it answered.

TestWebhookSubscriptionBody

object

DocumentDeleted

DocumentDeleted schema
FieldTypeDescription
deletedtrue
idstring (uuid)The deleted document.
object"document_deleted"

AuditEvent

AuditEvent schema
FieldTypeDescription
actionstringWhat happened, e.g. "risk.updated", "api.write.risk".
actorstringWho acted: a user id, a Clerk id, or "system".
categorystringCoarse category for SIEM routing.
idstring (uuid)Audit event id (the SIEM event_id).
metadata?anyEvent detail, as recorded.
object"audit_event"
resource_idstring | nullId of the record acted on.
resource_typestring | nullKind of record acted on.
severityinteger (0–10)CEF-scale severity, 0–10.
timestring (date-time)When the event happened.