Kernel Audit Logs API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Audit Logs API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Read audit log records for the authenticated organization.
  name: Audit Logs
paths:
  /audit-logs:
    get:
      description: API for searching audit logs. Limited to at most 30 day search, returns up to 100 records per page. Not recommended for bulk export.
      operationId: getAuditLogs
      parameters:
      - description: Lower bound (inclusive) for the audit record timestamp.
        in: query
        name: start
        required: true
        schema:
          example: '2026-01-01T00:00:00Z'
          format: date-time
          type: string
      - description: Upper bound (exclusive) for the audit record timestamp.
        in: query
        name: end
        required: true
        schema:
          example: '2026-01-02T00:00:00Z'
          format: date-time
          type: string
      - description: Filter by authentication strategy.
        in: query
        name: auth_strategy
        required: false
        schema:
          type: string
      - description: Filter by service name.
        in: query
        name: service
        required: false
        schema:
          type: string
      - description: Filter by HTTP method.
        in: query
        name: method
        required: false
        schema:
          type: string
      - description: Filter out results by HTTP method.
        explode: false
        in: query
        name: exclude_method
        required: false
        schema:
          items:
            type: string
          maxItems: 10
          type: array
        style: form
      - description: Free-text search over path, user ID, email, client IP, and status.
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Additional user IDs to OR into free-text search.
        explode: false
        in: query
        name: search_user_id
        required: false
        schema:
          items:
            type: string
          maxItems: 100
          type: array
        style: form
      - description: Maximum number of results to return.
        in: query
        name: limit
        required: false
        schema:
          default: 100
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque page token from X-Next-Page-Token for the next page of older records.
        in: query
        name: page_token
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AuditLogEntry'
                type: array
          description: A list of audit log records.
          headers:
            X-Has-More:
              description: Whether there are more records available beyond this page.
              schema:
                default: false
                type: boolean
            X-Limit:
              description: The limit applied to the returned records.
              schema:
                maximum: 100
                minimum: 1
                type: integer
            X-Next-Page-Token:
              description: Page token for the next page of older records, omitted when no more results.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List audit logs
      tags:
      - Audit Logs
  /audit-logs/export/chunk:
    get:
      description: Download an organization's audit log records for a time range as a file, for archival, compliance, or offline analysis. For interactive browsing, use GET /audit-logs.
      operationId: getAuditLogsExportChunk
      parameters:
      - description: Lower bound (inclusive) for the audit record timestamp.
        in: query
        name: start
        required: true
        schema:
          example: '2026-01-01T00:00:00Z'
          format: date-time
          type: string
      - description: Upper bound (exclusive) for the audit record timestamp.
        in: query
        name: end
        required: true
        schema:
          example: '2026-01-02T00:00:00Z'
          format: date-time
          type: string
      - description: Filter by authentication strategy.
        in: query
        name: auth_strategy
        required: false
        schema:
          type: string
      - description: Filter by service name.
        in: query
        name: service
        required: false
        schema:
          type: string
      - description: Filter by HTTP method.
        in: query
        name: method
        required: false
        schema:
          type: string
      - description: Filter out results by HTTP method.
        explode: false
        in: query
        name: exclude_method
        required: false
        schema:
          items:
            type: string
          maxItems: 10
          type: array
        style: form
      - description: Free-text search over path, user ID, email, client IP, and status.
        in: query
        name: search
        required: false
        schema:
          type: string
      - description: Additional user IDs to OR into free-text search.
        explode: false
        in: query
        name: search_user_id
        required: false
        schema:
          items:
            type: string
          maxItems: 100
          type: array
        style: form
      - description: Opaque cursor from X-Next-Cursor for the next chunk of older records.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - description: Maximum number of records to return in this chunk.
        in: query
        name: limit
        required: false
        schema:
          default: 50000
          maximum: 50000
          minimum: 1
          type: integer
      - description: Encoding for the returned chunk.
        in: query
        name: format
        required: false
        schema:
          default: jsonl.gz
          enum:
          - jsonl
          - jsonl.gz
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: One chunk of audit log records.
          headers:
            X-Content-Sha256:
              description: Hex SHA-256 of the response body.
              schema:
                pattern: ^[a-f0-9]{64}$
                type: string
            X-Has-More:
              description: Whether more records remain beyond this chunk.
              schema:
                default: false
                type: boolean
            X-Next-Cursor:
              description: Cursor for the next chunk of older records, empty when no more results.
              schema:
                type: string
            X-Row-Count:
              description: Number of records in this chunk.
              schema:
                maximum: 50000
                minimum: 0
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Download an audit-log export chunk
      tags:
      - Audit Logs
  /audit-logs/export/destinations:
    get:
      description: List audit log export destinations for the organization with pagination support.
      operationId: getAuditLogExportDestinations
      parameters:
      - description: Limit the number of destinations to return.
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Offset the number of destinations to return.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AuditLogExportDestination'
                type: array
          description: Audit log export destinations for the organization
          headers:
            X-Has-More:
              description: Whether there are more destinations to fetch.
              schema:
                default: false
                type: boolean
            X-Limit:
              description: Limit the number of destinations to return.
              schema:
                default: 20
                maximum: 100
                minimum: 1
                type: integer
            X-Next-Offset:
              description: The offset where the next page starts. 0 when there are no more results.
              schema:
                nullable: true
                type: integer
            X-Offset:
              description: The offset of destinations to return.
              schema:
                default: 0
                minimum: 0
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: List audit log export destinations
      tags:
      - Audit Logs
    post:
      description: Create a paused destination. Activate it with a status update once the destination test passes. Requires an active Enterprise plan.
      operationId: postAuditLogExportDestinations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuditLogExportDestinationRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogExportDestination'
          description: Audit log export destination created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Create an audit log export destination
      tags:
      - Audit Logs
  /audit-logs/export/destinations/{id}:
    parameters:
    - in: path
      name: id
      required: true
      schema:
        maxLength: 128
        type: string
    delete:
      description: Soft delete the destination and prevent new delivery attempts. An S3 upload already in progress may complete after the response.
      operationId: deleteAuditLogExportDestinationsById
      responses:
        '204':
          description: Audit log export destination deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Delete an audit log export destination
      tags:
      - Audit Logs
    get:
      description: Retrieve details for a single audit log export destination by its ID.
      operationId: getAuditLogExportDestinationsById
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogExportDestination'
          description: Audit log export destination
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Retrieve an audit log export destination
      tags:
      - Audit Logs
    patch:
      description: Apply a partial update to a destination. Requires an active Enterprise plan. Returns 409 when the destination was changed concurrently, because the merged configuration this request validated is no longer the one that would be stored; retry against fresh state. Pausing prevents new delivery attempts, but an S3 upload already in progress may complete after the response.
      operationId: patchAuditLogExportDestinationsById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAuditLogExportDestinationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogExportDestination'
          description: Audit log export destination updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Update an audit log export destination
      tags:
      - Audit Logs
  /audit-logs/export/destinations/{id}/test:
    post:
      description: Verify the destination is writable by assuming the configured role and uploading a temporary probe object with the same request metadata as a real delivery. Requires an active Enterprise plan.
      operationId: testAuditLogExportDestinationById
      parameters:
      - in: path
        name: id
        required: true
        schema:
          maxLength: 128
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogExportDestinationTestResult'
          description: Audit log export destination test result
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
      - bearerAuth: []
      summary: Test an audit log export destination
      tags:
      - Audit Logs
