{
  "openapi": "3.1.0",
  "info": {
    "title": "OnceAsk Agent Delivery API",
    "version": "1.4.0",
    "description": "Permissioned physical delivery for AI agents. Resolve a person to an opaque delivery token, request recipient consent when needed, and fulfill without returning the recipient street address to the agent."
  },
  "servers": [{ "url": "https://onceask.com/_api" }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "OnceAsk API key with resolve_delivery scope" }
    },
    "schemas": {
      "ResolveRequest": {
        "type": "object",
        "properties": {
          "contactId": { "type": "string" },
          "query": { "type": "string" },
          "purpose": { "type": "string" }
        },
        "anyOf": [{ "required": ["contactId"] }, { "required": ["query"] }]
      },
      "DeliveryToken": {
        "type": "string",
        "description": "Opaque, short-lived, one-time capability. Do not decode or treat as an address."
      }
    }
  },
  "paths": {
    "/v1/delivery/resolve": {
      "post": {
        "operationId": "resolveDelivery",
        "summary": "Resolve a known person for private physical delivery",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } } },
        "responses": {
          "200": {
            "description": "Structured delivery resolution. Status is authorized, permission_required, address_update_required, ambiguous, or not_found."
          }
        }
      }
    },
    "/v1/delivery/request-permission": {
      "post": {
        "operationId": "requestDeliveryPermission",
        "summary": "Ask a person to confirm a current delivery address and permission",
        "description": "After the user confirms the outreach, provide either a OnceAsk contact ID or a person's name/email. OnceAsk can discover the person from connected Google/Gmail-derived contacts and emails the secure request when possible without exposing the recipient's email or street address to the agent.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "query": { "type": "string", "description": "Person name or email, e.g. Aunt Theresa" }, "customMessage": { "type": "string" } }, "anyOf": [{ "required": ["contactId"] }, { "required": ["query"] }] } } }
        },
        "responses": { "200": { "description": "Request sent or secure request link prepared without revealing recipient address data." } }
      }
    },
    "/v1/fulfillment/handwrytten/catalog": {
      "get": {
        "operationId": "listHandwrittenCards",
        "summary": "List handwritten card designs and handwriting styles",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Available Handwrytten cards and fonts." } }
      }
    },
    "/v1/fulfillment/handwrytten/send": {
      "post": {
        "operationId": "sendHandwrittenCard",
        "summary": "Use an opaque delivery token to send a handwritten card",
        "description": "OnceAsk resolves the token server-side and passes the address directly to the fulfillment provider. The response never contains the recipient street address.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["deliveryToken", "cardId", "message"],
                "properties": {
                  "deliveryToken": { "$ref": "#/components/schemas/DeliveryToken" },
                  "cardId": { "type": "integer" },
                  "message": { "type": "string" },
                  "wishes": { "type": "string" },
                  "fontLabel": { "type": "string", "default": "Casual David" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Fulfillment status and provider order identifier; no address fields." } }
      }
    }
  },
  "x-onceask-privacy": {
    "raw-address-default": false,
    "preferred-scope": "resolve_delivery",
    "recipient-consent-required": true
  }
}