{ "openapi": "3.1.0", "info": { "title": "Riskhold", "version": "1", "summary": "A risk register an agent can draft into, and cannot sign off.", "description": "This schema describes routes and shapes. **What an agent may do, and the reason it will be refused, is served at `GET /api/v1/` and generated from the permission layer itself** \u2014 read that first. Nothing here restates it, deliberately: two descriptions of one boundary is one description too many, and the copy that drifts is the one somebody is coding against.\n\nAn agent may create: company_profile, control, decision_record, risk, risk_control. It may read: controls, decision_records, library_updates, memberships, methodology, profile, risk_controls, risks, scale, scoring_config. It may not create 7 other kinds of entry, may not delete or archive anything, and no endpoint accepts a file." }, "servers": [ { "url": "https://riskhold.co.uk" } ], "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "description": "An agent key, issued on the Agents screen in settings by a workspace owner and shown once." } } }, "paths": { "/api/v1/": { "get": { "summary": "What an agent may and may not do here. Needs no key.", "operationId": "get_root", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/openapi.json": { "get": { "summary": "This document. Needs no key.", "operationId": "get_schema", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/workspaces/": { "post": { "summary": "Create a workspace with no account and no human.", "operationId": "post_workspaces", "description": "Unauthenticated, gated by proof of work and a per-caller cap. Returns a scoped key and a claim URL, and nothing else. **Sends no email** \u2014 hand the claim URL to the person you are working with and they enter their own address. Refusals are 429s carrying Retry-After and, where you already have an unclaimed workspace, its claim URL.", "responses": { "200": { "description": "A challenge." }, "201": { "description": "The workspace, its key and its claim URL." }, "400": { "description": "No valid proof of work. Ask for a challenge first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Capped. Carries Retry-After, and your existing claim URL if you already have an unclaimed workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string", "description": "From POST /api/v1/workspaces/challenge." }, "signature": { "type": "string", "description": "The challenge's signature, returned with it." }, "solution": { "type": "string", "description": "Any string meeting the stated difficulty." }, "name": { "type": "string", "description": "Optional. The company name, if you know it." } } } } } } } }, "/api/v1/workspaces/challenge/": { "post": { "summary": "A proof-of-work challenge. Free to ask for.", "operationId": "post_workspace_challenge", "description": "Stateless to issue and single-use to spend. Difficulty rises with the recent provisioning rate and is capped, so a patient legitimate caller can always still pay it.", "responses": { "200": { "description": "A challenge." }, "201": { "description": "The workspace, its key and its claim URL." }, "400": { "description": "No valid proof of work. Ask for a challenge first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Capped. Carries Retry-After, and your existing claim URL if you already have an unclaimed workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/v1/risks/": { "get": { "summary": "The register. POST to draft a risk, or to correct your own draft.", "operationId": "get_risks", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start. Use `next_offset` from the last page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] }, "post": { "summary": "The register. POST to draft a risk, or to correct your own draft.", "operationId": "create_risk", "parameters": [], "description": "Creates an entry, or corrects one this key drafted and nobody has reviewed. Fields you omit take the workspace's defaults on creation and are left unchanged on a correction. Send an Idempotency-Key so a retry cannot duplicate the entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Only when correcting your own unreviewed draft." }, "title": { "type": "string", "description": "Required on creation." }, "description": { "type": "string" }, "category": { "type": "string" }, "owner": { "type": "string", "description": "A membership id from /memberships/." }, "inherent_likelihood": { "type": "integer", "description": "1 to 5, before controls." }, "inherent_impact": { "type": "integer", "description": "1 to 5, before controls." }, "appetite_band": { "type": "string", "description": "Highest band acceptable for this risk." }, "treatment": { "type": "string", "description": "mitigate, accept, transfer or avoid." }, "treatment_justification": { "type": "string", "description": "Required for anything other than mitigate." }, "treatment_reference": { "type": "string", "description": "Required for transfer and avoid." }, "treatment_deadline": { "type": "string", "description": "Required for avoid. YYYY-MM-DD." } } } } } }, "responses": { "201": { "description": "Created." }, "200": { "description": "An existing draft was corrected." }, "403": { "description": "Refused by one of the three guarantees. The code names which: authorship, human_judgement or no_deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "This Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "No endpoint accepts a file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Validation failed. `fields` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/risks/{pk}/": { "get": { "summary": "One risk, with both scores and its authorship.", "operationId": "get_risk_detail", "parameters": [ { "name": "pk", "in": "path", "required": true, "description": "The entry's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/controls/": { "get": { "summary": "The control library. POST to draft a control.", "operationId": "get_controls", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start. Use `next_offset` from the last page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] }, "post": { "summary": "The control library. POST to draft a control.", "operationId": "create_control", "parameters": [], "description": "Creates an entry, or corrects one this key drafted and nobody has reviewed. Fields you omit take the workspace's defaults on creation and are left unchanged on a correction. Send an Idempotency-Key so a retry cannot duplicate the entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Only when correcting your own unreviewed draft." }, "name": { "type": "string", "description": "Required on creation." }, "description": { "type": "string" }, "effectiveness_level": { "type": "integer", "description": "1 to 5, anchored in evidence." }, "evidence_note": { "type": "string", "description": "What you could show an auditor today." }, "default_axis": { "type": "string", "description": "likelihood or impact." }, "last_assessed": { "type": "string", "description": "YYYY-MM-DD." } } } } } }, "responses": { "201": { "description": "Created." }, "200": { "description": "An existing draft was corrected." }, "403": { "description": "Refused by one of the three guarantees. The code names which: authorship, human_judgement or no_deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "This Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "No endpoint accepts a file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Validation failed. `fields` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/controls/{pk}/": { "get": { "summary": "One control, with its effectiveness rating and evidence note.", "operationId": "get_control_detail", "parameters": [ { "name": "pk", "in": "path", "required": true, "description": "The entry's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/risk-controls/": { "get": { "summary": "Links between risks and controls. Narrow with ?risk= or ?control=. POST to attach a control to a risk.", "operationId": "get_risk_controls", "parameters": [ { "name": "risk", "in": "query", "required": false, "description": "Only links belonging to this risk.", "schema": { "type": "string" } }, { "name": "control", "in": "query", "required": false, "description": "Only links using this control.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start. Use `next_offset` from the last page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] }, "post": { "summary": "Links between risks and controls. Narrow with ?risk= or ?control=. POST to attach a control to a risk.", "operationId": "create_risk_control", "parameters": [], "description": "Creates an entry, or corrects one this key drafted and nobody has reviewed. Fields you omit take the workspace's defaults on creation and are left unchanged on a correction. Send an Idempotency-Key so a retry cannot duplicate the entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Only when correcting your own unreviewed draft." }, "risk": { "type": "string", "description": "Required on creation." }, "control": { "type": "string", "description": "Required on creation." }, "relevance": { "type": "string", "description": "How much this control holds this risk down." }, "reduces": { "type": "string", "description": "likelihood or impact \u2014 not both." }, "rationale": { "type": "string", "description": "Why it applies to this risk." } } } } } }, "responses": { "201": { "description": "Created." }, "200": { "description": "An existing draft was corrected." }, "403": { "description": "Refused by one of the three guarantees. The code names which: authorship, human_judgement or no_deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "This Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "No endpoint accepts a file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Validation failed. `fields` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/risk-controls/{pk}/": { "get": { "summary": "One link, including which axis it reduces.", "operationId": "get_risk_control_detail", "parameters": [ { "name": "pk", "in": "path", "required": true, "description": "The entry's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/decision-records/": { "get": { "summary": "Pointers to where decisions are written down. POST to file one. Riskhold never holds the document itself.", "operationId": "get_decision_records", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start. Use `next_offset` from the last page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] }, "post": { "summary": "Pointers to where decisions are written down. POST to file one. Riskhold never holds the document itself.", "operationId": "create_decision_record", "parameters": [], "description": "Creates an entry, or corrects one this key drafted and nobody has reviewed. Fields you omit take the workspace's defaults on creation and are left unchanged on a correction. Send an Idempotency-Key so a retry cannot duplicate the entry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Only when correcting your own unreviewed draft." }, "title": { "type": "string", "description": "Required on creation." }, "kind": { "type": "string", "description": "minutes, paper, email, ticket or other." }, "forum": { "type": "string", "description": "Who decided \u2014 the committee, the meeting." }, "record_date": { "type": "string", "description": "The date on the document. Not in the future." }, "location": { "type": "string", "description": "In words, for somebody who cannot follow a link." }, "url": { "type": "string", "description": "Optional permalink. http or https only." }, "summary": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created." }, "200": { "description": "An existing draft was corrected." }, "403": { "description": "Refused by one of the three guarantees. The code names which: authorship, human_judgement or no_deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "This Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "No endpoint accepts a file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Validation failed. `fields` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/decision-records/{pk}/": { "get": { "summary": "One decision record.", "operationId": "get_decision_record_detail", "parameters": [ { "name": "pk", "in": "path", "required": true, "description": "The entry's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/memberships/": { "get": { "summary": "Who is in this workspace, so a risk can be given an owner.", "operationId": "get_memberships", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50, capped at 200.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Where to start. Use `next_offset` from the last page.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/profile/": { "get": { "summary": "The company profile, its questions, and the proposal waiting for a person. POST to answer it.", "operationId": "get_profile", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] }, "post": { "summary": "The company profile, its questions, and the proposal waiting for a person. POST to answer it.", "operationId": "create_company_profile", "parameters": [], "description": "Answers the company profile, merged into the answers already given. Saving answers that change nothing writes nothing and returns 200. The response carries the proposal the answers imply, which a person decides on at its `review_url` \u2014 this endpoint never adds to the register. Sending quick-check answers that differ from the ones a person gave is refused with human_judgement. Send an Idempotency-Key so a retry cannot save twice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "type": "object", "description": "Question id \u2192 option tag, or a list of tags where the question is multi-choice. GET /api/v1/profile/ lists both. Questions left out keep their answer; null clears one. Required." } } } } } }, "responses": { "201": { "description": "Created." }, "200": { "description": "An existing draft was corrected." }, "403": { "description": "Refused by one of the three guarantees. The code names which: authorship, human_judgement or no_deletion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "This Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "415": { "description": "No endpoint accepts a file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Validation failed. `fields` names each one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/library/updates/": { "get": { "summary": "The library's monthly releases: what changed, which entries are for this company and why, the dates coming up, and the rules its profile may lead to.", "operationId": "get_library_updates", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/methodology/": { "get": { "summary": "The scoring rules as data, so a score matches the engine's.", "operationId": "get_methodology", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/scoring-config/": { "get": { "summary": "The weights in force, and the version stamped onto scores.", "operationId": "get_scoring_config", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } }, "/api/v1/scale/": { "get": { "summary": "What 1 to 5 mean in this company's own money and hours.", "operationId": "get_scale", "parameters": [], "responses": { "200": { "description": "The requested resource." }, "401": { "description": "No valid agent key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Not in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Rate limited. Carries Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "security": [ { "agentKey": [] } ] } } } }