The Matrix API

Conventions

Every route lives under https://matrix.pratimana.com/api, takes and returns JSON, and — unless marked Anyone — wants Authorization: Bearer <access token>. An access token lasts fifteen minutes; POST /api/tokens with the refresh token answers a fresh pair and retires the old refresh token. The command line does this for you; a page does it through assets/api.js.

Resources are plural nouns and the verbs carry the action: GET reads, POST creates, PATCH changes fields, PUT sets a whole value, DELETE removes. A change of state is a field, not a verb — a program is archived with PATCH /api/programs/{slug} {"status": "archived"}, an invitation is answered with PATCH /api/me/invitations/{id} {"status": "accepted"}, an upload is announced with PATCH /api/attachments/{id} {"uploaded": true}.

Lists answer {"results": [...], "count": n} and page with ?limit= and ?offset= (twenty rows by default). An error answers {"detail": "why"}, or the offending fields by name. A missing credential is 401; a refused one is 403; anything outside the caller's scope — another organization's members, a report they cannot read — is 404, deliberately, so the API does not confirm what exists.

Placeholders are ids unless named otherwise: {id} is a UUID, {slug} a program's slug, {organization_id} the caller's own organization from GET /api/me.

Sessions and tokens

A browser opens a session from its Pratimāna sign-in cookie; a terminal asks for a device code and has it approved in the browser. Both end with a token pair: an access token for the next fifteen minutes and a refresh token that mints the next pair and is spent in the process.

The account

Whoever holds the token. GET /api/me is the first call every client makes: it names the person, their platform tier, whether someone is viewing as them, and the organization they sit in — whose id names the organization routes below.

Organizations

Everything that belongs to one organization, under its id. The id has to be the caller's own (from GET /api/me); another organization's id answers 404, so the segment is an address, never a way in.

Programs

Bounty programs, public and private. Reading is open to anyone who can see the program; the sub-resources are the program team's. Archiving is an edit of status and is the organization owner's alone.

Grid Radar

The directory of programs that are not on Matrix: bounty and disclosure programs hosted on HackerOne, Bugcrowd, Intigriti, YesWeHack, Immunefi or a company's own site, curated by Pratimāna's staff. Read-only, for any signed-in account: a visitor is asked to sign in first. A target is a record and a link out; it never takes a report — the curation routes sit under Platform administration.

Reports

A researcher's findings and what the program does with them. A draft is the researcher's alone until it is sent — POST /api/reports with {"draft": id}. Attachments are uploaded straight to storage against a signed grant and announced when the upload is done.

Advisories and writeups

What the two sides write about a finding once it is public: the organization's advisory and the researcher's writeup. Reading is open to anyone. A piece drafted against a disclosed report is numbered PMA-2026-0042 or PMW-2026-0012 and is addressed under whoever published it — /acme/advisories/PMA-2026-0042, /@alex/writeups/PMW-2026-0012-oauth-takeover. Writing one is the author's alone: an advisory the program's, a writeup the reporter's, subject to the embargo the two agreed at disclosure.

Public and reference data

What a visitor sees without signing in: disclosed reports, the activity feed, the standings, a researcher's profile, the blog, the vulnerability taxonomy, CVSS scoring and the platform's safe-harbor terms.

Platform administration

Pratimāna's own staff, in three tiers: a member reads, an admin acts, and a superadmin alone changes what an account is, deletes accounts, settles money and views as someone else.

Other services

Not for people. The accounts service asks about addresses and single sign-on with the shared internal token; the scanner pushes its verdicts with a Google OIDC token; the scheduler ticks the jobs; the load balancer reads the health check.