Eli Own-site execution API

openapi: 3.2.0
info:
  title: Eli Own-site execution 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: Own-site execution
  description: Confirmed, capped and audited decisions.
paths:
  /api/v2/crawler-events:
    post:
      tags:
      - Own-site execution
      operationId: ingestCrawlerEvents
      summary: Ingest a batch of customer server or CDN request events
      description: Requires an Eli API key with write:own-site and a fresh verified domain. Eli classifies known AI crawlers before storage and discards IP addresses, query strings, referrers and full user agents.
      security:
      - eliApiKey: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - events
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 5000
                  items:
                    type: object
                    required:
                    - timestamp
                    - hostname
                    - request_path
                    - request_method
                    - status_code
                    - user_agent
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                      hostname:
                        type: string
                      request_path:
                        type: string
                      request_method:
                        type: string
                        enum:
                        - GET
                        - HEAD
                      status_code:
                        type: integer
                        minimum: 100
                        maximum: 599
                      user_agent:
                        type: string
      responses:
        '200':
          description: The accepted AI crawler events were aggregated. No raw personal data was stored.
        '400':
          description: Invalid batch.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A fresh verified website domain is required.
        '413':
          description: The request, event count or aggregate count exceeds the bounded limit.
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/onsite-changes/{id}:
    post:
      tags:
      - Own-site execution
      operationId: decideOnsiteChange
      summary: Approve, apply, revert or dismiss an on-site change
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnsiteDecisionRequest'
      responses:
        '200':
          description: The decision completed. The response is a machine-readable receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolReceipt'
        '400':
          description: Invalid JSON body, action, resource ID or publication target. No write occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Literal confirmation or the exact current preview hash is missing/stale, or the resource lifecycle conflicts with the decision. No unverified write should be assumed.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ConfirmationRequired'
                - $ref: '#/components/schemas/Error'
        '422':
          description: Stored content failed the mandatory safety or evidence gate. Nothing was published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/onsite-proposals:
    post:
      tags:
      - Own-site execution
      operationId: prepareHighestPriorityOnsiteProposal
      summary: Prepare the highest-priority existing-page proposal
      description: Selects a measured losing buyer question and matching verified owned page, or reuses unfinished work. It creates a reviewable proposal only and never approves or applies it.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      responses:
        '200':
          description: A proposal was prepared/reused, or no safe match was available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnsiteProposalResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/content-drafts/{id}:
    post:
      tags:
      - Own-site execution
      operationId: decideContentDraft
      summary: Approve, publish, revert, or dismiss a content draft
      description: Publication uses the connected CMS and its verified target. Revert moves only an exact Eli-created native WordPress post to trash, verifies that state, preserves the historical publication receipt and returns an immutable reversal receipt.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentDecisionRequest'
      responses:
        '200':
          description: The decision completed. The response is a machine-readable receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolReceipt'
        '400':
          description: Invalid JSON body, action, resource ID or publication target. No write occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Literal confirmation or the exact current preview hash is missing/stale, or the resource lifecycle conflicts with the decision. No unverified write should be assumed.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ConfirmationRequired'
                - $ref: '#/components/schemas/Error'
        '422':
          description: Stored content failed the mandatory safety or evidence gate. Nothing was published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/corrections/{id}:
    post:
      tags:
      - Own-site execution
      operationId: decideCorrection
      summary: Approve or dismiss a tenant-scoped correction
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrectionDecisionRequest'
      responses:
        '200':
          description: The decision completed. The response is a machine-readable receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolReceipt'
        '400':
          description: Invalid JSON body, action, resource ID or publication target. No write occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Literal confirmation or the exact current preview hash is missing/stale, or the resource lifecycle conflicts with the decision. No unverified write should be assumed.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ConfirmationRequired'
                - $ref: '#/components/schemas/Error'
        '422':
          description: Stored content failed the mandatory safety or evidence gate. Nothing was published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v2/layer/publish:
    post:
      tags:
      - Own-site execution
      operationId: publishAiLayer
      summary: Publish the reviewed AI-readable layer
      description: Publishes the current draft through the tenant-scoped RPC and requests discovery refresh. It does not enable autonomy or send to third parties.
      security:
      - eliApiKey: []
      - eliUserToken: []
      parameters:
      - $ref: '#/components/parameters/WorkspaceHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayerDecisionRequest'
      responses:
        '200':
          description: The decision completed. The response is a machine-readable receipt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolReceipt'
        '400':
          description: Invalid JSON body, action, resource ID or publication target. No write occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Literal confirmation or the exact current preview hash is missing/stale, or the resource lifecycle conflicts with the decision. No unverified write should be assumed.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ConfirmationRequired'
                - $ref: '#/components/schemas/Error'
        '422':
          description: Stored content failed the mandatory safety or evidence gate. Nothing was published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
    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'
    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'
    Forbidden:
      description: Workspace, role, scope, plan or feature does not permit this operation.
      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
    OnsiteProposalResponse:
      type: object
      required:
      - decision
      - resourceId
      - status
      - prepared
      - selected
      - approvalRequired
      - nextAction
      - changedByThisRequest
      properties:
        decision:
          type: string
          enum:
          - prepare
        resourceId:
          type: string
        status:
          type: string
          enum:
          - ready
          - no_match
          - connection_required
        prepared:
          type: boolean
        selected:
          type: object
          required:
          - changeId
          - promptId
          - pageUrl
          - reused
          - workflowStatus
          - applicationMode
          properties:
            changeId:
              type:
              - string
              - 'null'
              format: uuid
            promptId:
              type:
              - string
              - 'null'
              format: uuid
            pageUrl:
              type:
              - string
              - 'null'
              format: uri
            reused:
              type: boolean
            workflowStatus:
              type:
              - string
              - 'null'
              enum:
              - draft
              - approved
              - applying
              - reverting
              - null
            applicationMode:
              type:
              - string
              - 'null'
              enum:
              - native_wordpress
              - manual_cms_handoff
              - null
          additionalProperties: false
        previewEndpoint:
          type:
          - string
          - 'null'
        decisionEndpoint:
          type:
          - string
          - 'null'
        approvalRequired:
          type: boolean
        nextAction:
          type:
          - string
          - 'null'
          enum:
          - approve
          - apply
          - publish_handoff_then_verify
          - wait
          - null
        nextActionHint:
          type:
          - string
          - 'null'
        changedByThisRequest:
          type: boolean
          enum:
          - false
        caps:
          type:
          - object
          - 'null'
          additionalProperties: true
        audit_id:
          type:
          - string
          - 'null'
          format: uuid
      additionalProperties: false
    CorrectionDecisionRequest:
      type: object
      required:
      - action
      description: Requires write:own-site for an API key.
      properties:
        action:
          type: string
          enum:
          - approve
          - dismiss
        confirm:
          $ref: '#/components/schemas/LiteralConfirmation'
        confirmed_preview_hash:
          $ref: '#/components/schemas/PreviewHash'
      additionalProperties: false
    PreviewHash:
      type: string
      pattern: ^[a-f0-9]{64}$
      description: SHA-256 confirmation binding for the exact tool, workspace, resource and preview returned by the immediately preceding preview response.
    ContentDecisionRequest:
      type: object
      required:
      - action
      description: approve_publish and revert require write:drafts and write:own-site for an API key. dismiss requires write:drafts. Revert is limited to exact Eli-created native WordPress posts and remains available after downgrade.
      properties:
        action:
          type: string
          enum:
          - approve_publish
          - revert
          - dismiss
        confirm:
          $ref: '#/components/schemas/LiteralConfirmation'
        confirmed_preview_hash:
          $ref: '#/components/schemas/PreviewHash'
        provider:
          type: string
          enum:
          - wordpress
          - webflow
          - shopify
          - contentful
          - sanity
          - strapi
          - generic_api
          - manual_url
          description: Optional connected CMS choice. Use manual_url only with publication_url after the page is publicly live.
        publication_url:
          type: string
          format: uri
          maxLength: 2000
          description: Exact public URL used only with provider manual_url so Eli can verify a human publication handoff.
      additionalProperties: false
    OnsiteDecisionRequest:
      type: object
      required:
      - action
      properties:
        action:
          type: string
          enum:
          - approve
          - apply
          - revert
          - dismiss
        confirm:
          $ref: '#/components/schemas/LiteralConfirmation'
        confirmed_preview_hash:
          $ref: '#/components/schemas/PreviewHash'
      additionalProperties: false
    ConfirmationRequired:
      type: object
      required:
      - error
      - message
      - required
      - preview_hash
      - preview
      properties:
        error:
          type: string
          enum:
          - confirmation_required
        message:
          type: string
          description: Plain instruction to show the preview and re-call only after human approval.
        required:
          type: object
          required:
          - confirm
          - confirmed_preview_hash
          properties:
            confirm:
              $ref: '#/components/schemas/LiteralConfirmation'
            confirmed_preview_hash:
              $ref: '#/components/schemas/PreviewHash'
          additionalProperties: false
        preview_hash:
          $ref: '#/components/schemas/PreviewHash'
        preview:
          type: object
          additionalProperties: true
          description: The current before/after diff, draft or layer evidence. No write occurred.
      additionalProperties: true
    ProtocolReceipt:
      type: object
      required:
      - decision
      - resourceId
      - status
      - url
      - revertible
      - revert_hint
      - caps
      - audit_id
      properties:
        decision:
          type: string
          description: The exact accepted operation.
          example: apply
        resourceId:
          type: string
          description: The decided resource ID.
        status:
          type: string
          description: The state Eli verified after the decision.
          example: applied
        url:
          type:
          - string
          - 'null'
          format: uri
        revertible:
          type: boolean
          description: Whether Eli exposes a guarded machine revert for this completed action.
        revert_hint:
          type:
          - string
          - 'null'
          description: The exact safe next step for a revert or immutable follow-up.
        caps:
          type:
          - object
          - 'null'
          required:
          - used
          - limit
          - window
          properties:
            used:
              type: integer
              minimum: 0
            limit:
              type: integer
              minimum: 0
            window:
              type: string
              enum:
              - day
          additionalProperties: false
          description: Durable protocol write counter returned by the shared execution core.
        audit_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Durable protocol-decision audit row for this machine write.
        change_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Exact owned-site change reconciled by a content rollback, when applicable.
        publication_receipt_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Immutable publication receipt preserved across rollback.
        reversal_receipt_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Immutable verified rollback receipt, when rollback completed.
      additionalProperties: true
    LayerDecisionRequest:
      type: object
      description: Requires write:own-site for an API key.
      properties:
        confirm:
          $ref: '#/components/schemas/LiteralConfirmation'
        confirmed_preview_hash:
          $ref: '#/components/schemas/PreviewHash'
      additionalProperties: false
    LiteralConfirmation:
      type: boolean
      enum:
      - true
      description: Must be the JSON boolean true. Strings, numbers and free-text phrases are rejected.
  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.