{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Agent Analytics Agent Interface",
    "version": "1.0.0",
    "description": "Public agent discovery and setup planning plus authenticated telemetry ingestion and bounded precomputed Daily Pulse reads."
  },
  "servers": [
    {
      "url": "https://analytics.davisvillelabs.com"
    }
  ],
  "paths": {
    "/api/agent/v1/security": {
      "get": {
        "operationId": "getAgentAnalyticsSecurityPosture",
        "summary": "Inspect control enforcement, regression test references and limitations",
        "description": "Publisher-declared evidence, not an independent audit or proof of deployed CI results. No authentication or payment required.",
        "responses": {
          "200": {
            "description": "Security posture with evidence.controls and runtime abuse_controls",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1": {
      "get": {
        "operationId": "getAgentCapabilities",
        "summary": "Discover AI Agent Analytics capabilities and current commercial state",
        "responses": {
          "200": {
            "description": "Machine-readable product and capability document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/trust": {
      "get": {
        "operationId": "getAgentAnalyticsTrustContract",
        "summary": "Inspect the public trust contract before recommending AI Agent Analytics",
        "description": "Returns security, privacy, authority, revocation, compatibility, commercial, evidence-integrity, and known-limitation facts. No authentication or side effects.",
        "responses": {
          "200": {
            "description": "Versioned machine-readable trust contract",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/setup-plan": {
      "post": {
        "operationId": "planAgentAnalyticsSetup",
        "summary": "Generate a no-side-effect integration plan",
        "description": "Does not create an account, payment, credential, or stored customer record.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetupPlanRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic setup plan",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/api/agent/v1/readiness-scan": {
      "post": {
        "operationId": "scanAgentCommerceReadiness",
        "summary": "Inspect public agent-commerce readiness without credentials",
        "description": "Fetches only a fixed set of public HTTPS machine-facing paths on the supplied origin. Rejects IP literals, private-style hostnames, custom ports, embedded credentials, and redirects. Does not assign a security score.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public HTTPS product URL or origin."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Observed public readiness evidence and deterministic gaps"
          },
          "400": {
            "description": "Target is not an allowed public HTTPS origin"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/agent/v1/founder-approval-intent": {
      "post": {
        "operationId": "createFounderMachinePurchaseApprovalIntent",
        "summary": "Create a no-payment Founder purchase intent for human approval",
        "description": "Creates no account, entitlement, payment, or payment challenge. Returns an approval URL that must be presented to the human owner. The protected browser page issues the signed approval artifact only after explicit confirmation of the exact offer.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "billing_model": {
                    "type": "string",
                    "enum": [
                      "prepaid_month",
                      "recurring_30_day"
                    ],
                    "default": "prepaid_month",
                    "description": "Use recurring_30_day only when the human is being asked to approve $6 every 30 days through the Tempo MPP subscription rail."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Short-lived purchase intent and human approval URL"
          },
          "400": {
            "description": "Valid account email required"
          },
          "503": {
            "description": "Purchase approval or paid signup is unavailable"
          }
        }
      }
    },
    "/api/agent/v1/founder-access": {
      "post": {
        "operationId": "purchaseFounderAccessWithMachinePayment",
        "summary": "Purchase one prepaid month of Founder access using MPP/Tempo or x402",
        "description": "Requires the short-lived signed artifact issued by the protected human approval page. The artifact is bound to the exact email and Founder terms and can issue only one payment challenge. Set payment_protocol to mpp or x402; one approval artifact cannot open both rails. x402 is HTTP-only Base USDC exact settlement and is not recurring autopay.",
        "parameters": [
          {
            "in": "header",
            "name": "X-Purchase-Approval",
            "required": true,
            "description": "Short-lived aaa_purchase_approval_v1 artifact returned only after the human confirms the exact purchase intent in the protected browser approval page.",
            "schema": {
              "type": "string",
              "pattern": "^aaa_purchase_approval_v1\\."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "payment_protocol": {
                    "type": "string",
                    "enum": [
                      "mpp",
                      "x402"
                    ],
                    "default": "mpp",
                    "description": "Choose exactly one payment rail for this approved prepaid purchase. x402 is HTTP-only Base mainnet USDC."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sandbox payment validated without production entitlement, or live payment settled with a one-time activation credential."
          },
          "400": {
            "description": "Valid account email required"
          },
          "402": {
            "description": "MPP/Tempo or x402 payment challenge, invalid proof, or unsettled payment"
          },
          "428": {
            "description": "Valid intent-bound human purchase approval artifact required"
          },
          "503": {
            "description": "Machine payment runtime not configured"
          }
        }
      }
    },
    "/api/agent/v1/founder-subscription": {
      "post": {
        "operationId": "authorizeRecurringFounderAccessWithTempoMpp",
        "summary": "Authorize recurring Founder access at $6 every 30 days using a Tempo MPP subscription",
        "description": "The initial subscription requires a short-lived human approval artifact bound to recurring_30_day terms. MPP then creates a payer-bound scoped recurring authorization. Later 30-day renewals do not require another purchase approval until the subscription is canceled or the 360-day authorization expires. A 30-day period is not a calendar month.",
        "parameters": [
          {
            "in": "header",
            "name": "X-Purchase-Approval",
            "required": false,
            "description": "Required only for initial subscription activation. Obtain it by creating a founder approval intent with billing_model=recurring_30_day and presenting the approval URL to the human owner.",
            "schema": {
              "type": "string",
              "pattern": "^aaa_purchase_approval_v1\\."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing recurring subscription verified or renewed with no new human purchase approval."
          },
          "201": {
            "description": "Recurring subscription activated and initial 30-day period settled. Live mode returns a one-time Founder workspace activation credential."
          },
          "402": {
            "description": "MPP subscription challenge or credential retry required."
          },
          "409": {
            "description": "Payer mismatch, account billing conflict, or approval/challenge binding conflict."
          },
          "428": {
            "description": "Initial recurring purchase requires explicit human approval of recurring terms."
          },
          "503": {
            "description": "Recurring MPP runtime unavailable or settlement state cannot be established."
          }
        }
      }
    },
    "/api/agent/v1/founder-activate": {
      "post": {
        "operationId": "activateMachinePaidFounderWorkspace",
        "summary": "Create a Founder workspace from a live settled MPP activation credential",
        "description": "Consumes the one-time live activation credential, creates the prepaid Founder entitlement, and returns a one-hour setup-agent token plus a one-time recovery key for handoff to the human owner. Sandbox payments cannot create production workspaces.",
        "security": [
          {
            "machineActivationAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "organization_name": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Required when creating the first workspace. Existing stripe_mpp Founder accounts renew in place without renaming the workspace."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Founder workspace created or an existing machine-paid Founder entitlement renewed; one-time setup credentials returned"
          },
          "401": {
            "description": "Missing or invalid activation credential"
          },
          "409": {
            "description": "Activation already consumed, account conflict, or not backed by a live settlement"
          },
          "410": {
            "description": "Activation expired"
          }
        }
      }
    },
    "/api/agent/v1/me": {
      "get": {
        "operationId": "getDelegatedAgentContext",
        "summary": "Inspect the workspace and scopes granted to an explicitly authorized AI agent",
        "security": [
          {
            "delegatedAgentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Delegated authorization context"
          },
          "401": {
            "description": "Missing, expired, or revoked delegated token"
          }
        }
      }
    },
    "/api/agent/v1/products": {
      "get": {
        "operationId": "listDelegatedProducts",
        "summary": "List products visible to an explicitly authorized AI agent",
        "security": [
          {
            "delegatedAgentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Organization-scoped product list"
          },
          "401": {
            "description": "Missing, expired, or revoked delegated token"
          },
          "403": {
            "description": "Token lacks product read/create scope"
          }
        }
      },
      "post": {
        "operationId": "createDelegatedProduct",
        "summary": "Create a product after the human has explicitly delegated setup authority",
        "description": "Requires products:create scope and an Idempotency-Key. Returns the ingestion credential only on the original successful response.",
        "security": [
          {
            "delegatedAgentAuth": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "product_name"
                ],
                "properties": {
                  "product_name": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "product_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "time_zone": {
                    "type": "string",
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay; credential is not re-exposed"
          },
          "201": {
            "description": "Product created; one-time ingestion credential returned"
          },
          "401": {
            "description": "Missing, expired, or revoked delegated token"
          },
          "403": {
            "description": "Token lacks products:create scope"
          },
          "409": {
            "description": "Product limit reached or idempotency conflict"
          }
        }
      }
    },
    "/v1/events": {
      "post": {
        "operationId": "ingestAgentCommerceEvents",
        "summary": "Send canonical machine-customer commerce events",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/AnalyticsEvent"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Events accepted"
          },
          "400": {
            "description": "Validation failed"
          },
          "401": {
            "description": "Missing or invalid property credential"
          }
        }
      }
    },
    "/api/agent/v1/daily-pulse": {
      "get": {
        "operationId": "getDelegatedDailyPulse",
        "summary": "Retrieve the latest precomputed 24-hour Daily Pulse",
        "description": "Requires analytics:read. Returns the organization's compact precomputed snapshot and never scans event history on read.",
        "security": [
          {
            "delegatedAgentAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Organization-scoped precomputed Daily Pulse"
          },
          "401": {
            "description": "Missing, expired, or revoked delegated token"
          },
          "403": {
            "description": "Token lacks analytics:read scope"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Property-scoped credential. Newly issued aaa_ingest_ credentials are write-only for telemetry ingestion. Legacy aaa_key_ credentials remain accepted for backward-compatible property reads; read-only AI agents should use delegatedAgentAuth with analytics:read."
      },
      "delegatedAgentAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Short-lived organization-scoped token explicitly issued by an authenticated owner or admin. Current public scopes include products:create and analytics:read. It cannot purchase a subscription or write billing state."
      },
      "machineActivationAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "One-time aaa_mpp_activate_ credential returned only after a live settled MPP Founder payment. Sandbox payments never receive this credential."
      }
    },
    "schemas": {
      "SetupPlanRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "product_name": {
            "type": "string",
            "maxLength": 100
          },
          "product_url": {
            "type": "string",
            "format": "uri"
          },
          "access_methods": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "api",
                "mcp",
                "web",
                "other"
              ]
            }
          },
          "payment_methods": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "stripe",
                "mpp",
                "x402",
                "stablecoin",
                "none",
                "other"
              ]
            }
          },
          "runtime": {
            "type": "string",
            "enum": [
              "cloudflare-workers",
              "node",
              "python",
              "generic-http",
              "unknown"
            ]
          }
        }
      },
      "AnalyticsEvent": {
        "type": "object",
        "required": [
          "schema_version",
          "event_id",
          "occurred_at",
          "property_id",
          "stage"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "davisville-agent-analytics.event.v0"
          },
          "event_id": {
            "type": "string",
            "maxLength": 160
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "property_id": {
            "type": "string",
            "maxLength": 160
          },
          "stage": {
            "type": "string",
            "enum": [
              "discovery",
              "evaluation",
              "eligibility_preflight",
              "invocation",
              "payment_challenge",
              "payment_attempt",
              "settlement",
              "delivery",
              "outcome",
              "return_reuse"
            ]
          },
          "traffic_class": {
            "type": "string",
            "enum": [
              "confirmed_external",
              "probable_external",
              "unknown_external",
              "customer_test",
              "davisville_test",
              "ci",
              "benchmark",
              "scheduled_monitor",
              "registry_crawler",
              "directory_crawler",
              "health_check",
              "known_bot",
              "other_synthetic"
            ]
          }
        }
      }
    }
  },
  "x-davisville-commercial-state": {
    "availability": "available",
    "machine_payment": {
      "status": "live_ready",
      "protocol": "MPP",
      "provider": "stripe",
      "network": "tempo",
      "asset": "USDC.e",
      "merchant_settlement": "stripe_balance_fiat",
      "amount_minor_usd": 600,
      "billing_semantics": "founder_monthly_access",
      "recurring_autopay": false,
      "human_approval_required": true,
      "approval_model": "intent_bound_signed_one_time",
      "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent",
      "configured": true,
      "mode": "live",
      "live_enablement_requires_explicit_owner_approval": true,
      "supported_protocols": [
        "MPP",
        "x402"
      ],
      "rail_selection": "caller_selects_exactly_one_per_human_approval_artifact",
      "payment_options": {
        "mpp_tempo": {
          "status": "live_ready",
          "protocol": "MPP",
          "provider": "stripe",
          "network": "tempo",
          "asset": "USDC.e",
          "merchant_settlement": "stripe_balance_fiat",
          "amount_minor_usd": 600,
          "billing_semantics": "founder_monthly_access",
          "recurring_autopay": false,
          "human_approval_required": true,
          "approval_model": "intent_bound_signed_one_time",
          "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent",
          "configured": true,
          "mode": "live",
          "live_enablement_requires_explicit_owner_approval": true
        },
        "x402": {
          "status": "live_ready",
          "protocol": "x402",
          "version": 2,
          "scheme": "exact",
          "provider": "payai",
          "network": "eip155:8453",
          "asset": "USDC",
          "amount_minor_usd": 600,
          "amount_atomic": "6000000",
          "transport": "http",
          "merchant_settlement": "wallet_usdc",
          "human_approval_required": true,
          "approval_model": "intent_bound_signed_one_time",
          "configured": true
        }
      }
    },
    "machine_payments": {
      "prepaid_one_month": {
        "status": "live_ready",
        "protocol": "MPP",
        "provider": "stripe",
        "network": "tempo",
        "asset": "USDC.e",
        "merchant_settlement": "stripe_balance_fiat",
        "amount_minor_usd": 600,
        "billing_semantics": "founder_monthly_access",
        "recurring_autopay": false,
        "human_approval_required": true,
        "approval_model": "intent_bound_signed_one_time",
        "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent",
        "configured": true,
        "mode": "live",
        "live_enablement_requires_explicit_owner_approval": true,
        "supported_protocols": [
          "MPP",
          "x402"
        ],
        "rail_selection": "caller_selects_exactly_one_per_human_approval_artifact",
        "payment_options": {
          "mpp_tempo": {
            "status": "live_ready",
            "protocol": "MPP",
            "provider": "stripe",
            "network": "tempo",
            "asset": "USDC.e",
            "merchant_settlement": "stripe_balance_fiat",
            "amount_minor_usd": 600,
            "billing_semantics": "founder_monthly_access",
            "recurring_autopay": false,
            "human_approval_required": true,
            "approval_model": "intent_bound_signed_one_time",
            "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent",
            "configured": true,
            "mode": "live",
            "live_enablement_requires_explicit_owner_approval": true
          },
          "x402": {
            "status": "live_ready",
            "protocol": "x402",
            "version": 2,
            "scheme": "exact",
            "provider": "payai",
            "network": "eip155:8453",
            "asset": "USDC",
            "amount_minor_usd": 600,
            "amount_atomic": "6000000",
            "transport": "http",
            "merchant_settlement": "wallet_usdc",
            "human_approval_required": true,
            "approval_model": "intent_bound_signed_one_time",
            "configured": true
          }
        }
      },
      "recurring_stablecoin_30_day": {
        "status": "live_ready",
        "protocol": "MPP",
        "intent": "subscription",
        "provider": "stripe_settlement_with_native_tempo_subscription",
        "network": "tempo",
        "asset": "USDC.e",
        "merchant_settlement": "stripe_balance_fiat",
        "amount_minor_usd": 600,
        "billing_semantics": "founder_recurring_30_day_access",
        "period_count": 30,
        "period_unit": "day",
        "calendar_month_equivalent": false,
        "recurring_autopay": true,
        "scheduled_renewal": true,
        "authorization_lifetime_days": 360,
        "initial_human_approval_required": true,
        "renewal_human_approval_required": false,
        "payer_binding": "verified_tempo_wallet",
        "cancellation": {
          "stops_future_renewals": true,
          "preserves_current_paid_period": true,
          "customer_path": "/workspace/account"
        },
        "approval_model": "intent_bound_signed_initial_recurring_authorization",
        "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent",
        "purchase_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-subscription",
        "configured": true,
        "mode": "live",
        "live_enablement_requires_explicit_owner_approval": true
      }
    },
    "recurring_founder_price_minor": 600,
    "currency": "USD",
    "human_approval_required_before_purchase": true,
    "intent_bound_approval_artifact_required_for_machine_payment": true,
    "approval_intent_endpoint": "https://analytics.davisvillelabs.com/api/agent/v1/founder-approval-intent"
  }
}