openapi: 3.0.0
info:
  title: Zuplo Developer API Keys - Buckets Audit Logs API
  termsOfService: https://zuplo.com/legal/terms
  contact:
    name: Zuplo
    url: https://zuplo.com/
    email: support@zuplo.com
  description: The Zuplo Developer API (ZAPI) enables developers to programmatically manage API keys, consumers, buckets, tunnels, deployments, metering, audit logs, and more.
  version: 1.0.0
servers:
- url: https://dev.zuplo.com
  description: Zuplo Developer API
security:
- ApiKeyAuth: []
tags:
- name: Audit Logs
paths:
  /v1/accounts/{accountName}/audit-logs:
    get:
      operationId: AuditLogsService_list
      summary: Query Audit Logs
      description: Retrieves audit logs with optional filtering and pagination.
      parameters:
      - $ref: '#/components/parameters/Zuplo.Common.AccountParams'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.limit'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.offset'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.action'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.startDate'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.endDate'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.actor'
      - $ref: '#/components/parameters/Zuplo.AuditLogs.AuditLogsQuery.success'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zuplo.AuditLogs.AuditLogsResponse'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zuplo.HttpProblemDetails.BadRequestProblemResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zuplo.HttpProblemDetails.UnauthorizedProblemResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zuplo.HttpProblemDetails.InternalServerErrorProblemResponse'
      tags:
      - Audit Logs
