{ "openapi": "3.1.0", "info": { "title": "Withheld Public API", "version": "1.0.0", "description": "REST API for embedding Withheld exposure scans, triggering opt-out requests, and pulling status into a customer-owned product. Bearer-token authenticated; mint a key from /dashboard/api-keys." }, "servers": [ { "url": "/api/v1", "description": "Current host" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "wk_<32 hex>" } }, "schemas": { "Envelope": { "type": "object", "properties": { "data": {}, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "data" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": true } }, "required": [ "error" ] }, "Profile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "EU", "UK", "CH", "US", "CA", "AU", "NZ" ] } }, "locale": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProfileInput": { "type": "object", "required": [ "label", "jurisdictions" ], "properties": { "label": { "type": "string", "maxLength": 200 }, "full_name": { "type": "string", "maxLength": 200 }, "aliases": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "phones": { "type": "array", "items": { "type": "string" } }, "addresses": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "EU", "UK", "CH", "US", "CA", "AU", "NZ" ] } }, "locale": { "type": "string", "maxLength": 16 }, "date_of_birth": { "type": "string" } } }, "OptOutRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "profile_id": { "type": "string", "format": "uuid" }, "broker_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "submitting", "submitted", "awaiting_confirmation", "confirmed", "verified_removed", "failed_retryable", "needs_manual", "rejected", "reappeared" ] }, "legal_basis": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true }, "next_recheck_at": { "type": "string", "format": "date-time", "nullable": true }, "attempt_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Broker": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "website": { "type": "string", "nullable": true }, "opt_out_method": { "type": "string", "enum": [ "email", "web_form", "api", "manual" ] }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "attempts": { "type": "integer" }, "successes": { "type": "integer" }, "success_pct": { "type": "integer", "nullable": true, "description": "null when < 5 attempts in last 180d" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Token is valid but lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "429 — rate limit exceeded. Honour the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/profiles": { "get": { "summary": "List profiles", "responses": { "200": { "description": "Profile list (id + label + jurisdictions; PII intentionally omitted)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "summary": "Create a profile", "description": "Requires `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileInput" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/profiles/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get a profile", "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Partial-update a profile", "description": "Only the fields you send are touched. Requires `write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileInput" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/requests": { "get": { "summary": "List opt-out requests", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "profile_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 500 } } ], "responses": { "200": { "description": "Request list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Trigger a new opt-out request", "description": "Creates a `queued` row for {profile_id, broker_id}. Requires `write` scope and an active account-wide mandate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_id", "broker_id" ], "properties": { "profile_id": { "type": "string", "format": "uuid" }, "broker_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/requests/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get a request + its event timeline", "responses": { "200": { "description": "Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/requests/{id}/certificate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Certificate-of-removal PDF", "description": "Only returns 200 when the request is in `verified_removed`. Otherwise 400.", "responses": { "200": { "description": "PDF binary", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/brokers": { "get": { "summary": "List active brokers + success rates", "parameters": [ { "name": "jurisdiction", "in": "query", "schema": { "type": "string", "enum": [ "EU", "UK", "CH", "US", "CA", "AU", "NZ" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 1000 } } ], "responses": { "200": { "description": "Broker list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/exposure-scan": { "post": { "summary": "Aggregate exposure scan", "description": "Returns the count of brokers covering the given regions. Read scope.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "EU", "UK", "CH", "US", "CA", "AU", "NZ" ] } } } } } } }, "responses": { "200": { "description": "Scan result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } } }