Show Secret

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.onetimesecret.com/doc/v3-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "v3 - Secrets API (preview) MCP server": {
    "url": "https://api.onetimesecret.com/doc/v3-api/mcp"
  }
}
Close
GET /api/v3/guest/secret/{identifier}

Return metadata about a secret without revealing its value. Includes state, expiration details, and whether a passphrase is required. Records the access as telemetry on the receipt (#3633); a metadata GET no longer advances the secret's lifecycle state.

Path parameters

  • identifier string Required

    The identifier parameter

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • user_id string
    • shrimp string

      Default value is empty.

    • record object Required
      Hide record attributes Show record attributes object
      • identifier string Required
      • key string Required
      • shortid string Required
      • state string Required

        Values are new, revealed, burned, or previewed.

      • has_passphrase boolean Required
      • verification boolean Required
      • secret_value string
      • is_previewed boolean Required
      • is_revealed boolean Required
      • secret_ttl number Required
      • lifespan number Required
      • created number Required
      • updated number Required
    • details object
      Hide details attributes Show details attributes object
      • continue boolean Required
      • is_owner boolean Required
      • show_secret boolean Required
      • display_lines number Required
      • one_liner boolean | null
  • 404 application/json

    Not Found - Resource does not exist

    Hide response attributes Show response attributes object
    • error string

      ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier.

    • error_type string

      Machine-readable error class the client branches on (ADR-013, e.g., "RecordNotFound")

    • message string

      Human-readable error message (legacy/V1 shape)

    • field string

      Field that caused the error, if applicable

    • error_id string

      Unique error tracking identifier

    • request_id string

      Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error.
  • 500 application/json

    Internal Server Error - Something went wrong

    Hide response attributes Show response attributes object
    • error string

      ADR-013: user-facing message (V2+). On frozen V1 this is the error type identifier.

    • error_type string

      Machine-readable error class the client branches on (ADR-013, e.g., "RecordNotFound")

    • message string

      Human-readable error message (legacy/V1 shape)

    • field string

      Field that caused the error, if applicable

    • error_id string

      Unique error tracking identifier

    • request_id string

      Request correlation id; mirrors the x-request-id response header and appears in the server request log. Quote this when reporting an error.
GET /api/v3/guest/secret/{identifier} 
curl \
 --request GET 'https://us.onetimesecret.com/api/v3/guest/secret/{identifier}'
Response examples (200) 
{
  "user_id": "string",
  "shrimp": "",
  "record": {
    "identifier": "string",
    "key": "string",
    "shortid": "string",
    "state": "new",
    "has_passphrase": true,
    "verification": true,
    "secret_value": "string",
    "is_previewed": true,
    "is_revealed": true,
    "secret_ttl": 42.0,
    "lifespan": 42.0,
    "created": 42.0,
    "updated": 42.0
  },
  "details": {
    "continue": true,
    "is_owner": true,
    "show_secret": true,
    "display_lines": 42.0,
    "one_liner": true
  }
}
Response examples (404) 
{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}
Response examples (500) 
{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}