# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/audit-log.yaml (runtime 0.71.2)
#  + 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, #304): 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: Number of results per page (1–200, default 25)
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 25
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: A page of audit entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/AuditEntry"
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        "400":
          description: "`from` or `to` is present but not a valid ISO 8601 date"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "500":
          description: Internal server error
    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. `project_id` is required: the export is per-project by design. 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 required, or `from`/`to` is present but not a valid ISO 8601 date"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
    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
      x-naturali-resource:
        kind: audit
        from: entry_id
      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"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Audit entry not found
    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:
          type: string
          nullable: true
          enum:
            - user
            - api_key
            - null
          description: Principal kind; 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
        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
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
  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.