Get Control

Slug

controls-get

Get a specific control by its identifier.

URL Route

Get Control

GET https://www.zavior.ai/api/fco/controls/{id}

Response

404

{ "error": "not_found" }

Error

200

{ "id": "...", "control_id": "...", "organization_id": "...", "status": "Yes", "remark": "..." }

Get a specific control by its identifier.

Get Control

GET https://www.zavior.ai/api/fco/controls/{id}

<h2>Auth</h2><p>Bearer token with <code>controls.read</code>.</p>

Authorize

Slug

oauth-authorize

Start the OAuth Authorization Code (PKCE) flow.

URL Route

Authorize

GET https://www.zavior.ai/api/oauth/authorize

Required Query

client_id
redirect_uri
response_type=code
scope
state
code_challenge, code_challenge_method=S256

Response

Errors

{ "error": "invalid_request" }

Error

302

Redirects to brand sign-in if session is absent; otherwise issues code and redirects to redirect_uri?code=...&state=...

Start the OAuth Authorization Code (PKCE) flow.

Authorize

GET https://www.zavior.ai/api/oauth/authorize

Required Query

client_id
redirect_uri
response_type=code
scope
state
code_challenge, code_challenge_method=S256

<h2>Auth</h2><p>No auth header. User must sign in via brand page if not already authenticated.</p>

UserInfo

Slug

oauth-userinfo

Retrieve subject info for the current access token.

URL Route

UserInfo

GET https://www.zavior.ai/api/oauth/userinfo

Response

401

{ "error": "invalid_token" }

Error

200

{ "sub": "user-id", "email": "user@example.com", "name": "Full Name", "username": "user", "role": "Tech Admin - Admin", "org_name": "Acme", "entity": "...", "exp": 1735707600, "iat": 1735706700 }

Retrieve subject info for the current access token.

UserInfo

GET https://www.zavior.ai/api/oauth/userinfo

<h2>Auth</h2><p>Bearer token.</p>

Token Exchange

Slug

oauth-token-exchange

Issue on‑behalf‑of service token with `act` claim.

URL Route

Token Exchange

POST https://www.zavior.ai/api/oauth/token/exchange

Form

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token_type=urn:ietf:params:oauth:token-type:access_token
subject_token

Response

400

{ "error": "invalid_request" }

Error

200

{ "access_token": "...", "token_type": "Bearer", "expires_in": 900, "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" }

Issue on‑behalf‑of service token with `act` claim.

Token Exchange

POST https://www.zavior.ai/api/oauth/token/exchange

Form

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token_type=urn:ietf:params:oauth:token-type:access_token
subject_token

<h2>Auth</h2><p>Client authentication (Basic) may be required depending on config.</p>

Token

Slug

oauth-token

Exchange code or refresh token for an access token.

URL Route

Token

POST https://www.zavior.ai/api/oauth/token

Form

grant_type=authorization_code with code, code_verifier, client_id, redirect_uri
grant_type=refresh_token with refresh_token

Response

400

{ "error": "invalid_request" }

Error

200

