# Riskhold

> A risk register that keeps the judgement attributable to a person. An agent can
> read everything in a workspace and draft into it. It cannot accept a risk, record a
> review, change the scoring methodology, or delete anything.

## Start here

- [Capability document](https://riskhold.co.uk/api/v1/): what you may and may not do, as JSON.
  Needs no key. Generated from the permission layer itself, so it cannot describe a
  rule we do not enforce. **Read this first.**
- [OpenAPI schema](https://riskhold.co.uk/api/v1/openapi.json): routes and shapes. Needs no key.
- [For humans](https://riskhold.co.uk/docs/agents/): the same boundary in prose, for whoever is
  deciding whether to let you write here.
- [How Riskhold works](https://riskhold.co.uk/how-it-works.md): the method, as markdown. The
  library, scoring, records, control exceptions and reviews, with a glossary.

## What you can do

- Read: controls, decision_records, library_updates, memberships, methodology, profile, risk_controls, risks, scale, scoring_config
- Create: company_profile, control, decision_record, risk, risk_control
- Answer the company profile at `/api/v1/profile/`: what the company does, the data
  it holds, the tools it runs on. Riskhold's library proposes risks from the answers
  and a person decides on them. You cannot answer its quick checks — those are a
  person's statement about a control.
- Correct: your own drafts, until a person has confirmed one. POST with an `id`;
  there is no PUT or PATCH. Omitted fields keep their current value.
- Delete: nothing, ever, including archiving. Refused by a database trigger as well
  as by the API.
- Upload: nothing. No endpoint accepts a file. To record where a document lives,
  create a decision record naming its title, date and location.

There are 7 kinds of entry you cannot create, each because it states what
a *person* decided. The capability document lists every one with its reason.

## If you have no account

You can create a workspace without one, draft a register into it, and hand a human a
link to claim it.

1. `POST /api/v1/workspaces/challenge` — a proof-of-work challenge. Free to ask for.
2. Solve it. About a second of CPU at the usual difficulty.
3. `POST /api/v1/workspaces` with the challenge, its signature and your solution.
   You get a scoped key and a claim URL.
4. Answer the company profile (`GET`, then `POST /api/v1/profile/`) if you know the
   company. The library's suggestions wait for the person who claims the workspace;
   draft what they do not cover — up to 100 risks and 100 controls
   before it is claimed.
5. **Give the claim URL to the person you are working with.** They enter their own
   email and become the owner.

We send no email at any point before that. We are not given anybody's address and do
not want one — do not offer us one.

Limits worth knowing before you hit them: 3 workspaces per caller
per day. An unclaimed workspace is deleted after 5 days, or after
30 minutes if nothing is ever drafted into it.

## How we refuse

Every refusal is JSON with a `code` and a sentence: `{"error": {"code": "...",
"message": "..."}}`. Three of the codes name a guarantee rather than a status —
retrying those will always fail the same way, and the answer is a different action or
a message to the person you are working with.

Send an `Idempotency-Key` header on any POST. A retry carrying the same key returns
the original response instead of creating a second entry. This matters more here than
in most places: you cannot delete the duplicate you would otherwise leave behind.

## What we do not do

We never call a model on your behalf. No provider integration, no keys held, no
prompts shipped. Riskhold is driven by an agent the customer already runs.