Eli Public API

openapi: 3.2.0
info:
  title: Eli Public 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: Public
  description: Anonymous, public-tenant-scoped resources.
paths:
  /api/scan:
    post:
      tags:
      - Public
      operationId: runPublicScan
      summary: Run or read the cached public visibility scan for a domain
      description: Anonymous and public-tenant isolated. The seven-day cache, domain lease and public request/cost caps are reused; callers cannot request a fresh-cache bypass.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
      responses:
        '200':
          description: Public scan result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResult'
        '400':
          description: Invalid domain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /llms.txt:
    get:
      tags:
      - Public
      operationId: getOwnLlmsTxt
      summary: Read Eli's published AI-readable summary
      responses:
        '200':
          description: Plain-text llms.txt.
          content:
            text/plain: {}
  /capabilities.json:
    get:
      tags:
      - Public
      operationId: getOwnCapabilities
      summary: Read Eli's published capabilities and public action URLs
      responses:
        '200':
          description: Published capabilities.
          content:
            application/json: {}
  /l/{slug}/llms.txt:
    get:
      tags:
      - Public
      operationId: getPublishedClientLlmsTxt
      summary: Read a customer's published AI-readable layer
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Published plain text.
          content:
            text/plain: {}
        '404':
          $ref: '#/components/responses/NotFound'
  /l/{slug}/capabilities.json:
    get:
      tags:
      - Public
      operationId: getPublishedClientCapabilities
      summary: Read a customer's published capabilities
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Published capabilities.
          content:
            application/json: {}
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ScanRequest:
      type: object
      required:
      - domain
      properties:
        domain:
          type: string
          example: example.com
      additionalProperties: false
    ScanResult:
      type: object
      required:
      - domain
      - score
      - readability
      - usability
      - scannedAt
      properties:
        domain:
          type: string
        score:
          type: integer
          minimum: 0
          maximum: 100
        visibility:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        readability:
          type: integer
          minimum: 0
          maximum: 100
        usability:
          type: integer
          minimum: 0
          maximum: 100
        quotes:
          type: array
          items:
            type: object
            additionalProperties: true
        gaps:
          type: array
          items:
            type: object
            additionalProperties: true
        scannedAt:
          type: string
          format: date-time
      additionalProperties: true
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type:
          - string
          - 'null'
        details:
          type:
          - object
          - 'null'
          additionalProperties: true
      additionalProperties: true
  responses:
    NotFound:
      description: The resource is not visible in this workspace.
      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'
  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.