User guide Developer guidePlatform REST API

Developer guide

Platform REST API

Authenticate with a token and read or write your governance data over REST.

Platform REST API

The VerifyWise platform exposes a REST API for reading and writing your governance data: projects, risks, vendors, models, tasks, evidence, policies and more. Every endpoint lives under /api and authenticates with a bearer token you create in the app.

This article covers the basics that apply to every endpoint: the base URL, how to authenticate, the response shape and the current limits. For the full endpoint catalog, use the interactive API reference described below.

Agent Control has its own API

If you are governing an AI agent’s tool calls, you want the Agent Control hook API instead, not these endpoints. See the API reference in this guide.

Base URL

All endpoints are mounted under the /api prefix. The host depends on where VerifyWise runs. For a local install the default is:

bash

http://localhost:3000/api

On a hosted deployment, replace the host with your own domain. Endpoint paths keep their casing exactly as defined. For example, project risks are served at /api/projectRisks, not /api/project-risks.

Interactive API reference

VerifyWise serves a live OpenAPI (Swagger) reference that lists every endpoint, its parameters and its response schema. Open it in a browser at:

bash

http://localhost:3000/api/docs

The spec is OpenAPI 3.0. Use it as the source of truth for the full endpoint list; this article only covers the cross-cutting rules.

Authentication

Every request must carry a bearer token in the Authorization header.

bash

Authorization: Bearer <your-token>

You create tokens in the app under Settings → API keys. Only Admin users can create them, and an organization may hold up to 10 active tokens at a time. A token carries the role of the user who created it.

Create a token

Tokens can also be created through the API itself (Admin only). Send a name and an expiry in days:

bash

curl -X POST "http://localhost:3000/api/tokens" \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-pipeline","expires_in_days":90}'

The raw token is shown once

The full token is returned only in the create response, in the data.token field. It is stored as a hash and can never be retrieved again. Copy it immediately; if you lose it, create a new one.

List, revoke and delete tokens

Method & path	Description
GET /api/tokens	List the organization’s tokens with status and last-used time. The token value itself is never returned.
POST /api/tokens	Create a token (Admin only). Returns the raw token once.
POST /api/tokens/:id/revoke	Revoke a token. It stops working immediately and is kept, marked revoked, for your records.
DELETE /api/tokens/:id	Permanently delete a token row.

Revoking takes effect immediately

A revoked token is rejected on its next request, before its expiry date. Revoke a token the moment it may be compromised rather than waiting for it to expire.

Response shape

Responses use a consistent envelope: a short message and a data field that holds the payload.

json

{
  "message": "OK",
  "data": {
    "id": 1,
    "name": "ci-pipeline",
    "expires_at": "2027-06-18T00:00:00.000Z"
  }
}

Client errors (4xx) use the same envelope, with data carrying the detail:

json

{
  "message": "Bad Request",
  "data": "expires_in_days is required"
}

Server errors (5xx) use an error field instead of data:

json

{
  "message": "Internal Server Error",
  "error": "..."
}

Status codes

Code	Meaning
200 / 201	Success. 201 is returned when a resource is created.
400	Bad request: missing or invalid input.
401	Missing, invalid, expired or revoked token.
403	Authenticated, but the token’s role is not allowed to perform this action.
404	Resource not found.
500	Server error.

Limits to know about

Two things work differently from what you might expect. Both are easy to design around once you know about them.

List endpoints are not paginated

List endpoints (for example GET /api/projectRisks, GET /api/vendors) return every matching row for your organization. There are no limit, offset or page parameters. Some lists accept a filter parameter (for example active, deleted or all on risks), but expect to receive the full set and handle large responses on your side.

Most CRUD routes are not rate limited

Rate limiting is applied to some route groups, such as authentication, file, intake-form and detection-scan routes, but not to the main resource (CRUD) routes. Do not treat the absence of a limit as a licence to hammer the API; keep request volumes reasonable, as limits may be added later.

Multi-tenancy

Every request is scoped to the organization of the token that made it. You only ever see and modify your own organization’s data; there is no cross-organization access through these endpoints.

Working with resources

The CRUD pattern for projects, risks, vendors and more.

Developer guide

What the developer guide covers today.

API reference

The separate hook API for governing an agent’s tool calls.

PreviousAPI reference

NextWorking with resources

Platform REST API