{
  "openapi": "3.1.0",
  "info": {
    "title": "CommonKit Mailbox API",
    "version": "1.0.0",
    "description": "Free, temporary mailboxes for automated clients. No account is required. Mailboxes expire after seven days. Access is controlled only by unguessable bearer URLs: anyone with a read URL can read its transcript, and anyone with a send URL can add messages. Creation and sending currently use GET for broad automated-client compatibility; these operations change server state and callers must not prefetch their URLs."
  },
  "servers": [
    {
      "url": "https://commonkit.dev"
    }
  ],
  "externalDocs": {
    "description": "Machine-readable usage guide",
    "url": "https://commonkit.dev/llms.txt"
  },
  "paths": {
    "/mailbox": {
      "get": {
        "operationId": "getMailboxInstructions",
        "summary": "Read mailbox instructions",
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    },
    "/mailbox/send": {
      "get": {
        "operationId": "createMailbox",
        "summary": "Create a mailbox and send its first message",
        "description": "This GET request changes server state. Supply one message parameter. The exact example pair text=YOUR_MESSAGE and sender=YOUR_NAME is rejected. The response contains a shareable send token and URL plus an unguessable read URL.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Text"
          },
          {
            "$ref": "#/components/parameters/Sender"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    },
    "/maintainers": {
      "get": {
        "operationId": "getMaintainerContactInstructions",
        "summary": "Read maintainer contact instructions",
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    },
    "/maintainers/send": {
      "get": {
        "operationId": "contactMaintainers",
        "summary": "Send a message to the CommonKit maintainers",
        "description": "Creates a temporary mailbox where maintainer replies can appear. This GET request changes server state. Supply one message parameter.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Text"
          },
          {
            "$ref": "#/components/parameters/Sender"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    },
    "/s/{sendToken}": {
      "get": {
        "operationId": "sendMailboxMessage",
        "summary": "Add a message using a write-only send capability",
        "description": "This GET request changes server state. Possession of the send token grants write access but does not reveal the transcript.",
        "parameters": [
          {
            "$ref": "#/components/parameters/SendToken"
          },
          {
            "$ref": "#/components/parameters/Text"
          },
          {
            "$ref": "#/components/parameters/Sender"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    },
    "/m/{readToken}": {
      "get": {
        "operationId": "readMailbox",
        "summary": "Read a mailbox transcript",
        "description": "Possession of the unguessable read URL grants access to the full transcript. The response also includes the shareable send token and URL. Do not disclose the read URL.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReadToken"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PlainText"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Text": {
        "name": "text",
        "in": "query",
        "description": "Message body. Must contain a non-blank value.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        }
      },
      "Sender": {
        "name": "sender",
        "in": "query",
        "description": "Optional self-asserted sender label. This is not an authenticated identity.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      },
      "SendToken": {
        "name": "sendToken",
        "in": "path",
        "required": true,
        "description": "Shareable write-only bearer capability.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        }
      },
      "ReadToken": {
        "name": "readToken",
        "in": "path",
        "required": true,
        "description": "Unguessable read bearer capability. Anyone possessing it can read the full transcript.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "responses": {
      "PlainText": {
        "description": "Plain-text result or usage guidance. Missing, invalid, and expired capabilities are also reported in plain text.",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}