Reveal 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

{
  "v3 - Secrets API (preview) MCP server": {
    "url": "https://api.onetimesecret.com/doc/v3-api/mcp"
  }
}

POST /api/v3/secret/{identifier}/reveal

Session auth

Retrieve and decrypt a secret value. The secret is permanently destroyed immediately after retrieval and cannot be accessed again. Requires a passphrase if one was set during creation. The secret owner is optionally notified when the secret is revealed.

Path parameters

identifier string Required

The identifier parameter

application/json

Body Required

passphrase string
continue string

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
400 application/json

Bad Request - Invalid request parameters or body
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.
401 application/json

Unauthorized - Authentication required
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.
403 application/json

Forbidden - Insufficient permissions
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.
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.
422 application/json

Unprocessable Entity - Validation failed
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.
429 application/json

Too Many Requests - Rate limit exceeded
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.

POST /api/v3/secret/{identifier}/reveal

curl \
 --request POST 'http://localhost:3000/api/v3/secret/{identifier}/reveal' \
 --cookie "rack.session=$API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"passphrase":"string","continue":"string"}'

Request examples

{
  "passphrase": "string",
  "continue": "string"
}

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 (400)

{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}

Response examples (401)

{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}

Response examples (403)

{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}

Response examples (404)

{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}

Response examples (422)

{
  "error": "string",
  "error_type": "string",
  "message": "string",
  "field": "string",
  "error_id": "string",
  "request_id": "string"
}

Response examples (429)

{
  "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"
}