Eli Buyer Agent API

openapi: 3.2.0
info:
  title: Eli Buyer Agent API
  version: 2.0.0
  description: 'Eli is your AI growth team: AI agents that do your marketing work every day. You approve what matters. This API reads Eli''s evidence, from AI answers and the website, and executes reviewed own-site changes through Eli''s guarded decision core. Shipping writes require literal JSON confirmation, plan and protocol caps, an owner/admin principal, and an audit receipt. Third-party sends and autonomy switches are not exposed.'
  contact:
    name: Eli
    url: https://www.hireeli.io
servers:
- url: https://www.hireeli.io
tags:
- name: Buyer Agent
  description: Privacy-safe answer-to-pipeline reads and bounded writes.
paths:
  /api/v2/buyers:
    get:
      tags:
      - Buyer Agent
      operationId: listAiBuyerContexts
      summary: List privacy-safe AI Buyer Contexts
      description: Ranks tenant-pinned contexts by a transparent intent score. Probable and visitor-confirmed intent remain distinct; PII is excluded.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      - name: minimum_score
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: source
        in: query
        schema:
          type: string
      - name: intent
        in: query
        schema:
          type: string
      - name: stage
        in: query
        schema:
          type: string
      - name: variant
        in: query
        schema:
          type: string
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Paginated non-PII Buyer Context projections.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyers/{id}:
    get:
      tags:
      - Buyer Agent
      operationId: readAiBuyerContext
      summary: Read one answer-to-pipeline journey
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Inference, confirmation, evidence pack, action, timeline and outcomes without contact PII.
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-agent/state:
    get:
      tags:
      - Buyer Agent
      operationId: readBuyerAgentState
      summary: Read readiness and configuration
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: State, readiness, configuration and counts.
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-agent/report:
    get:
      tags:
      - Buyer Agent
      operationId: readAnswerToPipelineReport
      summary: Read funnel and experiment evidence
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Treatment/control counts, evidence grades, funnel, gaps and completeness.
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-agent/actions:
    get:
      tags:
      - Buyer Agent
      operationId: listBuyerActions
      summary: List prepared conversion actions
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Tenant-pinned action registry and verification state.
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-agent/actions/prepare:
    post:
      tags:
      - Buyer Agent
      operationId: prepareBuyerActions
      summary: Prepare evidence packs and actions without activating public behavior
      description: Requires write:drafts. Reuses already published evidence, makes no model call, leaves ambiguous external hosts in draft and never launches the Buyer Agent.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Preparation receipt with blockers and zero-provider cost.
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-agent/context-handoff:
    post:
      tags:
      - Buyer Agent
      operationId: createBuyerContextHandoff
      summary: 'Retired: answers 410 eli_convert_v1_retired'
      description: 'Retired (r65). Eli Convert v1 is retired: the site tag no longer draws it, so no handoff link is made. Every call answers 410 with error eli_convert_v1_retired and changes nothing.'
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - question_id
              - destination_url
              properties:
                question_id:
                  type: string
                  format: uuid
                destination_url:
                  type: string
                  format: uri
      responses:
        '403':
          $ref: '#/components/responses/Forbidden'
        '410':
          description: 'Eli Convert v1 is retired: nothing was made or changed.'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v2/buyer-agent/experiment:
    post:
      tags:
      - Buyer Agent
      operationId: configureBuyerAgentExperiment
      summary: Pause the measured Buyer Agent test (Eli Convert v1 is retired)
      description: 'Eli Convert v1 is retired (r65): the site tag no longer draws it. State live_test (a start, a resume or a new share) answers 410 eli_convert_v1_retired and changes nothing. Pausing (state paused) works as before in two steps: the first call returns 409 confirmation_required with the complete behavior, its preview hash and the required fields, and the second call confirms with literal user_confirmed true and confirmed_preview_hash. Role and caps are rechecked on every call.'
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: Configuration receipt of the pause.
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Confirmation required (with the preview), or confirmation stale (the hash is missing or the configuration changed).
        '410':
          description: 'A start, resume or new share: Eli Convert v1 is retired, nothing was changed.'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/buyer-outcomes:
    post:
      tags:
      - Buyer Agent
      operationId: recordBuyerOutcome
      summary: Append a member-attested pipeline outcome
      description: Requires write:own-site. REST assertions are member-attested and can never become CRM-verified; signed CRM ingestion is the only CRM evidence path.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - context_id
              - stage
              - occurred_at
              - idempotency_key
              properties:
                context_id:
                  type: string
                  format: uuid
                stage:
                  type: string
                  enum:
                  - lead
                  - qualified
                  - meeting_booked
                  - meeting_held
                  - opportunity_created
                  - closed_won
                  - closed_lost
                  - disqualified
                occurred_at:
                  type: string
                  format: date-time
                idempotency_key:
                  type: string
                value_cents:
                  type: integer
                  minimum: 0
                currency:
                  type: string
                  pattern: ^[A-Z]{3}$
      responses:
        '200':
          description: Append-only member-attested outcome receipt.
        '400':
          description: Invalid outcome; nothing changed.
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    WorkspaceHeader:
      name: x-eli-tenant
      in: header
      required: false
      description: Workspace UUID. Required for user tokens with multiple memberships. For API keys it is only an equality assertion against the key-pinned workspace.
      schema:
        type: string
        format: uuid
    ResourceId:
      name: id
      in: path
      required: true
      description: Tenant-scoped resource UUID.
      schema:
        type: string
        format: uuid
  responses:
    NotFound:
      description: The resource is not visible in this workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Credential missing, invalid, expired or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Workspace, role, scope, plan or feature does not permit this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Request or durable protocol cap reached.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds before the in-memory request window resets, when applicable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: A required security, billing, cap, audit, evidence or storage check is unavailable. Writes fail closed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type:
          - string
          - 'null'
        details:
          type:
          - object
          - 'null'
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    eliApiKey:
      type: http
      scheme: bearer
      bearerFormat: ELI_API_KEY
      description: A scoped key in the eli_live_<key_id>_<secret> format. The plaintext is shown only when the key is created. The validated key row pins the workspace.
    eliUserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A current Eli/Supabase user access token. Row-level security and current owner/admin membership govern writes.