BuildWorkPro Observability API

openapi: 3.2.0
info:
  title: BuildWorkPro Observability API
  version: 1.0.0
  description: Construction project management, CRM, and workflows — public REST API.
  contact:
    name: BuildWorkPro Developers
    email: developers@buildworkpro.com
  license:
    name: Proprietary
    url: https://buildworkpro.com/terms
servers:
- url: https://app.buildworkpro.com/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Observability
  description: API audit logs and usage metering for the authenticated organization.
paths:
  /api-audit-logs:
    get:
      operationId: listApiAuditLogs
      summary: List API audit log entries for the calling tenant
      description: Returns cursor-paginated API audit log rows for the calling tenant. Each row records one v1 API request — method, path, status, duration, request id, and (when authenticated) the API key id, OAuth token id, or user id that made the call. Filterable by API key, HTTP method, status code, and date range. Tenant-scoped — Tenant A can never see Tenant B's audit log even if scopes are mis-issued.
      security:
      - bearerAuth:
        - audit:read
      tags:
      - Observability
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
        required: false
        name: limit
        in: query
      - schema:
          type: string
        required: false
        name: cursor
        in: query
      - schema:
          type: integer
          minimum: 1
        required: false
        name: apiKeyId
        in: query
      - schema:
          type: string
        required: false
        name: method
        in: query
      - schema:
          type:
          - integer
          - 'null'
        required: false
        name: status
        in: query
      - schema:
          type: string
          format: date-time
          description: ISO 8601 lower bound for createdAt (inclusive)
        required: false
        description: ISO 8601 lower bound for createdAt (inclusive)
        name: dateFrom
        in: query
      - schema:
          type: string
          format: date-time
          description: ISO 8601 upper bound for createdAt (inclusive)
        required: false
        description: ISO 8601 upper bound for createdAt (inclusive)
        name: dateTo
        in: query
      responses:
        '200':
          description: Audit log page
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiAuditLog'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Scope insufficient
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-rate-limit-cost: 1
  /usage:
    get:
      operationId: getUsage
      summary: Get current rate-limit consumption
      description: Returns the calling tenant's current rate-limit consumption for both the tenant-wide cost-weighted budget (sliding hour) and the per-API-key request limit (sliding minute). Use this to surface live consumption in developer dashboards or to back off proactively before hitting `429`. Data is sourced from the same Redis-backed buckets that the rate limiter writes to, so the numbers returned here are exactly the limits enforced.
      security:
      - bearerAuth:
        - audit:read
      tags:
      - Observability
      responses:
        '200':
          description: Current usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UsageResponse'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '403':
          description: Scope insufficient
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      x-rate-limit-cost: 1
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: URL identifying the problem type
        title:
          type: string
          description: Short human-readable summary
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation
        request_id:
          type: string
          description: Server-generated request identifier
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field path that failed validation
              code:
                type: string
                description: Validation error code
              message:
                type: string
                description: Human-readable validation message
            required:
            - field
            - code
            - message
          description: Validation error array (422 only)
      required:
      - type
      - title
      - status
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Server-generated request identifier
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
    UsageResponse:
      type: object
      properties:
        tenant:
          type: object
          properties:
            limit:
              type: integer
            used:
              type: integer
            remaining:
              type: integer
            resetSeconds:
              type: integer
            windowSeconds:
              type: integer
          required:
          - limit
          - used
          - remaining
          - resetSeconds
          - windowSeconds
          description: Tenant-wide cost-weighted budget (sliding hour window)
        apiKey:
          type:
          - object
          - 'null'
          properties:
            limit:
              type: integer
            used:
              type: integer
            remaining:
              type: integer
            resetSeconds:
              type: integer
            windowSeconds:
              type: integer
          required:
          - limit
          - used
          - remaining
          - resetSeconds
          - windowSeconds
          description: Per-API-key request limit (sliding minute window). Null when the caller is OAuth/refresh-token authenticated (not an API key).
      required:
      - tenant
      - apiKey
    PaginationMeta:
      type: object
      properties:
        cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page; null when no more results
        has_more:
          type: boolean
          description: Whether more pages are available after this one
        count:
          type: integer
          description: Items in this page
      required:
      - cursor
      - has_more
      - count
    ApiAuditLog:
      type: object
      properties:
        id:
          type: integer
        tenantId:
          type: integer
        apiKeyId:
          type:
          - integer
          - 'null'
        oauthTokenId:
          type:
          - integer
          - 'null'
        userId:
          type:
          - integer
          - 'null'
        method:
          type: string
        path:
          type: string
        status:
          type: integer
        durationMs:
          type: integer
        requestId:
          type: string
        ip:
          type:
          - string
          - 'null'
        userAgent:
          type:
          - string
          - 'null'
        errorCode:
          type:
          - string
          - 'null'
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
      required:
      - id
      - tenantId
      - apiKeyId
      - oauthTokenId
      - userId
      - method
      - path
      - status
      - durationMs
      - requestId
      - ip
      - userAgent
      - errorCode
      - createdAt
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bwp_live_... or bwp_test_...
      description: Long-lived tenant-wide API key. Provision in Settings → Developer → API Keys.
    oauth2:
      type: oauth2
      description: OAuth 2.1 per-user token. Available in Phase 4.
      flows:
        authorizationCode:
          authorizationUrl: https://app.buildworkpro.com/api/v1/oauth/authorize
          tokenUrl: https://app.buildworkpro.com/api/v1/oauth/token
          refreshUrl: https://app.buildworkpro.com/api/v1/oauth/token
          scopes: {}