components:
  schemas:
    Zuplo.HttpProblemDetails.InternalServerErrorProblemResponse:
      type: object
      required:
      - type
      - title
      properties:
        type:
          type: string
          enum:
          - https://httpproblems.com/http-status/500
        title:
          type: string
          enum:
          - Internal Server Error
      allOf:
      - type: object
        required:
        - type
        - title
        properties:
          type:
            type: string
          title:
            type: string
          detail:
            type: string
          instance:
            type: string
      example:
        type: https://httpproblems.com/http-status/500
        title: Internal Server Error
        status: 500
    Zuplo.HttpProblemDetails.UnauthorizedProblemResponse:
      type: object
      required:
      - type
      - title
      properties:
        type:
          type: string
          enum:
          - https://httpproblems.com/http-status/401
        title:
          type: string
          enum:
          - Unauthorized
      allOf:
      - type: object
        required:
        - type
        - title
        properties:
          type:
            type: string
          title:
            type: string
          detail:
            type: string
          instance:
            type: string
      example:
        type: https://httpproblems.com/http-status/401
        title: Unauthorized
        status: 401
    Zuplo.AuditLogs.Actor:
      type: object
      required:
      - sub
      - email
      - type
      - connection
      - actingAs
      - metadata
      properties:
        sub:
          type: string
          description: The subject identifier of the actor (user ID, API key, etc.)
        email:
          type: string
          nullable: true
          description: The email address of the actor (only for user actors)
        type:
          type: string
          description: The type of actor (e.g., 'user', 'consumer', 'service', 'anonymous')
        connection:
          type: string
          nullable: true
          description: The authentication connection used (e.g., 'auth0', 'google')
        actingAs:
          type: object
          allOf:
          - $ref: '#/components/schemas/Zuplo.AuditLogs.ActingAs'
          nullable: true
          description: Information about the user being impersonated, if any
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          description: Additional metadata about the actor
      description: Details about the actor who performed the action
    Zuplo.AuditLogs.AuditLogsPagination:
      type: object
      required:
      - limit
      - offset
      - total
      - hasMore
      properties:
        limit:
          type: integer
          format: int32
          description: Maximum number of results returned
        offset:
          type: integer
          format: int32
          description: Number of results skipped
        total:
          type: integer
          format: int32
          description: Total number of results available
        hasMore:
          type: boolean
          description: Whether there are more results available
      description: Pagination information for audit logs
    Zuplo.AuditLogs.Resource:
      type: object
      required:
      - type
      - id
      - metadata
      properties:
        type:
          type: string
          description: The type of resource (e.g., 'account', 'project', 'deployment')
        id:
          type: string
          description: The unique identifier of the resource
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          description: Additional metadata about the resource
      description: A resource affected by the action
    Zuplo.AuditLogs.AuditLog:
      type: object
      required:
      - action
      - metadata
      - actor
      - resources
      - context
      - route
      - timestamp
      - requestId
      - success
      - error
      properties:
        action:
          type: string
          description: The action that was performed (e.g., 'account.create', 'project.delete')
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          description: Additional metadata about the action
        actor:
          allOf:
          - $ref: '#/components/schemas/Zuplo.AuditLogs.Actor'
          description: Details about the actor who performed the action
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Zuplo.AuditLogs.Resource'
          nullable: true
          description: List of resources affected by this action
        context:
          allOf:
          - $ref: '#/components/schemas/Zuplo.AuditLogs.Context'
          description: Contextual information about where and how the action was performed
        route:
          allOf:
          - $ref: '#/components/schemas/Zuplo.AuditLogs.Route'
          description: Information about the API route that triggered this audit event
        timestamp:
          type: string
          format: date-time
          description: The timestamp when the action occurred
        requestId:
          type: string
          description: The unique request ID for correlation
        success:
          type: boolean
          nullable: true
          description: Whether the action was successful
        error:
          type: string
          nullable: true
          description: Error message if the action failed
      description: An audit log entry representing an action performed in the system
    Zuplo.AuditLogs.ActingAs:
      type: object
      required:
      - sub
      - email
      properties:
        sub:
          type: string
          description: The subject identifier of the user being impersonated
        email:
          type: string
          nullable: true
          description: The email address of the impersonated user (if available)
      description: Details about the user being impersonated, if applicable
    Zuplo.AuditLogs.AuditLogsResponse:
      type: object
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Zuplo.AuditLogs.AuditLog'
          description: Array of audit log entries
        pagination:
          allOf:
          - $ref: '#/components/schemas/Zuplo.AuditLogs.AuditLogsPagination'
          description: Pagination information
      description: Response containing a list of audit logs with pagination
    Zuplo.AuditLogs.Route:
      type: object
      required:
      - source
      - url
      - method
      properties:
        source:
          type: string
          nullable: true
          description: The source system or API that handled the request (e.g., 'api', 'gateway')
        url:
          type: string
          nullable: true
          description: The full URL path of the request
        method:
          type: string
          nullable: true
          description: The HTTP method used for the request
      description: Information about the API route that triggered this audit event
    Zuplo.HttpProblemDetails.BadRequestProblemResponse:
      type: object
      required:
      - type
      - title
      properties:
        type:
          type: string
          enum:
          - https://httpproblems.com/http-status/400
        title:
          type: string
          enum:
          - Bad Request
      allOf:
      - type: object
        required:
        - type
        - title
        properties:
          type:
            type: string
          title:
            type: string
          detail:
            type: string
          instance:
            type: string
      example:
        type: https://httpproblems.com/http-status/400
        title: Bad Request
        status: 400
    Zuplo.AuditLogs.Context:
      type: object
      required:
      - ipAddress
      - userAgent
      - country
      - region
      - city
      - postalCode
      - metroCode
      - asOrg
      properties:
        ipAddress:
          type: string
          nullable: true
          description: The IP address of the request
        userAgent:
          type: string
          nullable: true
          description: The user agent string of the request
        country:
          type: string
          nullable: true
          description: The ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB')
        region:
          type: string
          nullable: true
          description: The region/state code (e.g., 'CA' for California)
        city:
          type: string
          nullable: true
          description: The city name from which the request originated
        postalCode:
          type: string
          nullable: true
          description: The postal/ZIP code
        metroCode:
          type: string
          nullable: true
          description: The metro code (DMA code in the US)
        asOrg:
          type: string
          nullable: true
          description: The Autonomous System organization (ISP name)
      description: Contextual information about where and how the action was performed
  parameters:
    Zuplo.AuditLogs.AuditLogsQuery.success:
      name: success
      in: query
      required: false
      description: Filter by success status (true for successful, false for failed)
      schema:
        type: boolean
      explode: false
    Zuplo.AuditLogs.AuditLogsQuery.limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return (1-100)
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
      explode: false
    Zuplo.AuditLogs.AuditLogsQuery.offset:
      name: offset
      in: query
      required: false
      description: Number of results to skip for pagination
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
      explode: false
    Zuplo.AuditLogs.AuditLogsQuery.startDate:
      name: startDate
      in: query
      required: false
      description: Filter events after this date (ISO 8601 format)
      schema:
        type: string
        format: date-time
      explode: false
    Zuplo.Common.AccountParams:
      name: accountName
      in: path
      required: true
      description: The name of the account. You can find this in your Zuplo Portal under Settings > Project Information.
      schema:
        type: string
    Zuplo.AuditLogs.AuditLogsQuery.endDate:
      name: endDate
      in: query
      required: false
      description: Filter events before this date (ISO 8601 format)
      schema:
        type: string
        format: date-time
      explode: false
    Zuplo.AuditLogs.AuditLogsQuery.action:
      name: action
      in: query
      required: false
      description: Filter by specific action (e.g., 'account.create')
      schema:
        type: string
      explode: false
    Zuplo.AuditLogs.AuditLogsQuery.actor:
      name: actor
      in: query
      required: false
      description: Filter by actor email address or subject identifier
      schema:
        type: string
      explode: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Format: Bearer {api-key}'