{
  "openapi": "3.1.0",
  "info": {
    "title": "didtheyopen API",
    "version": "1.0.0",
    "summary": "Open tracking for the email your agent already sends from your Gmail or Outlook.",
    "description": "REST API for email open tracking. An open means a mail client loaded the tracking image. It is not proof that a person read the message. Say opened, never read. Authenticate with Authorization: Bearer and a key of the form dto_<c|r|m|a>_<keyid>_<secret>. Keys in the query string are rejected. Unknown JSON fields are rejected on the routes that check them. Every JSON response uses Cache-Control: no-store. Request bodies are limited to 1 MB unless a route says otherwise. Human docs: https://didtheyopen.com/docs",
    "contact": {
      "email": "support@didtheyopen.com",
      "url": "https://didtheyopen.com/privacy"
    }
  },
  "externalDocs": {
    "description": "API docs for agents",
    "url": "https://didtheyopen.com/docs"
  },
  "servers": [
    {
      "url": "https://p.didtheyopen.com",
      "description": "Production API and hosted MCP server"
    }
  ],
  "tags": [
    { "name": "Health" },
    { "name": "Signup" },
    { "name": "Account" },
    { "name": "Messages" },
    { "name": "Events" },
    { "name": "Links" },
    { "name": "Suppressions" },
    { "name": "Webhooks" },
    { "name": "Billing" },
    { "name": "MCP" }
  ],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/healthz": {
      "get": {
        "tags": ["Health"],
        "operationId": "healthz",
        "summary": "Liveness",
        "security": [],
        "responses": {
          "200": {
            "description": "The text ok.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "text/plain": {
                "schema": { "type": "string", "const": "ok" },
                "example": "ok"
              }
            }
          }
        }
      }
    },
    "/signup": {
      "post": {
        "tags": ["Signup"],
        "operationId": "signup",
        "summary": "Create a trial account",
        "description": "No request body and no API key. Returns an agent key (create and read), a manage key, and a dashboard login, each shown once. A browser form post (content type application/x-www-form-urlencoded) returns HTML instead of JSON. Cross-site browser requests must come from a configured site origin; agents send no Origin header. The client address is used only as a rate limit bucket and is not stored.",
        "security": [],
        "responses": {
          "201": {
            "description": "Account created.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SignupResult" },
                "example": {
                  "owner_id": "o_exampleownerid000000000000",
                  "agent_key": "dto_a_examplekeyid_examplesecret",
                  "manage_key": "dto_m_examplekeyid_examplesecret",
                  "dashboard_login_key": "dtl_exampleid_examplesecret",
                  "api_base": "https://p.didtheyopen.com",
                  "dashboard_url": "https://p.didtheyopen.com/dash/login",
                  "guide_url": "https://didtheyopen.com/agent.md?v=7",
                  "caps": {
                    "message_cap_per_day": 25,
                    "events_cap_per_message": 200,
                    "events_cap_per_day": 1000,
                    "default_expiry_days": 30,
                    "max_expiry_days": 30
                  },
                  "note": "Keys are shown once and cannot be recovered. Store them now. Trial: 25 tracked emails, then a paid plan; GET /v1/me shows what is left."
                }
              },
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["Account"],
        "operationId": "getMe",
        "summary": "Account, plan, and usage",
        "description": "Any valid key. guide.url is the agent guide address for guide.version.",
        "responses": {
          "200": {
            "description": "Account view.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Me" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "tags": ["Messages"],
        "operationId": "createMessage",
        "summary": "Create a tracked message",
        "description": "Scope: create. Requires Idempotency-Key (1 to 128 characters). The same key and body within 24 hours replays the stored 201, including pixel_url. The same key and a different body is 409 idempotency_conflict. pixel_url is returned here and on that replay only. A trial or lapsed plan that cannot create returns 402 payment_required, except an idempotent replay of an earlier 201.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateMessage" },
              "example": {
                "client_ref": "proposal-dana-1",
                "sender_label": "work",
                "label": "Dana Levi",
                "expires_in_days": 30
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message created. Includes pixel_url.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreated" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/PaymentRequired" },
          "403": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      },
      "get": {
        "tags": ["Messages"],
        "operationId": "listMessages",
        "summary": "List messages",
        "description": "Scope: read. Newest first. Does not include insight or pixel_url.",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["active", "paused"] }
          },
          {
            "name": "sender_label",
            "in": "query",
            "required": false,
            "schema": { "$ref": "#/components/schemas/SenderLabel" }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of messages.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/MessagePage" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages/by-ref/{client_ref}": {
      "get": {
        "tags": ["Messages"],
        "operationId": "getMessageByRef",
        "summary": "Get a message by the caller's reference",
        "description": "Scope: read. Includes insight, which is null when the message has no loads yet.",
        "parameters": [
          {
            "name": "client_ref",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "The message and its insight.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MessageWithInsight" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages/{id}": {
      "get": {
        "tags": ["Messages"],
        "operationId": "getMessage",
        "summary": "Get one message",
        "description": "Scope: read. Includes insight, which is null when the message has no loads yet.",
        "parameters": [{ "$ref": "#/components/parameters/MessageId" }],
        "responses": {
          "200": {
            "description": "The message and its insight.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MessageWithInsight" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "patch": {
        "tags": ["Messages"],
        "operationId": "patchMessage",
        "summary": "Pause, resume, or shorten expiry",
        "description": "Scope: manage. Send state, expires_in_days, or both. expires_in_days can only shorten the current expiry (400 cannot_extend). The response is a message view and does not include insight.",
        "parameters": [{ "$ref": "#/components/parameters/MessageId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PatchMessage" },
              "example": { "state": "paused" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated message view.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": {
                  "unevaluatedProperties": false,
                  "allOf": [{ "$ref": "#/components/schemas/Message" }]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "delete": {
        "tags": ["Messages"],
        "operationId": "deleteMessage",
        "summary": "Delete a message",
        "description": "Scope: manage.",
        "parameters": [{ "$ref": "#/components/parameters/MessageId" }],
        "responses": {
          "204": {
            "description": "Deleted. No body.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages/{id}/events": {
      "get": {
        "tags": ["Events"],
        "operationId": "listMessageEvents",
        "summary": "Loads for one message",
        "description": "Scope: read. Newest first. expand=assessment is the only accepted expand value. It adds assessment on each item and load_summary on the page. assessment is null when it could not be computed or the event is outside the 500 oldest loads of the message.",
        "parameters": [
          { "$ref": "#/components/parameters/MessageId" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "expand",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["assessment"] }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of loads.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/messages/{id}/links": {
      "post": {
        "tags": ["Links"],
        "operationId": "createTrackedLinks",
        "summary": "Build tracked links",
        "description": "Scope: create. 1 to 50 addresses, each at most 2048 characters. tracked_url is null when the address is not tracked (not http or https, or an unsubscribe address). Nothing is stored. 409 message_inactive when the message is paused or expired. 503 clicks_unavailable when click tracking is not configured. Also limited to 120 requests per 60 seconds per owner, separate from the API key limit.",
        "parameters": [{ "$ref": "#/components/parameters/MessageId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LinksRequest" },
              "example": { "urls": ["https://example.com/proposal", "mailto:dana@example.com"] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One result per input address, in the same order.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LinksResponse" },
                "example": {
                  "links": [
                    {
                      "url": "https://example.com/proposal",
                      "tracked_url": "https://p.didtheyopen.com/c/m_example/0/sealed"
                    },
                    { "url": "mailto:dana@example.com", "tracked_url": null }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/events": {
      "get": {
        "tags": ["Events"],
        "operationId": "listEvents",
        "summary": "Account feed",
        "description": "Scope: read. Commit order, oldest first. since is an ISO-8601 UTC time, unix seconds, or a next_since cursor (r and a row id). A time is only a lower bound for the first page. Pass next_since back to continue. When the page is empty, next_since echoes since, or is null if since was omitted. summary=1 adds summaries for at most 20 messages with new loads on the page. A bad since is 400 invalid_since.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "ISO-8601 UTC time, unix seconds, or an r cursor from next_since."
          },
          { "$ref": "#/components/parameters/Limit" },
          {
            "name": "summary",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["0", "1"] }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the feed.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/FeedPage" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/p/{token}.gif": {
      "get": {
        "tags": ["Events"],
        "operationId": "pixel",
        "summary": "Tracking image",
        "description": "No auth. Always 200 image/gif, 43 bytes, a transparent 1x1 GIF. A load is recorded only for GET, and only for a known, active, unexpired token within caps. The response looks the same either way. Cache-Control is no-store.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "The tracking GIF.",
            "content": {
              "image/gif": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      },
      "head": {
        "tags": ["Events"],
        "operationId": "pixelHead",
        "summary": "Tracking image headers",
        "description": "Same headers as GET, with no body and no recorded load.",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }
          }
        ],
        "responses": {
          "200": { "description": "GIF headers only." }
        }
      }
    },
    "/c/{message_id}/{index}/{sealed}": {
      "get": {
        "tags": ["Links"],
        "operationId": "followTrackedLink",
        "summary": "Follow a tracked link",
        "description": "No auth. 302 to the sealed destination. A valid link redirects even when the message is paused, expired, or deleted. A click is recorded only for GET on an active unexpired message within caps. 400 HTML when the link does not unseal. Never an open redirect.",
        "security": [],
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^m_[0-9a-hjkmnp-tv-z]{26}$" }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^\\d{1,3}$" }
          },
          {
            "name": "sealed",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{40,4000}$" }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the destination.",
            "headers": {
              "Location": { "schema": { "type": "string" } },
              "Cache-Control": { "$ref": "#/components/headers/NoStore" }
            }
          },
          "400": {
            "description": "The link is not valid. HTML, not JSON.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          }
        }
      },
      "head": {
        "tags": ["Links"],
        "operationId": "followTrackedLinkHead",
        "summary": "Tracked link headers",
        "description": "Same redirect as GET. HEAD does not record a click.",
        "security": [],
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "index",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "sealed",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "302": { "description": "Redirect. No recorded click." },
          "400": { "description": "The link is not valid." }
        }
      }
    },
    "/v1/suppressions/check": {
      "post": {
        "tags": ["Suppressions"],
        "operationId": "checkSuppressions",
        "summary": "Check suppression hashes",
        "description": "Scope: create or read. 1 to 50 lowercase sha256 hex digests of a lowercased address or domain. Returns whether any hash is suppressed. Hashes are not echoed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SuppressionCheck" },
              "example": {
                "hashes": ["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether any hash is suppressed.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["suppressed"],
                  "properties": { "suppressed": { "type": "boolean" } }
                },
                "example": { "suppressed": false }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/suppressions": {
      "get": {
        "tags": ["Suppressions"],
        "operationId": "listSuppressions",
        "summary": "List suppressions",
        "description": "Scope: manage. At most 500 rows. Hashes are never returned.",
        "responses": {
          "200": {
            "description": "Suppression rows without hashes.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionPage" } }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "tags": ["Suppressions"],
        "operationId": "createSuppression",
        "summary": "Add a suppression",
        "description": "Scope: manage. value_hash is the lowercase sha256 hex of the lowercased address or domain. 409 suppression_exists when that hash is already stored. The hash is not returned.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionCreate" } }
          }
        },
        "responses": {
          "201": {
            "description": "Created. The hash is not included.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/suppressions/{id}": {
      "delete": {
        "tags": ["Suppressions"],
        "operationId": "deleteSuppression",
        "summary": "Delete a suppression",
        "description": "Scope: manage.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "204": {
            "description": "Deleted. No body.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": ["Webhooks"],
        "operationId": "listWebhooks",
        "summary": "List webhooks",
        "description": "Scope: manage. Secrets are not included.",
        "responses": {
          "200": {
            "description": "Webhook rows.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPage" } }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "tags": ["Webhooks"],
        "operationId": "createWebhook",
        "summary": "Register a webhook",
        "description": "Scope: manage. url must be https, a public hostname, port 443, with no credentials, at most 2048 characters. At most 5 webhooks per owner (429 quota_exceeded). secret is returned once. A bad url is 400 invalid_url.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookCreate" },
              "example": { "url": "https://agent.example.com/hooks/didtheyopen" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created. secret is shown once.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/webhooks/{id}": {
      "patch": {
        "tags": ["Webhooks"],
        "operationId": "enableWebhook",
        "summary": "Re-enable a webhook",
        "description": "Scope: manage. Body must include enabled true. Resets the failure count and clears disabled_at. Returns the webhook view. This handler does not reject extra JSON fields.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebhookEnable" },
              "example": { "enabled": true }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The webhook after it is enabled.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      },
      "delete": {
        "tags": ["Webhooks"],
        "operationId": "deleteWebhook",
        "summary": "Delete a webhook",
        "description": "Scope: manage.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "204": {
            "description": "Deleted. No body.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/webhooks/{id}/test": {
      "post": {
        "tags": ["Webhooks"],
        "operationId": "testWebhook",
        "summary": "Send a test delivery",
        "description": "Scope: manage. Sends one delivery with type test. insight is null on that delivery. No request body.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "200": {
            "description": "Whether the test delivery was accepted by the receiver.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["delivered"],
                  "properties": { "delivered": { "type": "boolean" } }
                },
                "example": { "delivered": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": ["Webhooks"],
        "operationId": "listDeliveries",
        "summary": "Recent deliveries",
        "description": "Scope: manage. The last 100 deliveries. status is pending, delivered, or failed.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": {
          "200": {
            "description": "Delivery rows.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPage" } }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/billing/checkout/{plan}": {
      "get": {
        "tags": ["Billing"],
        "operationId": "billingCheckout",
        "summary": "Open a checkout",
        "description": "No API key. Query owner and sig must match a signed checkout link from GET /v1/me or a 402 body. 303 to the hosted checkout page, or to the customer portal when the owner already has an active plan. A missing portal for an active plan is a 409 HTML page. A bad signature, unknown plan, or unknown owner is a 404 HTML page. Too many attempts is a 429 HTML page. A checkout failure is a 503 HTML page. These responses are HTML, not the JSON error envelope.",
        "security": [],
        "parameters": [
          {
            "name": "plan",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "enum": ["personal", "developer"] }
          },
          {
            "name": "owner",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "sig",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "303": {
            "description": "Redirect to checkout or the customer portal.",
            "headers": { "Location": { "schema": { "type": "string" } } }
          },
          "404": {
            "description": "HTML page. The link is not valid.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          },
          "409": {
            "description": "HTML page. The owner already has a plan and no portal is set.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          },
          "429": {
            "description": "HTML page. Too many attempts.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          },
          "503": {
            "description": "HTML page. Checkout could not be created.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/billing/polar": {
      "post": {
        "tags": ["Billing"],
        "operationId": "polarWebhook",
        "summary": "Payment webhook",
        "description": "Called by the payment provider, not by agents. Standard Webhooks headers webhook-id, webhook-timestamp, and webhook-signature. The signature is v1, plus base64 HMAC-SHA256 of id.timestamp.raw body. Timestamps more than 5 minutes off are refused. Body limit 64 KB. A bad or missing signature is 403 bad_signature. Unconfigured billing is 503 billing_unconfigured. An unknown product is 503 billing_unknown_product. Handled subscription events are acknowledged; other events return 200 with result ignored. Only the subscription id, plan, status, and dates are stored.",
        "security": [],
        "parameters": [
          {
            "name": "webhook-id",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "webhook-timestamp",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "webhook-signature",
            "in": "header",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event applied, stale, ignored, or unmatched.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": ["ok", "result"],
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "result": {
                      "type": "string",
                      "enum": ["applied", "stale", "ignored", "unmatched"]
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/dash/billing/portal": {
      "get": {
        "tags": ["Billing"],
        "operationId": "billingPortal",
        "summary": "Open the customer portal",
        "description": "Dashboard session cookie dto_session, not an API key. 303 to a short-lived portal session, or 503 HTML when no portal is available.",
        "security": [],
        "responses": {
          "303": {
            "description": "Redirect to the customer portal.",
            "headers": { "Location": { "schema": { "type": "string" } } }
          },
          "302": {
            "description": "No dashboard session. Redirects to /dash/login.",
            "headers": { "Location": { "schema": { "type": "string" } } }
          },
          "503": {
            "description": "HTML page. The portal is unavailable.",
            "content": { "text/html": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": ["MCP"],
        "operationId": "mcp",
        "summary": "Hosted MCP server",
        "description": "Streamable HTTP, stateless, one JSON-RPC object per request. Send Accept: application/json, text/event-stream. OPTIONS is 204 with Allow: POST, OPTIONS and no CORS headers. GET and DELETE are 405. Batches are 400. Authorization Bearer is the same agent key as /v1 and counts as one request against that key's rate limit. Without the header, initialize, tools/list, and didtheyopen_signup work; other tools return an error asking for the header. A wrong key is 401, too many requests is 429, and a credential in the query string is 400. Those failures use a JSON-RPC error envelope with error.code -32000 and error.data.code set to the API error code, and they keep the HTTP status. Tool calls run inside the worker. Keys and tool arguments are not logged.",
        "security": [{ "bearerAuth": [] }, {}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" },
              "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result. The shape depends on the method.",
            "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
            "content": {
              "application/json": { "schema": { "type": "object" } }
            }
          },
          "400": {
            "description": "JSON-RPC error. Credential in the query string, a batch, or a parse error.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
            }
          },
          "401": {
            "description": "JSON-RPC error. Missing or invalid API key.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
            }
          },
          "405": {
            "description": "JSON-RPC error. POST only.",
            "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
            }
          },
          "413": {
            "description": "JSON-RPC error. Body over 1 MB.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
            }
          },
          "429": {
            "description": "JSON-RPC error. Too many requests. Retry-After: 60.",
            "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcError" } }
            }
          }
        }
      },
      "options": {
        "tags": ["MCP"],
        "operationId": "mcpOptions",
        "summary": "MCP preflight",
        "description": "204 with Allow: POST, OPTIONS and Cache-Control: no-store. No Access-Control headers. The endpoint is for agents and server-side clients, not browser pages. No auth, database or rate-limit work.",
        "security": [],
        "responses": {
          "204": {
            "description": "No body. Allow: POST, OPTIONS. No Access-Control-Allow-Origin.",
            "headers": {
              "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } },
              "Cache-Control": { "$ref": "#/components/headers/NoStore" }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "dto_<c|r|m|a>_<keyid>_<secret>",
        "description": "API key. c create, r read, m manage (manage includes read), a agent (create and read). Sent only in the Authorization header. Query names key, token, api_key, apikey, api-key, access_token, access-token, accesstoken, auth, authorization, bearer, secret, or password are rejected in any case. A query value matching dto_<letter>_, dtl_, or whsec_ is also rejected, except the cursor parameter."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Page size. Default 25. 1 to 100. A bad value is 400 invalid_limit.",
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Opaque cursor from next_cursor. A bad value is 400 invalid_cursor.",
        "schema": { "type": "string" }
      },
      "MessageId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string" }
      },
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string" }
      }
    },
    "headers": {
      "NoStore": {
        "description": "Responses are not cached.",
        "schema": { "type": "string", "const": "no-store" }
      },
      "RetryAfter": {
        "description": "Seconds to wait. 60 for rate_limited. 3600 for a daily message cap.",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "Error": {
        "description": "Error envelope. code is a stable string such as unauthorized, forbidden, not_found, credential_in_url, invalid_body, unknown_field, invalid_json, invalid_cursor, invalid_limit, invalid_filter, invalid_since, invalid_url, idempotency_key_required, cannot_extend, idempotency_conflict, client_ref_exists, suppression_exists, message_inactive, quota_exceeded, rate_limited, storage_unavailable, quota_platform, clicks_unavailable, forbidden_origin, signups_full, or internal_error.",
        "headers": {
          "Cache-Control": { "$ref": "#/components/headers/NoStore" },
          "Retry-After": { "$ref": "#/components/headers/RetryAfter" }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "PaymentRequired": {
        "description": "402 payment_required. checkout and manage_url sit beside error. An idempotent replay of a successful create is still 201.",
        "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" } },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } }
        }
      }
    },
    "schemas": {
      "ErrorBody": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": { "$ref": "#/components/schemas/ErrorBody" }
        }
      },
      "CheckoutLinks": {
        "type": "object",
        "additionalProperties": false,
        "required": ["personal_url", "developer_url"],
        "properties": {
          "personal_url": { "type": "string", "format": "uri" },
          "developer_url": { "type": "string", "format": "uri" }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error", "checkout", "manage_url"],
        "properties": {
          "error": { "$ref": "#/components/schemas/ErrorBody" },
          "checkout": {
            "oneOf": [{ "$ref": "#/components/schemas/CheckoutLinks" }, { "type": "null" }]
          },
          "manage_url": { "type": ["string", "null"] }
        }
      },
      "SenderLabel": { "type": "string", "enum": ["personal", "work"] },
      "MessageState": { "type": "string", "enum": ["active", "paused"] },
      "Classification": {
        "type": "string",
        "enum": ["image_request", "possible_proxy", "possible_scanner", "missing_data"]
      },
      "ClientFamily": {
        "type": "string",
        "enum": [
          "gmail_proxy",
          "apple_relay",
          "iphone_ipad",
          "mac",
          "android",
          "windows",
          "outlook",
          "other",
          "unknown"
        ]
      },
      "LoadLabel": {
        "type": "string",
        "enum": ["opened", "prefetch_likely", "mpp_unknown", "unknown"],
        "description": "Only opened counts as an open."
      },
      "Kind": { "type": "string", "enum": ["open", "click"] },
      "Caps": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "message_cap_per_day",
          "events_cap_per_message",
          "events_cap_per_day",
          "default_expiry_days",
          "max_expiry_days"
        ],
        "properties": {
          "message_cap_per_day": { "type": "integer" },
          "events_cap_per_message": { "type": "integer" },
          "events_cap_per_day": { "type": "integer" },
          "default_expiry_days": { "type": "integer" },
          "max_expiry_days": { "type": "integer" }
        }
      },
      "Usage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["messages_created", "events_recorded"],
        "properties": {
          "messages_created": { "type": "integer" },
          "events_recorded": { "type": "integer" }
        }
      },
      "Guide": {
        "type": "object",
        "additionalProperties": false,
        "required": ["version", "url"],
        "properties": {
          "version": { "type": "integer" },
          "url": { "type": "string", "format": "uri" }
        }
      },
      "SignupResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "owner_id",
          "agent_key",
          "manage_key",
          "dashboard_login_key",
          "api_base",
          "dashboard_url",
          "guide_url",
          "caps",
          "note"
        ],
        "properties": {
          "owner_id": { "type": "string" },
          "agent_key": { "type": "string" },
          "manage_key": { "type": "string" },
          "dashboard_login_key": { "type": "string" },
          "api_base": { "type": "string" },
          "dashboard_url": { "type": "string" },
          "guide_url": { "type": "string" },
          "caps": { "$ref": "#/components/schemas/Caps" },
          "note": { "type": "string" }
        }
      },
      "Me": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "owner_id",
          "key_id",
          "scopes",
          "caps",
          "usage_today",
          "plan",
          "trial_remaining",
          "paid_through",
          "can_create",
          "checkout",
          "manage_url",
          "guide"
        ],
        "properties": {
          "owner_id": { "type": "string" },
          "key_id": { "type": "string" },
          "scopes": {
            "type": "array",
            "items": { "type": "string", "enum": ["create", "read", "manage"] }
          },
          "caps": { "$ref": "#/components/schemas/Caps" },
          "usage_today": { "$ref": "#/components/schemas/Usage" },
          "plan": { "type": "string", "enum": ["internal", "trial", "personal", "developer"] },
          "trial_remaining": { "type": ["integer", "null"] },
          "paid_through": { "type": ["string", "null"], "format": "date-time" },
          "can_create": { "type": "boolean" },
          "checkout": {
            "oneOf": [{ "$ref": "#/components/schemas/CheckoutLinks" }, { "type": "null" }]
          },
          "manage_url": { "type": ["string", "null"] },
          "guide": { "$ref": "#/components/schemas/Guide" }
        }
      },
      "CreateMessage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["client_ref", "sender_label"],
        "properties": {
          "client_ref": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" },
          "sender_label": { "$ref": "#/components/schemas/SenderLabel" },
          "expires_in_days": {
            "type": "integer",
            "minimum": 1,
            "description": "Defaults to the owner's default, capped by max_expiry_days. Self-serve accounts max out at 30."
          },
          "label": {
            "type": "string",
            "maxLength": 64,
            "description": "Optional display name. At most 64 printable characters, no angle brackets. Not an email address."
          }
        }
      },
      "PatchMessage": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "state": { "$ref": "#/components/schemas/MessageState" },
          "expires_in_days": { "type": "integer", "minimum": 1 }
        }
      },
      "Message": {
        "type": "object",
        "description": "Shared message fields. Closed by unevaluatedProperties on each response schema that composes it, so a create body can add pixel_url and a read body can add insight.",
        "required": [
          "id",
          "client_ref",
          "label",
          "sender_label",
          "state",
          "created_at",
          "expires_at",
          "event_count",
          "click_count",
          "last_event_at"
        ],
        "properties": {
          "id": { "type": "string" },
          "client_ref": { "type": "string" },
          "label": { "type": "string" },
          "sender_label": { "$ref": "#/components/schemas/SenderLabel" },
          "state": { "$ref": "#/components/schemas/MessageState" },
          "created_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time" },
          "event_count": {
            "type": "integer",
            "description": "Every recorded image load, opened or not."
          },
          "click_count": { "type": "integer" },
          "last_event_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "MessageCreated": {
        "unevaluatedProperties": false,
        "allOf": [
          { "$ref": "#/components/schemas/Message" },
          {
            "type": "object",
            "required": ["pixel_url"],
            "properties": { "pixel_url": { "type": "string", "format": "uri" } }
          }
        ]
      },
      "MessagePage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items", "next_cursor"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "unevaluatedProperties": false,
              "allOf": [{ "$ref": "#/components/schemas/Message" }]
            }
          },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "InsightOpen": {
        "type": "object",
        "additionalProperties": false,
        "required": ["received_at", "classification", "client_family", "label"],
        "properties": {
          "received_at": { "type": "string", "format": "date-time" },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "client_family": { "$ref": "#/components/schemas/ClientFamily" },
          "label": { "$ref": "#/components/schemas/LoadLabel" }
        }
      },
      "Insight": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "version",
          "rules_version",
          "notable",
          "reason",
          "event_count",
          "opens",
          "clicks",
          "latest",
          "previous",
          "families",
          "possible_self_view",
          "headline"
        ],
        "properties": {
          "version": { "type": "integer" },
          "rules_version": { "type": "integer" },
          "notable": { "type": "boolean" },
          "reason": {
            "type": "string",
            "enum": [
              "first_open",
              "clicked",
              "new_device",
              "reopened",
              "possible_open_hidden",
              "repeat",
              "possible_automated"
            ]
          },
          "event_count": { "type": "integer" },
          "opens": { "type": "integer" },
          "clicks": { "type": "integer" },
          "latest": {
            "oneOf": [{ "$ref": "#/components/schemas/InsightOpen" }, { "type": "null" }]
          },
          "previous": {
            "oneOf": [{ "$ref": "#/components/schemas/InsightOpen" }, { "type": "null" }]
          },
          "families": { "type": "array", "items": { "type": "string" } },
          "possible_self_view": { "type": "boolean" },
          "headline": { "type": "string" }
        }
      },
      "MessageWithInsight": {
        "unevaluatedProperties": false,
        "allOf": [
          { "$ref": "#/components/schemas/Message" },
          {
            "type": "object",
            "required": ["insight"],
            "properties": {
              "insight": {
                "oneOf": [{ "$ref": "#/components/schemas/Insight" }, { "type": "null" }]
              }
            }
          }
        ]
      },
      "EventItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "received_at",
          "classification",
          "classifier_version",
          "client_family",
          "load_label",
          "kind"
        ],
        "properties": {
          "id": { "type": "string" },
          "received_at": { "type": "string", "format": "date-time" },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "classifier_version": { "type": "integer" },
          "client_family": { "$ref": "#/components/schemas/ClientFamily" },
          "load_label": { "$ref": "#/components/schemas/LoadLabel" },
          "kind": { "$ref": "#/components/schemas/Kind" },
          "link_index": {
            "type": "integer",
            "description": "Present only when kind is click."
          },
          "assessment": {
            "oneOf": [{ "$ref": "#/components/schemas/Assessment" }, { "type": "null" }],
            "description": "Present only when expand=assessment."
          }
        }
      },
      "LoadSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rules_version",
          "raw_loads",
          "assessed_loads",
          "truncated",
          "by_label",
          "human_engagement",
          "wording"
        ],
        "properties": {
          "rules_version": { "type": "integer" },
          "raw_loads": { "type": "integer" },
          "assessed_loads": { "type": "integer" },
          "truncated": { "type": "boolean" },
          "by_label": {
            "type": "object",
            "additionalProperties": false,
            "required": ["opened", "prefetch_likely", "mpp_unknown", "unknown"],
            "properties": {
              "opened": { "type": "integer" },
              "prefetch_likely": { "type": "integer" },
              "mpp_unknown": { "type": "integer" },
              "unknown": { "type": "integer" }
            }
          },
          "human_engagement": {
            "type": "string",
            "enum": ["opened", "unknown", "none_observed"]
          },
          "wording": { "type": "string" }
        }
      },
      "Assessment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "rules_version",
          "basis",
          "label",
          "label_strength",
          "human_engagement",
          "human_open_strength",
          "reasons",
          "conflicts",
          "missing",
          "signals",
          "signals_version",
          "network_data_version",
          "context",
          "timing"
        ],
        "properties": {
          "rules_version": { "type": "integer" },
          "basis": { "type": "string", "enum": ["request_signals", "legacy_labels", "error"] },
          "label": { "$ref": "#/components/schemas/LoadLabel" },
          "label_strength": { "type": ["string", "null"], "enum": ["signal", "strong", null] },
          "human_engagement": { "type": "string", "enum": ["opened", "unknown"] },
          "human_open_strength": { "type": ["string", "null"], "enum": ["signal", null] },
          "reasons": { "type": "array", "items": { "type": "string" } },
          "conflicts": { "type": "array", "items": { "type": "string" } },
          "missing": { "type": "array", "items": { "type": "string" } },
          "signals": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Fixed signal codes. Never a header value."
          },
          "signals_version": { "type": ["integer", "null"] },
          "network_data_version": { "type": ["string", "null"] },
          "context": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": ["event_ids", "evaluated_through"],
                "properties": {
                  "event_ids": { "type": "array", "items": { "type": "string" } },
                  "evaluated_through": { "type": "string" }
                }
              },
              { "type": "null" }
            ]
          },
          "timing": {
            "type": "object",
            "additionalProperties": false,
            "required": ["seconds_since_pixel_created", "basis"],
            "properties": {
              "seconds_since_pixel_created": { "type": ["integer", "null"] },
              "basis": { "type": "string", "const": "pixel_created" }
            }
          }
        }
      },
      "EventPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items", "next_cursor"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/EventItem" } },
          "load_summary": {
            "oneOf": [{ "$ref": "#/components/schemas/LoadSummary" }, { "type": "null" }],
            "description": "Present only when expand=assessment."
          },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "FeedItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "received_at",
          "classification",
          "classifier_version",
          "client_family",
          "load_label",
          "kind",
          "message_id",
          "client_ref",
          "label",
          "sender_label"
        ],
        "properties": {
          "id": { "type": "string" },
          "received_at": { "type": "string", "format": "date-time" },
          "classification": { "$ref": "#/components/schemas/Classification" },
          "classifier_version": { "type": "integer" },
          "client_family": { "$ref": "#/components/schemas/ClientFamily" },
          "load_label": { "$ref": "#/components/schemas/LoadLabel" },
          "kind": { "$ref": "#/components/schemas/Kind" },
          "link_index": { "type": "integer" },
          "message_id": { "type": "string" },
          "client_ref": { "type": "string" },
          "label": { "type": "string" },
          "sender_label": { "$ref": "#/components/schemas/SenderLabel" }
        }
      },
      "FeedSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": ["message_id", "client_ref", "label", "sender_label", "new_events", "insight"],
        "properties": {
          "message_id": { "type": "string" },
          "client_ref": { "type": "string" },
          "label": { "type": "string" },
          "sender_label": { "$ref": "#/components/schemas/SenderLabel" },
          "new_events": { "type": "integer" },
          "insight": { "$ref": "#/components/schemas/Insight" }
        }
      },
      "FeedPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items", "next_since", "has_more", "guide_version"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/FeedItem" } },
          "next_since": { "type": ["string", "null"] },
          "has_more": { "type": "boolean" },
          "guide_version": { "type": "integer" },
          "summaries": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FeedSummary" }
          },
          "summaries_truncated": { "type": "boolean" }
        }
      },
      "LinksRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["urls"],
        "properties": {
          "urls": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": { "type": "string", "maxLength": 2048 }
          }
        }
      },
      "LinksResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["links"],
        "properties": {
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["url", "tracked_url"],
              "properties": {
                "url": { "type": "string" },
                "tracked_url": { "type": ["string", "null"] }
              }
            }
          }
        }
      },
      "SuppressionCheck": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hashes"],
        "properties": {
          "hashes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
          }
        }
      },
      "SuppressionCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": ["kind", "value_hash"],
        "properties": {
          "kind": { "type": "string", "enum": ["address", "domain"] },
          "value_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
          "note": { "type": "string", "maxLength": 200 }
        }
      },
      "Suppression": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "kind", "note", "created_at"],
        "properties": {
          "id": { "type": "string" },
          "kind": { "type": "string", "enum": ["address", "domain"] },
          "note": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "SuppressionPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }
        }
      },
      "Webhook": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "url",
          "enabled",
          "consecutive_failures",
          "created_at",
          "disabled_at",
          "last_delivered_at"
        ],
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string" },
          "enabled": { "type": "boolean" },
          "consecutive_failures": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "disabled_at": { "type": ["string", "null"], "format": "date-time" },
          "last_delivered_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "WebhookCreated": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "url", "secret", "enabled", "created_at"],
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string" },
          "secret": { "type": "string", "description": "Shown once. Starts with whsec_." },
          "enabled": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookCreate": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url"],
        "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } }
      },
      "WebhookEnable": {
        "type": "object",
        "required": ["enabled"],
        "properties": { "enabled": { "type": "boolean", "const": true } }
      },
      "WebhookPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }
        }
      },
      "Delivery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "webhook_id",
          "event_id",
          "attempts",
          "status",
          "last_status",
          "created_at",
          "delivered_at",
          "next_attempt_at"
        ],
        "properties": {
          "id": { "type": "string" },
          "webhook_id": { "type": "string" },
          "event_id": { "type": "string" },
          "attempts": { "type": "integer" },
          "status": { "type": "string", "enum": ["pending", "delivered", "failed"] },
          "last_status": { "type": ["integer", "null"] },
          "created_at": { "type": "string", "format": "date-time" },
          "delivered_at": { "type": ["string", "null"], "format": "date-time" },
          "next_attempt_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "DeliveryPage": {
        "type": "object",
        "additionalProperties": false,
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": {},
          "method": { "type": "string" },
          "params": {}
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["jsonrpc", "id", "error"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "type": "null" },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer" },
              "message": { "type": "string" },
              "data": {
                "type": "object",
                "properties": { "code": { "type": "string" } },
                "description": "Present on tracker auth, rate, and method errors. Protocol parse errors from the MCP handler may omit it."
              }
            }
          }
        }
      }
    }
  }
}
