Create Incoming 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/incoming/secret

Create a secret destined for a pre-configured recipient and send them an email notification. The recipient is identified by a hash rather than a raw email address. Returns the receipt and secret metadata on success.

application/json

Body Required

memo string

Default value is empty.
secret string Required

Minimum length is 1.
recipient string Required

Minimum length is 1.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- success boolean Required
- message string | null
- shrimp string | null
- custid string | null
- record object Required
  
  Hide record attributes Show record attributes object
  
  receipt object Required
  
  Hide receipt attributes Show receipt attributes object
  
  identifier string Required
  
  key string Required
  
  custid string | null
  
  owner_id string | null
  
  state string | null
  
  secret_shortid string | null
  
  shortid string | null
  
  memo string | null
  
  recipients string | null
  
  secret_ttl number | null
  
  receipt_ttl number | null
  
  lifespan number | null
  
  share_domain string | null
  
  created number | null
  
  updated number | null
  
  shared number | null
  
  received number | null
  
  burned number | null
  
  viewed number | null
  
  show_recipients boolean | null
  
  is_viewed boolean | null
  
  is_received boolean | null
  
  is_burned boolean | null
  
  is_expired boolean | null
  
  is_orphaned boolean | null
  
  is_destroyed boolean | null
  
  has_passphrase boolean | null
  
  secret object Required
  
  Hide secret attributes Show secret attributes object
  
  identifier string Required
  
  key string Required
  
  state string | null
  
  shortid string | null
  
  secret_ttl number | null
  
  lifespan number | null
  
  has_passphrase boolean | null
  
  verification boolean | null
  
  created number | null
  
  updated number | null
- details object | null
  
  Hide details attributes Show details attributes object | null
  
  memo string | null
  
  recipient string | 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.
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.
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/incoming/secret

curl \
 --request POST 'https://nz.onetimesecret.com/api/incoming/secret' \
 --header "Content-Type: application/json" \
 --data '{"memo":"","secret":"string","recipient":"string"}'

Request examples

{
  "memo": "",
  "secret": "string",
  "recipient": "string"
}

Response examples (200)

{
  "success": true,
  "message": "string",
  "shrimp": "string",
  "custid": "string",
  "record": {
    "receipt": {
      "identifier": "string",
      "key": "string",
      "custid": "string",
      "owner_id": "string",
      "state": "string",
      "secret_shortid": "string",
      "shortid": "string",
      "memo": "string",
      "recipients": "string",
      "secret_ttl": 42.0,
      "receipt_ttl": 42.0,
      "lifespan": 42.0,
      "share_domain": "string",
      "created": 42.0,
      "updated": 42.0,
      "shared": 42.0,
      "received": 42.0,
      "burned": 42.0,
      "viewed": 42.0,
      "show_recipients": true,
      "is_viewed": true,
      "is_received": true,
      "is_burned": true,
      "is_expired": true,
      "is_orphaned": true,
      "is_destroyed": true,
      "has_passphrase": true
    },
    "secret": {
      "identifier": "string",
      "key": "string",
      "state": "string",
      "shortid": "string",
      "secret_ttl": 42.0,
      "lifespan": 42.0,
      "has_passphrase": true,
      "verification": true,
      "created": 42.0,
      "updated": 42.0
    }
  },
  "details": {
    "memo": "string",
    "recipient": "string"
  }
}

Response examples (400)

{
  "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 (500)

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