--- 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