# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/audit-log.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/audit-log.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Audit Log API
  version: 1.0.0
  description: >-
    Audit log: who asked for what, and what the answer was — one append-only entry per authorized
    request, carrying the principal, the action, the resource, the HTTP status and the request id.
    Filterable by any of those, readable one entry at a time, and exportable as a newline-delimited
    stream for archival before the retention window closes. A fully runtime-backed module — this
    spec is generated verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}.
    The project in the path is authorized by naturali and enforced upstream by the project's scoped
    credential.


    This module mirrors the upstream runtime verbatim (tier A): paths are the runtime's own
    re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape
    passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by
    naturali itself (authentication, project resolution, an unreachable runtime) use naturali's.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: "{baseUrl}"
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Audit Log
    description: Query the append-only audit log
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/audit-log:
    get:
      tags:
        - Audit Log
      summary: List audit entries
      description: Returns audit-log entries visible to the caller, newest first. All filters are optional
        and combine with AND. `resource_srn` is a prefix match (e.g. `srn:{project}:secret:` matches
        every secret action); every other filter is exact.
      operationId: listAuditEntries
      parameters:
        - name: action
          in: query
          description: Exact permission-action string, e.g. `secrets:DeleteSecret`
          schema:
            type: string
            example: secrets:DeleteSecret
        - name: principal_id
          in: query
          description: Public id of the principal (`user_…` or `key_…`)
          schema:
            type: string
        - name: resource_public_id
          in: query
          description: Exact target resource public id, e.g. `sec_…`
          schema:
            type: string
        - name: resource_srn
          in: query
          description: SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN
            is never rewritten; the filter matches it as stored.
          schema:
            type: string
        - name: from
          in: query
          description: Only entries created at or after this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Only entries created at or before this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Results per page. Above 200 it is clamped; below 1 or not an integer it is `400
            VALIDATION_FAILED`.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 25
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of audit entries
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/AuditEntry"
        "400":
          description: "`from` or `to` is not a valid ISO 8601 date, `limit` is not a valid page size, or
            `cursor` is malformed or was issued for other filters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/audit-log/export:
    get:
      tags:
        - Audit Log
      summary: Export audit entries as NDJSON
      description: "Streams a project's audit-log entries as newline-delimited JSON — one entry object per
        line, oldest first — for archival before the retention window expires, or for shipping into
        an external system. The export is per-project: `project_id` names it, or a project-bound
        credential implies its own. Filters behave exactly as they do on the list endpoint."
      operationId: exportAuditEntries
      x-mcp-exclude: true
      parameters:
        - name: action
          in: query
          description: Exact permission-action string, e.g. `secrets:DeleteSecret`
          schema:
            type: string
        - name: principal_id
          in: query
          description: Public id of the principal (`user_…` or `key_…`)
          schema:
            type: string
        - name: resource_public_id
          in: query
          description: Exact target resource public id, e.g. `sec_…`
          schema:
            type: string
        - name: resource_srn
          in: query
          description: SRN prefix match, e.g. `srn:{project}:secret:`. The log is append-only, so a stored SRN
            is never rewritten; the filter matches it as stored.
          schema:
            type: string
        - name: from
          in: query
          description: Only entries created at or after this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Only entries created at or before this timestamp (ISO 8601)
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: A newline-delimited stream of audit entries. Each line is a JSON object with the same
            fields as `AuditEntry`.
          content:
            application/x-ndjson:
              schema:
                type: string
        "400":
          description: "`project_id` is missing and the credential names no project, or `from`/`to` is present
            but not a valid ISO 8601 date"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/audit-log/{entry_id}:
    get:
      tags:
        - Audit Log
      summary: Get an audit entry
      description: Returns a single audit-log entry, including its `detail` payload
      operationId: getAuditEntry
      parameters:
        - name: entry_id
          in: path
          required: true
          description: Audit entry ID
          schema:
            type: string
            example: audit_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Audit entry details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditEntry"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Audit entry not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    AuditEntry:
      type: object
      properties:
        id:
          type: string
          example: audit_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
          nullable: true
          description: Project the action targeted; null for global actions
        principal_type:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/PrincipalType"
          description: "Who acted: `user` or `api_key`; null for platform-originated entries (those are
            identified by their `action`, e.g. `quotas:MonitorBreach`)"
        principal_id:
          type: string
          nullable: true
          description: Public id of the principal (`user_…` or `key_…`); null for platform-originated entries
        on_behalf_of:
          $ref: "#/components/schemas/OnBehalfOf"
        action:
          type: string
          description: The permission-action string that authorized the request
          example: secrets:DeleteSecret
        resource_srn:
          type: string
          nullable: true
          description: SRN the action targeted (type-level `srn:{project}:{type}:*` on creates)
          example: srn:proj_V1StGXR8Z5jdHi6B:secret:sec_V1StGXR8Z5jdHi6B
        resource_public_id:
          type: string
          nullable: true
          description: Target resource public id (from the SRN, or the response body on creates)
        status:
          type: integer
          description: HTTP status of the response
          example: 200
        request_id:
          type: string
          nullable: true
          description: Per-request correlation id (also returned in the X-Request-Id header)
        ip:
          type: string
          nullable: true
        user_agent:
          type: string
          nullable: true
        detail:
          type: object
          nullable: true
          description: Kind-specific payload. Multi-check routes record the remaining checks under
            `additional_checks`. Platform-originated entries set a `detail.kind` discriminator, e.g.
            `quota_monitor_breach` or `guardrail_evaluation`.
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
    PrincipalType:
      type: string
      enum:
        - user
        - api_key
        - agent
        - automation
        - approval
        - trigger
        - system
        - eval
        - decider
        - ingestion_rule
        - memory_rule
        - playbook_version
      description: What kind of principal acted. `user` and `api_key` are authenticated callers, and the
        id is the user's (`user_…`) or the key's own (`key_…`), so a record names which key acted
        rather than its owner. `agent` is an agent writing under its own identity (`agent_…`).
        `automation` is the task engine acting on a dispatch outcome and `approval` an approval
        resolution; neither carries an id. `trigger` is a trigger firing under its own `policy_ids`
        (`trg_…`). `system` is the platform itself, with an id naming the mechanism
        (`retention_sweep`, `zero_retention`). `eval`, `decider`, `ingestion_rule`, `memory_rule`
        and `playbook_version` are that resource's work running under its own `policy_ids` when
        nobody started it, the id its own.
      example: user
    OnBehalfOf:
      type: object
      nullable: true
      description: The tool call the write was made on behalf of, as the runtime records it; null for a
        write made as the credential alone. The `created_by_principal_*` pair stays the
        credential's.
      properties:
        tool_id:
          type: string
          nullable: true
          example: tool_V1StGXR8Z5jdHi6B
        agent_id:
          type: string
          nullable: true
          description: The agent whose turn called the tool
          example: agent_V1StGXR8Z5jdHi6B
        generation_id:
          type: string
          nullable: true
          description: The generation that called the tool
          example: gen_V1StGXR8Z5jdHi6B
        work_id:
          type: string
          nullable: true
          description: "The run-as work that called the tool: a playbook case or execution, a task, or an
            orchestration run"
          example: pbk_case_V1StGXR8Z5jdHi6B
        session_id:
          type: string
          nullable: true
          example: sess_V1StGXR8Z5jdHi6B
        actor_id:
          type: string
          nullable: true
          example: actor_V1StGXR8Z5jdHi6B
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`; omit it for the first page. A cursor this list did
        not issue is `400`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: "A connected app's OAuth access token, issued by this API's authorization server
        (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation,
        confined to the projects the user chose when approving the app."
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  responses:
    TooManyRequests:
      description: "`QUOTA_EXCEEDED` — a `requests` quota on the calling API key or its project is spent
        for the window; `Retry-After` says when it reopens"
      headers:
        Retry-After:
          description: Seconds until the quota window admits a request again
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Unexpected server error — `INTERNAL_ERROR`, with the raw message never forwarded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProjectNotFound:
      description: The project does not exist or the caller is not a member of it (`RESOURCE_NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
