--- openapi: 3.1.0 info: title: API v2 version: '2026-04-15' description: Our current stable API. JSON-based, with improved consistency and new endpoints compared to v1. Actively maintained and recommended for production use. Receives new features and updates, but breaking changes are avoided or properly deprecated. 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/v2/receipt/recent": get: operationId: v2_listReceipts summary: List Receipts description: Lists receipts (metadata records) for secrets created within the last 30 days. Supports scoping by customer (default), organization, or custom domain. Returns each receipt's state, timestamps, and summary information. 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: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan 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: string has_items: anyOf: - type: string - type: 'null' received: type: array items: type: object properties: identifier: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan notreceived: type: array items: type: object properties: identifier: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan required: - type - since - now 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: - basicAuth: [] "/api/v2/receipt/{identifier}/burn": post: operationId: v2_receipt_burnSecret summary: Burn Secret description: Permanently destroys a secret before its expiration time. Requires the receipt identifier and a passphrase if one was set. Returns the updated receipt record with burn confirmation and related URLs. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} 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/v2/receipt/{identifier}": get: operationId: v2_showReceipt summary: Show Receipt description: Retrieves the receipt (metadata) for a previously created secret. Returns the receipt's state, share and burn URLs, expiration details, and recipient information. For generated secrets viewed shortly after creation, the generated value may be included. The receipt tracks whether the associated secret has been viewed, burned, or expired. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter patch: operationId: v2_updateReceipt summary: Update Receipt description: Updates a receipt's mutable fields. Currently supports setting the memo field (up to 500 characters). Only the receipt owner can perform updates. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} 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/v2/private/recent": get: operationId: v2_private_listReceipts summary: List Receipts description: Lists receipts (metadata records) for secrets created within the last 30 days. Supports scoping by customer (default), organization, or custom domain. Returns each receipt's state, timestamps, and summary information. 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: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan 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: string has_items: anyOf: - type: string - type: 'null' received: type: array items: type: object properties: identifier: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan notreceived: type: array items: type: object properties: identifier: anyOf: - type: string - type: 'null' created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: number receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' required: - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan required: - type - since - now 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 deprecated: true security: - basicAuth: [] "/api/v2/private/{identifier}/burn": post: operationId: v2_private_burnSecret summary: Burn Secret description: Permanently destroys a secret before its expiration time. Requires the receipt identifier and a passphrase if one was set. Returns the updated receipt record with burn confirmation and related URLs. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 deprecated: true x-sensitive: true security: - basicAuth: [] - {} 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/v2/private/{identifier}": get: operationId: v2_private_showReceipt summary: Show Receipt description: Retrieves the receipt (metadata) for a previously created secret. Returns the receipt's state, share and burn URLs, expiration details, and recipient information. For generated secrets viewed shortly after creation, the generated value may be included. The receipt tracks whether the associated secret has been viewed, burned, or expired. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 deprecated: true x-sensitive: true security: - basicAuth: [] - {} parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter patch: operationId: v2_private_updateReceipt summary: Update Receipt description: Updates a receipt's mutable fields. Currently supports setting the memo field (up to 500 characters). Only the receipt owner can perform updates. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 deprecated: true x-sensitive: true security: - basicAuth: [] - {} 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/v2/secret/{identifier}": get: operationId: v2_showSecret summary: Show Secret description: Retrieves a secret's metadata and optionally its decrypted content. When called with continue=true and the correct passphrase, the secret value is returned and the secret is consumed. Without continue, returns only metadata such as whether a passphrase is required. The secret can only be viewed 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: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan details: type: object properties: continue: anyOf: - type: string - type: 'null' is_owner: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' correct_passphrase: anyOf: - type: string - type: 'null' display_lines: anyOf: - type: string - type: 'null' one_liner: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - display_lines required: - record '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter "/api/v2/secret/{identifier}/status": get: operationId: v2_secret_showSecretStatus summary: Show Secret Status description: Checks whether a secret exists and returns its current state without consuming it. Returns the secret's metadata including expiration details, or a state of "unknown" if the secret does not exist. responses: '200': description: Successful response content: application/json: schema: anyOf: - type: object properties: record: type: object properties: state: type: string const: unknown required: - state required: - record - type: object properties: record: type: object properties: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan details: type: object properties: current_expiration: anyOf: - type: number - type: 'null' required: - current_expiration required: - record - details '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter "/api/v2/secret/status": post: operationId: v2_listSecretStatus summary: List Secret Status description: Retrieves the status of multiple secrets in a single request. Accepts a comma-separated list of secret identifiers and returns each secret's current state and metadata. Does not consume or reveal any secret values. 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 created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: - basicAuth: [] - {} requestBody: required: true content: application/json: schema: type: object properties: identifiers: type: array items: type: string required: - identifiers "/api/v2/secret/{identifier}/reveal": post: operationId: v2_secret_revealSecret summary: Reveal Secret description: Retrieves and permanently reveals a secret's content. Requires the secret identifier, a passphrase if one was set, and a continue flag to confirm the reveal. The secret is destroyed immediately upon reveal and cannot be accessed again. Returns the decrypted secret value along with display metadata. 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 created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan details: type: object properties: continue: anyOf: - type: string - type: 'null' is_owner: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' correct_passphrase: anyOf: - type: string - type: 'null' display_lines: anyOf: - type: string - type: 'null' one_liner: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - display_lines required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: - basicAuth: [] - {} 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/v2/secret/generate": post: operationId: v2_generateSecret summary: Generate Secret description: Creates a new secret with a randomly generated value. Accepts optional password generation parameters (length, character sets), TTL, recipient email, and share domain. Returns the receipt and secret records with share URLs. 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 created: type: number updated: type: number key: type: string shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: type: string secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - receipt_ttl - lifespan secret: type: object properties: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: - basicAuth: [] - {} 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/v2/secret/conceal": post: operationId: v2_concealSecret summary: Conceal Secret description: Creates a new secret from user-provided content. Accepts the secret value, an optional passphrase, TTL, recipient email, and share domain. Returns the receipt and secret records with share URLs. 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 created: type: number updated: type: number key: type: string shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: type: string secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - receipt_ttl - lifespan secret: type: object properties: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '401': description: Unauthorized - Authentication required content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '403': description: Forbidden - Insufficient permissions content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: - basicAuth: [] - {} 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/v2/guest/secret/conceal": post: operationId: v2_guest_concealSecret summary: Conceal Secret description: Creates a new secret from user-provided content. Accepts the secret value, an optional passphrase, TTL, recipient email, and share domain. Returns the receipt and secret records with share URLs. 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 created: type: number updated: type: number key: type: string shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: type: string secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - receipt_ttl - lifespan secret: type: object properties: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 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/v2/guest/secret/generate": post: operationId: v2_guest_generateSecret summary: Generate Secret description: Creates a new secret with a randomly generated value. Accepts optional password generation parameters (length, character sets), TTL, recipient email, and share domain. Returns the receipt and secret records with share URLs. 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 created: type: number updated: type: number key: type: string shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: type: string secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - receipt_ttl - lifespan secret: type: object properties: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan 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: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 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/v2/guest/secret/{identifier}": get: operationId: v2_guest_showSecret summary: Show Secret description: Retrieves a secret's metadata and optionally its decrypted content. When called with continue=true and the correct passphrase, the secret value is returned and the secret is consumed. Without continue, returns only metadata such as whether a passphrase is required. The secret can only be viewed 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: identifier: type: string created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan details: type: object properties: continue: anyOf: - type: string - type: 'null' is_owner: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' correct_passphrase: anyOf: - type: string - type: 'null' display_lines: anyOf: - type: string - type: 'null' one_liner: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - display_lines required: - record '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: [] parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter "/api/v2/guest/secret/{identifier}/reveal": post: operationId: v2_guest_revealSecret summary: Reveal Secret description: Retrieves and permanently reveals a secret's content. Requires the secret identifier, a passphrase if one was set, and a continue flag to confirm the reveal. The secret is destroyed immediately upon reveal and cannot be accessed again. Returns the decrypted secret value along with display metadata. 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 created: type: string updated: type: string key: type: string shortid: type: string state: type: string enum: - new - revealed - burned - previewed has_passphrase: anyOf: - type: string - type: 'null' verification: anyOf: - type: string - type: 'null' secret_value: type: string is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' required: - identifier - created - updated - key - shortid - state - secret_ttl - lifespan details: type: object properties: continue: anyOf: - type: string - type: 'null' is_owner: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' correct_passphrase: anyOf: - type: string - type: 'null' display_lines: anyOf: - type: string - type: 'null' one_liner: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - display_lines required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 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/v2/guest/receipt/{identifier}": get: operationId: v2_guest_showReceipt summary: Show Receipt description: Retrieves the receipt (metadata) for a previously created secret. Returns the receipt's state, share and burn URLs, expiration details, and recipient information. For generated secrets viewed shortly after creation, the generated value may be included. The receipt tracks whether the associated secret has been viewed, burned, or expired. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 x-sensitive: true security: [] parameters: - name: identifier in: path required: true schema: type: string description: The identifier parameter "/api/v2/guest/receipt/{identifier}/burn": post: operationId: v2_guest_burnSecret summary: Burn Secret description: Permanently destroys a secret before its expiration time. Requires the receipt identifier and a passphrase if one was set. Returns the updated receipt record with burn confirmation and related URLs. 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 created: type: number updated: type: number key: anyOf: - type: string - type: 'null' shortid: type: string state: type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned custid: anyOf: - type: string - type: 'null' owner_id: anyOf: - type: string - type: 'null' shared: anyOf: - type: string - type: 'null' previewed: anyOf: - type: string - type: 'null' revealed: anyOf: - type: string - type: 'null' burned: anyOf: - type: string - type: 'null' secret_ttl: anyOf: - type: string - type: 'null' receipt_ttl: anyOf: - type: string - type: 'null' lifespan: anyOf: - type: string - type: 'null' secret_shortid: anyOf: - type: string - type: 'null' secret_identifier: anyOf: - type: string - type: 'null' recipients: anyOf: - anyOf: - type: array items: type: string - type: string - type: 'null' share_domain: anyOf: - type: string - type: 'null' has_passphrase: anyOf: - type: boolean - type: 'null' is_previewed: anyOf: - type: string - type: 'null' is_revealed: anyOf: - type: string - type: 'null' is_burned: anyOf: - type: string - type: 'null' is_destroyed: anyOf: - type: string - type: 'null' is_expired: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - type: string - type: 'null' memo: anyOf: - type: string - type: 'null' kind: anyOf: - anyOf: - type: string enum: - generate - conceal - type: string const: '' - type: 'null' received: anyOf: - type: string - type: 'null' viewed: anyOf: - type: string - type: 'null' is_viewed: anyOf: - type: string - type: 'null' is_received: anyOf: - type: string - type: 'null' secret_state: anyOf: - type: string enum: - new - shared - revealed - burned - previewed - expired - orphaned - type: 'null' natural_expiration: type: string expiration_in_seconds: anyOf: - type: string - type: 'null' share_path: type: string burn_path: type: string receipt_path: type: string share_url: type: string receipt_url: type: string burn_url: type: string expiration: type: number required: - identifier - created - updated - shortid - state - secret_ttl - receipt_ttl - lifespan - natural_expiration - expiration_in_seconds - share_path - burn_path - receipt_path - share_url - receipt_url - burn_url - expiration details: type: object properties: type: type: string const: record display_lines: anyOf: - type: string - type: 'null' no_cache: anyOf: - type: string - type: 'null' secret_realttl: anyOf: - type: number - type: 'null' view_count: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' has_passphrase: anyOf: - type: string - type: 'null' can_decrypt: anyOf: - type: string - type: 'null' secret_value: anyOf: - type: string - type: 'null' show_secret: anyOf: - type: string - type: 'null' show_secret_link: anyOf: - type: string - type: 'null' show_receipt_link: anyOf: - type: string - type: 'null' show_receipt: anyOf: - type: string - type: 'null' show_recipients: anyOf: - type: string - type: 'null' is_orphaned: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' is_expired: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' required: - type - display_lines - view_count required: - record '400': description: Bad Request - Invalid request parameters or body content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '422': description: Unprocessable Entity - Validation failed content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 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/v2/supported-locales": get: operationId: v2_getSupportedLocales summary: Get Supported Locales responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean locales: type: array items: type: string default_locale: type: string locale: type: string required: - success - locales - default_locale - locale '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: [] "/api/v2/status": get: operationId: v2_systemStatus summary: System Status responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean status: type: string locale: type: string required: - success - status - locale '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: [] "/api/v2/version": get: operationId: v2_systemVersion summary: System Version responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean version: type: array items: anyOf: - type: string - type: number locale: type: string required: - success - version - locale '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message '500': description: Internal Server Error - Something went wrong content: application/json: schema: type: object properties: error: type: string description: Error type identifier (e.g., "FormError") message: type: string description: Human-readable error message field: type: string description: Field that caused the error, if applicable error_id: type: string description: Unique error tracking identifier required: - message tags: - v2 security: [] components: securitySchemes: sessionAuth: type: apiKey in: cookie name: rack.session description: Session-based authentication via browser cookies. Some endpoints additionally require a specific role (see x-ots-required-role extension on individual operations). basicAuth: type: http scheme: basic description: HTTP Basic authentication with username (email) and API token. Some endpoints additionally require a specific role (see x-ots-required-role extension on individual operations). schemas: {} tags: - name: v2 description: V2 operations