Ada Audit Log API

openapi: 3.2.0
info:
  title: Knowledge Audit Log API
  version: 1.0.0
servers:
- url: https://example.ada.support/api
  description: Production
tags:
- name: auditLog
paths:
  /v2/analytics/audit-log/events/:
    get:
      operationId: list-audit-log-events
      summary: List Audit log events
      description: 'Retrieve the authenticated account''s own Audit log events, newest first, in cursor-paginated pages. Intended for pulling the Audit log into a SIEM.


        Pagination is cursor-based: read `meta.next_page_url` and replay it verbatim to fetch the next page. `next_page_url` is `null` on the last or empty page. The time window and `cursor` must be held constant across pages; the recommended way to guarantee this is to replay the returned `next_page_url` unchanged.


        No field filters are exposed: callers pull the full time window and filter on their own side (the SIEM).


        Validation errors (missing or invalid `start_date` or `end_date`, a window wider than 30 days, a malformed cursor, or a window change mid-pagination) return `400`.


        Rate limits (per account): 10 requests per second, 120 per minute, and 40,000 per day. A `429` means a limit was exceeded; back off and retry. For ongoing ingestion, poll on a steady cadence (for example, every few minutes) rather than in a tight loop.


        Backfilling vs incremental pulls: a single request covers at most 30 days. To backfill more history, issue successive requests over adjacent windows of up to 30 days. For incremental pulls, set `start_date` to just after the newest `timestamp` you have already stored, then follow `next_page_url` until it is `null`.'
      tags:
      - auditLog
      parameters:
      - name: start_date
        in: query
        description: Start of the time window (inclusive), ISO 8601. The window (`end_date - start_date`) may not exceed 30 days.
        required: true
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: End of the time window (inclusive), ISO 8601. When omitted it defaults to the request time (UTC); the resolved value is reflected in `next_page_url`, so replay the returned `next_page_url` verbatim to keep the window fixed across pages.
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Maximum events per page. Out-of-range or non-integer values are rejected with `400`; the applied limit is not echoed in the response.
        required: false
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        description: 'Opaque base64-encoded pagination cursor from a previous response''s `meta.next_page_url`. Treat it as an opaque token, not an id. The time window and `cursor` must be held constant across pages: replay the returned `next_page_url` unchanged.'
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A cursor-paginated page of Audit log events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogEventList'
        '400':
          description: Bad Request (validation, cursor, or window drift)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized (missing or non-Bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found (Audit log API not enabled for this account)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests (rate limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas:
    AuditLogEventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEvent'
          description: The page of Audit log events (at most `limit` items)
        meta:
          $ref: '#/components/schemas/AuditLogEventListMeta'
          description: Pagination metadata
      required:
      - data
      - meta
      description: A cursor-paginated page of Audit log events
      title: AuditLogEventList
    AuditLogEventListMeta:
      type: object
      properties:
        next_page_url:
          type:
          - string
          - 'null'
          description: URL for the next page of results, or `null` on the last or empty page. Replay it unchanged to keep the time window and the cursor constant across pages.
      description: Pagination metadata
      title: AuditLogEventListMeta
    ErrorsErrorsItems:
      type: object
      properties:
        type:
          type: string
          description: The error type
        message:
          type: string
          description: The error message
        details:
          type:
          - string
          - 'null'
          description: Extra information about the error
      required:
      - type
      - message
      title: ErrorsErrorsItems
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorsErrorsItems'
          description: A list of errors
      required:
      - errors
      title: Errors
    AuditLogEvent:
      type: object
      properties:
        id:
          type: string
          description: Globally unique event id (uuid4)
        timestamp:
          type: string
          format: date-time
          description: When the change occurred (ISO 8601, UTC, millisecond precision)
        actor_email:
          type: string
          description: Email of the user who made the change, or the owner of a dashboard-created Platform API key. Empty for system and service-token actors.
        actor_name:
          type: string
          description: Display name of the actor; empty when unavailable
        actor_user_id:
          type: string
          description: User id of the actor. For an API key, the id of the user who created the key. Empty for system and service-token actors.
        entity_type:
          type: string
          description: The type of entity that was changed
        entity_id:
          type: string
          description: The id of the entity that was changed
        entity_name:
          type: string
          description: A human-readable name for the changed entity
        activity:
          type: string
          description: What happened to the entity. One of `created`, `updated`, `deleted`, `executed`, `invited`, `activated`, or `deactivated`.
        interface:
          type: string
          description: Where the change originated, such as `dashboard`, `api`, `mcp`, `cli`, `import`, `export`, or `system` (background jobs and Ada's internal processing).
        context_ip:
          type: string
          description: Source IP address of the request that made the change
        context_user_agent:
          type: string
          description: User agent string of the request that made the change
        api_key_name:
          type: string
          description: Name of the API key used, when the change was made by a dashboard-created Platform API key; empty otherwise.
      required:
      - id
      - timestamp
      - entity_type
      - entity_id
      - activity
      description: 'A single Audit log event: one configuration change recorded for the account. Empty-string fields mean the value was unavailable for that event (for example, a system actor has no email).'
      title: AuditLogEvent
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer