{ "openapi": "3.1.0", "info": { "title": "API v3 (alpha)", "version": "2026-08-26", "description": "Our next-generation API. Similar to v2 with JSON types and new endpoints, but still evolving. Although we use the v3 API to power our UI, it is not recommended for production use externally until we reach stable status. Subject to change without deprecation." }, "servers": [ { "url": "https://nz.onetimesecret.com", "description": "Aotearoa New Zealand" }, { "url": "https://ca.onetimesecret.com", "description": "Canada" }, { "url": "https://eu.onetimesecret.com", "description": "Europe" }, { "url": "https://uk.onetimesecret.com", "description": "United Kingdom" }, { "url": "https://us.onetimesecret.com", "description": "United States" }, { "url": "http://localhost:3000", "description": "Development" } ], "paths": { "/api/v3/receipt/recent": { "get": { "operationId": "v3_listReceipts", "summary": "List Receipts", "description": "List receipts for the authenticated user's recent secrets. Returns receipts from the last 30 days, sorted by most recently updated. Supports scoping by organization or custom domain.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } }, "details": { "type": "object", "properties": { "type": { "type": "string" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "since": { "type": "number" }, "now": { "type": "number" }, "has_items": { "type": "boolean" }, "revealed_receipts": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } }, "pending_receipts": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } } }, "required": [ "type", "since", "now", "has_items" ] }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "records" ] } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [ { "sessionAuth": [] } ] } }, "/api/v3/receipt/{identifier}": { "get": { "operationId": "v3_showReceipt", "summary": "Show Receipt", "description": "Retrieve a receipt with full details about a secret's lifecycle, including share and burn URLs, expiration, and current state. On first access, may include the generated secret value briefly.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "secret_state": { "anyOf": [ { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, { "type": "null" } ] }, "natural_expiration": { "type": "string" }, "expiration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiration_in_seconds": { "type": "number" }, "share_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_path": { "type": "string" }, "receipt_path": { "type": "string" }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt_url": { "type": "string" }, "burn_url": { "type": "string" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "natural_expiration", "expiration", "expiration_in_seconds", "share_path", "burn_path", "receipt_path", "share_url", "receipt_url", "burn_url" ] }, "details": { "type": "object", "properties": { "type": { "type": "string", "const": "record" }, "display_lines": { "type": "number" }, "no_cache": { "type": "boolean" }, "secret_realttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "view_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "last_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "can_decrypt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secret_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_secret": { "type": "boolean" }, "show_secret_link": { "type": "boolean" }, "show_receipt_link": { "type": "boolean" }, "show_receipt": { "type": "boolean" }, "show_recipients": { "type": "boolean" }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "type", "display_lines", "no_cache", "has_passphrase", "can_decrypt", "show_secret", "show_secret_link", "show_receipt_link", "show_receipt", "show_recipients" ] } }, "required": [ "record" ] } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ] }, "patch": { "operationId": "v3_updateReceipt", "summary": "Update Receipt", "description": "Update the memo field on a receipt owned by the authenticated user. Returns the updated receipt record.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "secret_state": { "anyOf": [ { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, { "type": "null" } ] }, "natural_expiration": { "type": "string" }, "expiration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiration_in_seconds": { "type": "number" }, "share_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_path": { "type": "string" }, "receipt_path": { "type": "string" }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt_url": { "type": "string" }, "burn_url": { "type": "string" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "natural_expiration", "expiration", "expiration_in_seconds", "share_path", "burn_path", "receipt_path", "share_url", "receipt_url", "burn_url" ] }, "details": { "type": "object", "properties": { "type": { "type": "string", "const": "record" }, "display_lines": { "type": "number" }, "no_cache": { "type": "boolean" }, "secret_realttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "view_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "last_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "can_decrypt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secret_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_secret": { "type": "boolean" }, "show_secret_link": { "type": "boolean" }, "show_receipt_link": { "type": "boolean" }, "show_receipt": { "type": "boolean" }, "show_recipients": { "type": "boolean" }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "type", "display_lines", "no_cache", "has_passphrase", "can_decrypt", "show_secret", "show_secret_link", "show_receipt_link", "show_receipt", "show_recipients" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/v3/receipt/{identifier}/burn": { "post": { "operationId": "v3_receipt_burnSecret", "summary": "Burn Secret", "description": "Permanently destroy a secret before it has been revealed. Requires a passphrase if one was set during creation. Returns the updated receipt confirming the secret has been burned.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "secret_state": { "anyOf": [ { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, { "type": "null" } ] }, "natural_expiration": { "type": "string" }, "expiration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiration_in_seconds": { "type": "number" }, "share_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_path": { "type": "string" }, "receipt_path": { "type": "string" }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt_url": { "type": "string" }, "burn_url": { "type": "string" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "natural_expiration", "expiration", "expiration_in_seconds", "share_path", "burn_path", "receipt_path", "share_url", "receipt_url", "burn_url" ] }, "details": { "type": "object", "properties": { "type": { "type": "string", "const": "record" }, "display_lines": { "type": "number" }, "no_cache": { "type": "boolean" }, "secret_realttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "view_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "last_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "can_decrypt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secret_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_secret": { "type": "boolean" }, "show_secret_link": { "type": "boolean" }, "show_receipt_link": { "type": "boolean" }, "show_receipt": { "type": "boolean" }, "show_recipients": { "type": "boolean" }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "type", "display_lines", "no_cache", "has_passphrase", "can_decrypt", "show_secret", "show_secret_link", "show_receipt_link", "show_receipt", "show_recipients" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "continue": { "type": "string" } } } } } } } }, "/api/v3/secret/conceal": { "post": { "operationId": "v3_concealSecret", "summary": "Conceal Secret", "description": "Store a user-provided secret value and return share metadata including a secret link for the recipient and a receipt link for the creator. The secret can only be retrieved once before it is permanently destroyed.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "receipt": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned" ] }, "secret": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "receipt", "secret", "share_domain" ] }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "object", "properties": { "kind": { "type": "string", "const": "conceal" }, "share_domain": { "type": "string" }, "recipient": { "type": "string" }, "passphrase": { "type": "string" }, "ttl": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "kind", "share_domain", "secret" ] } }, "required": [ "secret" ] } } } } } }, "/api/v3/secret/generate": { "post": { "operationId": "v3_generateSecret", "summary": "Generate Secret", "description": "Generate a random secret value using configurable character sets and length, then return share metadata including a secret link and a receipt link. The generated value can only be retrieved once.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "receipt": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned" ] }, "secret": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "receipt", "secret", "share_domain" ] }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "object", "properties": { "kind": { "type": "string", "const": "generate" }, "share_domain": { "type": "string" }, "recipient": { "type": "string" }, "passphrase": { "type": "string" }, "ttl": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "length": { "type": "integer", "minimum": 4, "maximum": 128 }, "character_sets": { "type": "object", "properties": { "uppercase": { "type": "boolean" }, "lowercase": { "type": "boolean" }, "numbers": { "type": "boolean" }, "symbols": { "type": "boolean" }, "exclude_ambiguous": { "type": "boolean" } } } }, "required": [ "kind", "share_domain" ] } }, "required": [ "secret" ] } } } } } }, "/api/v3/secret/{identifier}": { "get": { "operationId": "v3_showSecret", "summary": "Show Secret", "description": "Return metadata about a secret without revealing its value. Includes state, expiration details, and whether a passphrase is required. Records the access as telemetry on the receipt (#3633); a metadata GET no longer advances the secret's lifecycle state.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "details": { "type": "object", "properties": { "continue": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "show_secret": { "type": "boolean" }, "display_lines": { "type": "number" }, "one_liner": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "continue", "is_owner", "show_secret", "display_lines", "one_liner" ] } }, "required": [ "record" ] } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ] } }, "/api/v3/secret/{identifier}/reveal": { "post": { "operationId": "v3_secret_revealSecret", "summary": "Reveal Secret", "description": "Retrieve and decrypt a secret value. The secret is permanently destroyed immediately after retrieval and cannot be accessed again. Requires a passphrase if one was set during creation. The secret owner is optionally notified when the secret is revealed.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "details": { "type": "object", "properties": { "continue": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "show_secret": { "type": "boolean" }, "display_lines": { "type": "number" }, "one_liner": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "continue", "is_owner", "show_secret", "display_lines", "one_liner" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passphrase": { "type": "string" }, "continue": { "type": "string" } } } } } } } }, "/api/v3/secret/{identifier}/status": { "get": { "operationId": "v3_secret_showSecretStatus", "summary": "Show Secret Status", "description": "Check the current status of a secret by its identifier. Returns the secret's state and expiration details, or an unknown state if the secret does not exist.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "details": { "type": "object", "properties": { "continue": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "show_secret": { "type": "boolean" }, "display_lines": { "type": "number" }, "one_liner": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "continue", "is_owner", "show_secret", "display_lines", "one_liner" ] } }, "required": [ "record" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ] } }, "/api/v3/secret/status": { "post": { "operationId": "v3_listSecretStatus", "summary": "List Secret Status", "description": "Retrieve the status of multiple secrets in a single request. Accepts a comma-separated list of secret identifiers and returns their current state and metadata.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "created", "updated" ] } }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "records" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "identifiers" ] } } } } } }, "/api/v3/guest/secret/conceal": { "post": { "operationId": "v3_guest_concealSecret", "summary": "Conceal Secret", "description": "Store a user-provided secret value and return share metadata including a secret link for the recipient and a receipt link for the creator. The secret can only be retrieved once before it is permanently destroyed.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "receipt": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned" ] }, "secret": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "receipt", "secret", "share_domain" ] }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "object", "properties": { "kind": { "type": "string", "const": "conceal" }, "share_domain": { "type": "string" }, "recipient": { "type": "string" }, "passphrase": { "type": "string" }, "ttl": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "kind", "share_domain", "secret" ] } }, "required": [ "secret" ] } } } } } }, "/api/v3/guest/secret/generate": { "post": { "operationId": "v3_guest_generateSecret", "summary": "Generate Secret", "description": "Generate a random secret value using configurable character sets and length, then return share metadata including a secret link and a receipt link. The generated value can only be retrieved once.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "receipt": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned" ] }, "secret": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "receipt", "secret", "share_domain" ] }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "object", "properties": { "kind": { "type": "string", "const": "generate" }, "share_domain": { "type": "string" }, "recipient": { "type": "string" }, "passphrase": { "type": "string" }, "ttl": { "anyOf": [ { "type": "string", "pattern": "^\\d+$" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "length": { "type": "integer", "minimum": 4, "maximum": 128 }, "character_sets": { "type": "object", "properties": { "uppercase": { "type": "boolean" }, "lowercase": { "type": "boolean" }, "numbers": { "type": "boolean" }, "symbols": { "type": "boolean" }, "exclude_ambiguous": { "type": "boolean" } } } }, "required": [ "kind", "share_domain" ] } }, "required": [ "secret" ] } } } } } }, "/api/v3/guest/secret/{identifier}": { "get": { "operationId": "v3_guest_showSecret", "summary": "Show Secret", "description": "Return metadata about a secret without revealing its value. Includes state, expiration details, and whether a passphrase is required. Records the access as telemetry on the receipt (#3633); a metadata GET no longer advances the secret's lifecycle state.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "details": { "type": "object", "properties": { "continue": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "show_secret": { "type": "boolean" }, "display_lines": { "type": "number" }, "one_liner": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "continue", "is_owner", "show_secret", "display_lines", "one_liner" ] } }, "required": [ "record" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ] } }, "/api/v3/guest/secret/{identifier}/reveal": { "post": { "operationId": "v3_guest_revealSecret", "summary": "Reveal Secret", "description": "Retrieve and decrypt a secret value. The secret is permanently destroyed immediately after retrieval and cannot be accessed again. Requires a passphrase if one was set during creation. The secret owner is optionally notified when the secret is revealed.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "revealed", "burned", "previewed" ] }, "has_passphrase": { "type": "boolean" }, "verification": { "type": "boolean" }, "secret_value": { "type": "string" }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "secret_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" } }, "required": [ "identifier", "key", "shortid", "state", "has_passphrase", "verification", "is_previewed", "is_revealed", "secret_ttl", "lifespan", "created", "updated" ] }, "details": { "type": "object", "properties": { "continue": { "type": "boolean" }, "is_owner": { "type": "boolean" }, "show_secret": { "type": "boolean" }, "display_lines": { "type": "number" }, "one_liner": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "continue", "is_owner", "show_secret", "display_lines", "one_liner" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "passphrase": { "type": "string" }, "continue": { "type": "string" } } } } } } } }, "/api/v3/guest/receipt/{identifier}": { "get": { "operationId": "v3_guest_showReceipt", "summary": "Show Receipt", "description": "Retrieve a receipt with full details about a secret's lifecycle, including share and burn URLs, expiration, and current state. On first access, may include the generated secret value briefly.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "secret_state": { "anyOf": [ { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, { "type": "null" } ] }, "natural_expiration": { "type": "string" }, "expiration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiration_in_seconds": { "type": "number" }, "share_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_path": { "type": "string" }, "receipt_path": { "type": "string" }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt_url": { "type": "string" }, "burn_url": { "type": "string" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "natural_expiration", "expiration", "expiration_in_seconds", "share_path", "burn_path", "receipt_path", "share_url", "receipt_url", "burn_url" ] }, "details": { "type": "object", "properties": { "type": { "type": "string", "const": "record" }, "display_lines": { "type": "number" }, "no_cache": { "type": "boolean" }, "secret_realttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "view_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "last_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "can_decrypt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secret_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_secret": { "type": "boolean" }, "show_secret_link": { "type": "boolean" }, "show_receipt_link": { "type": "boolean" }, "show_receipt": { "type": "boolean" }, "show_recipients": { "type": "boolean" }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "type", "display_lines", "no_cache", "has_passphrase", "can_decrypt", "show_secret", "show_secret_link", "show_receipt_link", "show_receipt", "show_recipients" ] } }, "required": [ "record" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ] } }, "/api/v3/guest/receipt/{identifier}/burn": { "post": { "operationId": "v3_guest_burnSecret", "summary": "Burn Secret", "description": "Permanently destroy a secret before it has been revealed. Requires a passphrase if one was set during creation. Returns the updated receipt confirming the secret has been burned.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "secret_state": { "anyOf": [ { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, { "type": "null" } ] }, "natural_expiration": { "type": "string" }, "expiration": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expiration_in_seconds": { "type": "number" }, "share_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_path": { "type": "string" }, "receipt_path": { "type": "string" }, "share_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receipt_url": { "type": "string" }, "burn_url": { "type": "string" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "natural_expiration", "expiration", "expiration_in_seconds", "share_path", "burn_path", "receipt_path", "share_url", "receipt_url", "burn_url" ] }, "details": { "type": "object", "properties": { "type": { "type": "string", "const": "record" }, "display_lines": { "type": "number" }, "no_cache": { "type": "boolean" }, "secret_realttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "view_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "first_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "last_access": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "can_decrypt": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "secret_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_secret": { "type": "boolean" }, "show_secret_link": { "type": "boolean" }, "show_receipt_link": { "type": "boolean" }, "show_receipt": { "type": "boolean" }, "show_recipients": { "type": "boolean" }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "type", "display_lines", "no_cache", "has_passphrase", "can_decrypt", "show_secret", "show_secret_link", "show_receipt_link", "show_receipt", "show_recipients" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "x-sensitive": true, "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier parameter" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "continue": { "type": "string" } } } } } } } }, "/api/v3/guest/receipts": { "post": { "operationId": "v3_showMultipleReceipts", "summary": "Show Multiple Receipts", "description": "Retrieve multiple receipts in a single request by providing an array of receipt identifiers. Returns up to 25 receipts per request. Useful for checking the status of several secrets at once.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } }, "details": { "type": "object", "properties": { "type": { "type": "string" }, "scope": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "since": { "type": "number" }, "now": { "type": "number" }, "has_items": { "type": "boolean" }, "revealed_receipts": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } }, "pending_receipts": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "shortid": { "type": "string" }, "state": { "type": "string", "enum": [ "new", "shared", "revealed", "burned", "previewed", "expired", "orphaned" ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "type": "number" }, "updated": { "type": "number" }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revealed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "secret_ttl": { "type": "number" }, "receipt_ttl": { "type": "number" }, "lifespan": { "type": "number" }, "secret_shortid": { "type": "string" }, "secret_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, { "type": "null" } ] }, "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_previewed": { "type": "boolean" }, "is_revealed": { "type": "boolean" }, "is_burned": { "type": "boolean" }, "is_destroyed": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "is_orphaned": { "type": "boolean" }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "generate", "conceal" ] }, { "type": "string", "const": "" } ] }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "standard", "incoming" ] }, { "type": "null" } ] }, "show_recipients": { "type": "boolean" } }, "required": [ "identifier", "key", "shortid", "state", "created", "updated", "secret_ttl", "receipt_ttl", "lifespan", "is_previewed", "is_revealed", "is_burned", "is_destroyed", "is_expired", "is_orphaned", "show_recipients" ] } } }, "required": [ "type", "since", "now", "has_items" ] }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "records" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "identifiers" ] } } } } } }, "/api/v3/supported-locales": { "get": { "operationId": "v3_getSupportedLocales", "summary": "Get Supported Locales", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "locales": { "type": "array", "items": { "type": "string" } }, "default_locale": { "type": "string" }, "locale": { "type": "string" } }, "required": [ "locales", "default_locale", "locale" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [] } }, "/api/v3/status": { "get": { "operationId": "v3_systemStatus", "summary": "System Status", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "locale": { "type": "string" } }, "required": [ "status", "locale" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [] } }, "/api/v3/version": { "get": { "operationId": "v3_systemVersion", "summary": "System Version", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "locale": { "type": "string" } }, "required": [ "version", "locale" ] } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [ { "sessionAuth": [] }, { "basicAuth": [] } ] } }, "/api/v3/feedback": { "post": { "operationId": "v3_receiveFeedback", "summary": "Receive Feedback", "description": "Submit a feedback message. Accepts a text message with optional timezone and client version metadata. Available to both authenticated and anonymous users.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "shrimp": { "default": "", "type": "string" }, "record": { "type": "object", "properties": { "msg": { "type": "string", "minLength": 1, "maxLength": 1500 }, "stamp": { "type": "number" } }, "required": [ "msg", "stamp" ] }, "details": { "type": "object", "properties": { "received": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "received" ] } }, "required": [ "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "v3" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" } }, "required": [ "message" ] } } } } } }, "/api/incoming/config": { "get": { "operationId": "incoming_getConfig", "summary": "Get Config", "description": "Retrieve the incoming secrets feature configuration, including whether the feature is enabled, memo length limits, default TTL, and the list of available recipients identified by hash.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "memo_max_length": { "default": 50, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "secret_max_length": { "default": 10000, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recipients": { "default": [], "type": "array", "items": { "type": "object", "properties": { "digest": { "type": "string", "minLength": 1 }, "display_name": { "type": "string" } }, "required": [ "digest", "display_name" ] } }, "default_ttl": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "enabled" ] } }, "required": [ "config" ] } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "incoming" ], "security": [] } }, "/api/incoming/secret": { "post": { "operationId": "incoming_createIncomingSecret", "summary": "Create Incoming Secret", "description": "Create a secret destined for a pre-configured recipient and send them an email notification. The recipient is identified by a hash rather than a raw email address. Returns the receipt and secret metadata on success.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shrimp": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "record": { "type": "object", "properties": { "receipt": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "custid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secret_shortid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipients": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secret_ttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "receipt_ttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lifespan": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "share_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "received": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "burned": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "viewed": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "show_recipients": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_viewed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_received": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_burned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_expired": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_orphaned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_destroyed": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "identifier", "key" ] }, "secret": { "type": "object", "properties": { "identifier": { "type": "string" }, "key": { "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secret_ttl": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lifespan": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "has_passphrase": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "verification": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "identifier", "key" ] } }, "required": [ "receipt", "secret" ] }, "details": { "anyOf": [ { "type": "object", "properties": { "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } }, "required": [ "success", "record" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "incoming" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memo": { "default": "", "type": "string" }, "secret": { "type": "string", "minLength": 1 }, "recipient": { "type": "string", "minLength": 1 } }, "required": [ "secret", "recipient" ] } } } } } }, "/api/incoming/validate": { "post": { "operationId": "incoming_validateRecipient", "summary": "Validate Recipient", "description": "Validate whether a recipient hash corresponds to a configured incoming recipient. Returns true if the hash is recognized, false otherwise. Use this before submitting a secret creation request.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string" }, "valid": { "type": "boolean" } }, "required": [ "recipient", "valid" ] } } } }, "400": { "description": "Bad Request - Invalid request parameters or body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "422": { "description": "Unprocessable Entity - Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier." }, "error_type": { "type": "string", "description": "Machine-readable error class the client branches on (ADR-013, e.g., \"RecordNotFound\")" }, "message": { "type": "string", "description": "Human-readable error message (legacy/V1 shape)" }, "field": { "type": "string", "description": "Field that caused the error, if applicable" }, "error_id": { "type": "string", "description": "Unique error tracking identifier" }, "request_id": { "type": "string", "description": "Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error." } } } } } } }, "tags": [ "incoming" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "minLength": 1 } }, "required": [ "recipient" ] } } } } } } }, "components": { "securitySchemes": { "sessionAuth": { "type": "apiKey", "in": "cookie", "name": "rack.session", "description": "Session-based authentication via browser cookies." }, "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic authentication with username (extid or email) and API token. The user extid can be found on the API Settings page." } }, "schemas": {} }, "tags": [ { "name": "incoming", "description": "Incoming operations" }, { "name": "v3", "description": "V3 operations" } ] }