Platform API (/v1)

The Platform API is Waafir's versioned HTTP interface. Use it to read and manage your organisation from your own systems. It covers your team (invite members, change roles, remove them), access grants on data rooms, folders, files, Q&A, data room chat and agents, activity and per-counterparty engagement, and portfolio monitoring.

It is a separate surface from Waafir's MCP servers, which expose the same platform to AI clients as tools. Both authenticate with the same personal access tokens.

Base URL

Every endpoint sits under:

https://app.waafir.io/api/v1

The endpoints reference lists each one by its full path, for example GET /api/v1/team.

Your first call

1. Issue a token. In Waafir, open Add-ons → Connect and issue a personal access token. A read token is enough to start. Copy the value, which begins with waafir_pat_. It is shown only once.
2. Ask who you are. GET /api/v1/session echoes the identity and organisation the token acts as. Use it to check that a token works before you build on it:

curl -s https://app.waafir.io/api/v1/session \
  -H "Authorization: Bearer $WAAFIR_TOKEN"

{
  "orgId": "…",
  "userId": "…",
  "email": "you@example.com",
  "orgRole": "admin",
  "authMethod": "pat",
  "principalType": "user"
}

A 401 means the token is missing, mistyped, expired or revoked. Other refusals usually carry a machine-readable code, explained on the error codes page. Some carry none, so always fall back to the HTTP status.

How the reference is built

The endpoints and error codes pages are generated from the platform's own route tree every time this site is published. They are not written by hand. A production release builds them from the same commit as the app, so they list the routes that release serves, with the role gate and token scope each endpoint requires and the query parameters it accepts. Their error lists are a known minimum, not exhaustive: an endpoint can return codes the generator cannot see, so handle unlisted errors by HTTP status.

Versioning

/v1 is additive within its version. Waafir may add response fields and optional request parameters. It does not remove or retype an existing field, or remove an endpoint, within /v1. A breaking change ships under a new version prefix. Write clients that ignore fields they do not recognise.

Where to go next

• Authentication: tokens, scopes, the role ceiling and data-room-restricted tokens.
• Endpoints: every endpoint, grouped by area.
• Error codes: the known refusals and what to do about them.
• Loan API reference and the cookbook: the request and response contract for portfolio-monitoring data ingestion.