davisvillelabs-com Agent API

openapi: 3.2.0
info:
  title: AI Analytics Interface Agent API
  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
tags:
- name: Agent
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
      tags:
      - Agent
  /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
      tags:
      - Agent
  /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
      tags:
      - Agent
  /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
      tags:
      - Agent
  /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
      tags:
      - Agent
  /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
      tags:
      - Agent
  /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 returned 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
      responses:
        '200':
          description: Purchase successful
        '400':
          description: Invalid request
        '401':
          description: Missing or invalid X-Purchase-Approval header
        '402':
          description: Payment required
        '503':
          description: Service unavailable
      tags:
      - Agent
  /api/agent/v1/usage:
    get:
      operationId: getAgentAnalyticsUsage
      summary: Fetch usage statistics for a public API key
      description: Returns usage counts for the public API key used in the request. No authentication beyond the public key is required.
      parameters:
      - name: api_key
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Usage data
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
components:
  schemas:
    SetupPlanRequest:
      type: object
      additionalProperties: false
      required:
      - product_id
      properties:
        product_id:
          type: string
          description: Identifier of the product to plan for.
        options:
          type: object
          additionalProperties: false
          properties:
            region:
              type: string
              enum:
              - us-east
              - eu-west