{ "access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 900 }

Exchange code or refresh token for an access token.

Token

POST https://www.zavior.ai/api/oauth/token

Form

grant_type=authorization_code with code, code_verifier, client_id, redirect_uri
grant_type=refresh_token with refresh_token

<h2>Auth</h2><p>Form post (no Bearer required).</p>

Get Policy

Slug

policy-get

Fetch policy metadata (includes signed URLs where available).

URL Route

Get Policy

GET https://www.zavior.ai/api/policies/{id}

Response

404

{ "error": "not_found" }

Error

200

{ "id": "...", "file_data": { "sas_url": "..." }, "title": "..." }

Fetch policy metadata (includes signed URLs where available).

Get Policy

GET https://www.zavior.ai/api/policies/{id}

<h2>Auth</h2><p>Bearer token with <code>controls.read</code>.</p>

Get Evidence

Slug

evidence-get

Fetch evidence metadata (includes signed URLs where available).

URL Route

Get Evidence

GET https://www.zavior.ai/api/evidence/{id}

Response

404

{ "error": "not_found" }

Error

200

{ "id": "...", "file_data": { "sas_url": "...", "file_name": "..." }, "related": { ... } }

Fetch evidence metadata (includes signed URLs where available).

Get Evidence

GET https://www.zavior.ai/api/evidence/{id}

<h2>Auth</h2><p>Bearer token with <code>controls.read</code>.</p>

Create Control

Slug

controls-create

Create a new organization-specific control record.

URL Route

Create Control

POST https://www.zavior.ai/api/fco/controls

Body

{ "control_id": "uuid", "organization_id": "uuid", "status": "Yes", "remark": "..." }

Response

403

{ "error": "insufficient_permissions" }

Error

201

{ "data": { "id": "...", "control_id": "uuid", "organization_id": "uuid" } }

Create a new organization-specific control record.

Create Control

POST https://www.zavior.ai/api/fco/controls

Body

{ "control_id": "uuid", "organization_id": "uuid", "status": "Yes", "remark": "..." }

<h2>Auth</h2><p>Bearer token with <code>controls.write</code>.</p>

Update Control

Slug

controls-update

Update a control (PATCH at gateway → PUT upstream).

URL Route

Update Control

PATCH https://www.zavior.ai/api/fco/controls/{id}

Body

{ "remark": "Updated via MCP" }

The gateway forwards as PUT /api/v1/fco/{id} to IAM/FCO.

Response

403

{ "error": "user_member_cannot_modify_risk_or_review_frequency" }

Error

200

{ "data": { "id": "...", "remark": "Updated via MCP" } }

Update a control (PATCH at gateway → PUT upstream).

Update Control

PATCH https://www.zavior.ai/api/fco/controls/{id}

Body

{ "remark": "Updated via MCP" }

The gateway forwards as PUT /api/v1/fco/{id} to IAM/FCO.

<h2>Auth</h2><p>Bearer token with <code>controls.write</code>.</p>

List Controls

Slug

controls-list

List FCO control records with optional filters and pagination.

URL Route

List Controls

GET https://www.zavior.ai/api/fco/controls

Query Params

frameworkId (string)
riskLevel (low|medium|high|critical)
reviewFrequency (monthly|quarterly|semiannual|annual)
q (string search)
page (number)
pageSize (number)

Response

401

{ "error": "missing_or_invalid_authorization" }

Error

200

[ { "id": "...", "control_id": "...", "organization_id": "...", "status": "Yes", "remark": "..." } ]

List FCO control records with optional filters and pagination.

List Controls

GET https://www.zavior.ai/api/fco/controls

Query Params

frameworkId (string)
riskLevel (low|medium|high|critical)
reviewFrequency (monthly|quarterly|semiannual|annual)
q (string search)
page (number)
pageSize (number)

<h2>Auth</h2><p>Bearer token with <code>controls.read</code>.</p>

OpenAPI Spec

Slug

openapi-spec

Location of the OpenAPI used by ChatGPT Actions and other clients.

URL Route

OpenAPI

GET https://www.zavior.ai/api/openapi/zavior-controls.yaml

Use this URL to import into tools such as ChatGPT Actions.

Response

Error

404 if the spec is not available.

Error

Response

YAML document describing API operations.

Location of the OpenAPI used by ChatGPT Actions and other clients.

OpenAPI

GET https://www.zavior.ai/api/openapi/zavior-controls.yaml

Use this URL to import into tools such as ChatGPT Actions.

<h2>Auth</h2><p>No authentication required.</p>

Authentication (OAuth 2.0)

Slug

authentication-oauth2

How to obtain tokens via Authorization Code + PKCE.

URL Route

OAuth 2.0 (PKCE)

Use the standard Authorization Code with PKCE flow.

Authorize

GET https://www.zavior.ai/api/oauth/authorize

Token

POST https://www.zavior.ai/api/oauth/token

Token Exchange (On-Behalf-Of)

POST https://www.zavior.ai/api/oauth/token/exchange

Response

Error

{ "error": "invalid_grant" }

Error

Token Response

{ "access_token": "...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "...", "scope": "controls.read controls.write" }

How to obtain tokens via Authorization Code + PKCE.

OAuth 2.0 (PKCE)

Use the standard Authorization Code with PKCE flow.

Authorize

GET https://www.zavior.ai/api/oauth/authorize

Token

POST https://www.zavior.ai/api/oauth/token

Token Exchange (On-Behalf-Of)

POST https://www.zavior.ai/api/oauth/token/exchange

<h2>Scopes</h2><ul><li><code>controls.read</code> (read endpoints)</li><li><code>controls.write</code> (create/update endpoints)</li></ul><h2>Bearer</h2><p><code>Authorization: Bearer <access_token></code></p>

API Overview

Slug

api-overview-2c205

High-level overview of the Zavior MCP API surface.

URL Route

API Overview

The Zavior MCP API exposes CRU operations for Framework Control Organisation (FCO) records, OAuth 2.0 endpoints for authorization, and resources for evidence and policies.

Base Host

https://www.zavior.ai/api

OpenAPI

GET https://www.zavior.ai/api/openapi/zavior-controls.yaml

Response

Common Errors

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error

Error

Response Format

All endpoints return JSON; errors include error and optional detail.

High-level overview of the Zavior MCP API surface.

API Overview

The Zavior MCP API exposes CRU operations for Framework Control Organisation (FCO) records, OAuth 2.0 endpoints for authorization, and resources for evidence and policies.

Base Host

https://www.zavior.ai/api

OpenAPI

GET https://www.zavior.ai/api/openapi/zavior-controls.yaml

<h2>Authentication</h2><p>OAuth 2.0 Authorization Code with PKCE. Bearer tokens are required for all endpoints except OpenAPI and /oauth/*.</p>