components:
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request – invalid input
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Conflict – resource already exists
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Forbidden – insufficient permissions or plan
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized – missing or invalid authorization token
  schemas:
    AuditLogExportDestinationTestResult:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              enum:
              - assume_role_failed
              - put_object_failed
              type: string
            message:
              type: string
          required:
          - code
          - message
          type: object
        stage:
          enum:
          - assume_role
          - put_object
          - complete
          type: string
        success:
          type: boolean
      required:
      - success
      - stage
      type: object
    AuditLogExportDestination:
      additionalProperties: false
      description: 'An organization-scoped audit log export destination.


        Delivery is at-least-once for rows visible when their window is committed: a delivery that is retried rewrites the same object, and the same `event_id` can appear in more than one object, so consumers must deduplicate on `event_id`. Each event-time window is held for ten minutes before it commits; a row that becomes visible after its window is committed may not be delivered.


        Objects are written as `<prefix>/destination_id=<destination>/org_id=<org>/date=<YYYY-MM-DD>/hour=<HH>/<window>-<chunk>.jsonl.gz`, where `date` and `hour` are the UTC calendar hour that fully contains every row in the object, so the layout is safe to register as a Hive-partitioned table. The object name is derived from the rows it holds, so a retried delivery rewrites its own object.'
      properties:
        bucket:
          maxLength: 63
          minLength: 3
          type: string
        consecutive_failures:
          minimum: 0
          readOnly: true
          type: integer
          x-go-type-skip-optional-pointer: true
          x-omitempty: false
        created_at:
          format: date-time
          readOnly: true
          type: string
          x-go-type-skip-optional-pointer: true
        external_id:
          maxLength: 128
          readOnly: true
          type: string
          x-go-type-skip-optional-pointer: true
        format:
          enum:
          - jsonl.gz
          type: string
        id:
          maxLength: 128
          readOnly: true
          type: string
          x-go-type-skip-optional-pointer: true
        kernel_role_arn:
          description: 'The Kernel role that assumes `role_arn` in your account to deliver logs. Allow this role as the principal in your role''s trust policy, and require `external_id` as the `sts:ExternalId` condition.


            Recreating a destination issues a new `external_id`, which the trust policy has to be updated to match.'
          maxLength: 2048
          readOnly: true
          type: string
          x-go-type-skip-optional-pointer: true
        kms_key_id:
          maxLength: 2048
          type: string
        last_error:
          description: Sanitized description of the most recent delivery failure.
          readOnly: true
          type: string
        last_error_at:
          format: date-time
          readOnly: true
          type: string
        last_exported_cursor:
          description: 'Opaque, versioned checkpoint for forward-only continuous export. This value is not compatible with audit-log list page tokens.


            Delivery starts at the moment the destination is activated, so events recorded before that are not delivered. Pausing stops delivery and resuming starts again from the time of the resume: events recorded while a destination was paused are never exported, and pausing is not a way to defer delivery.'
          readOnly: true
          type: string
        last_success_at:
          format: date-time
          readOnly: true
          type: string
        next_attempt_at:
          format: date-time
          readOnly: true
          type: string
        prefix:
          maxLength: 512
          type: string
        region:
          maxLength: 128
          minLength: 1
          type: string
        role_arn:
          maxLength: 2048
          minLength: 1
          type: string
        status:
          description: Pausing prevents new delivery attempts. An S3 upload already in progress may complete after the pause response; its rows can appear again after the destination is resumed.
          enum:
          - active
          - paused
          type: string
        type:
          enum:
          - s3
          type: string
        updated_at:
          format: date-time
          readOnly: true
          type: string
          x-go-type-skip-optional-pointer: true
      required:
      - id
      - type
      - region
      - bucket
      - prefix
      - role_arn
      - external_id
      - kernel_role_arn
      - format
      - status
      - consecutive_failures
      - created_at
      - updated_at
      type: object
    UpdateAuditLogExportDestinationRequest:
      additionalProperties: false
      properties:
        bucket:
          maxLength: 63
          minLength: 3
          type: string
        kms_key_id:
          description: KMS key ID, alias, or ARN. Set to an empty string to remove the configured KMS key; omit or send null to leave unchanged.
          maxLength: 2048
          type: string
        prefix:
          maxLength: 512
          type: string
        region:
          maxLength: 128
          minLength: 1
          type: string
        role_arn:
          maxLength: 2048
          minLength: 1
          type: string
        status:
          enum:
          - active
          - paused
          type: string
      type: object
    AuditLogEntry:
      properties:
        auth_strategy:
          description: Authentication strategy used for the request.
          type: string
        client_ip:
          description: Client IP address.
          type: string
        domain:
          description: Request host.
          type: string
        duration_ms:
          description: Request duration in milliseconds.
          type: integer
        email:
          description: Email of the authenticated user at request time, if any.
          type: string
        method:
          description: HTTP method.
          type: string
        path:
          description: Request path.
          type: string
        route:
          description: Matched API route pattern, if available.
          type: string
        status:
          description: HTTP response status code.
          type: integer
        timestamp:
          description: UTC time when the request was received.
          format: date-time
          type: string
        user_agent:
          description: User agent header.
          type: string
        user_id:
          description: ID of the authenticated user, if any.
          type: string
      required:
      - timestamp
      - auth_strategy
      - user_id
      - email
      - status
      - method
      - path
      - route
      - domain
      - duration_ms
      - client_ip
      - user_agent
      type: object
    ErrorDetail:
      properties:
        code:
          description: Lower-level error code providing more specific detail
          example: invalid_input
          type: string
        message:
          description: Further detail about the error
          example: Provided version string is not semver compliant
          type: string
      type: object
    CreateAuditLogExportDestinationRequest:
      additionalProperties: false
      properties:
        bucket:
          maxLength: 63
          minLength: 3
          type: string
        format:
          enum:
          - jsonl.gz
          type: string
        kms_key_id:
          maxLength: 2048
          type: string
        prefix:
          maxLength: 512
          type: string
        region:
          maxLength: 128
          minLength: 1
          type: string
        role_arn:
          maxLength: 2048
          minLength: 1
          type: string
        type:
          enum:
          - s3
          type: string
      required:
      - type
      - region
      - bucket
      - prefix
      - role_arn
      - format
      type: object
    Error:
      properties:
        code:
          description: Application-specific error code (machine-readable)
          example: bad_request
          type: string
        details:
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
          type: string
      required:
      - code
      - message
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
x-service-info:
  categories:
  - browsers
  docs:
    apiReference: https://www.kernel.sh/docs
    homepage: https://www.kernel.sh
    llms: https://api.onkernel.com/llms.txt
x-provenance:
  method: harvested
  publisher: Kernel
  source: https://api.onkernel.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)