BuildWorkPro Briefing API

openapi: 3.2.0
info:
  title: BuildWorkPro Briefing 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: Briefing
  description: Per-user Dismiss / Snooze of rows on the "Needs you today" morning briefing.
paths:
  /dashboard/briefing/dismissals:
    post:
      summary: Dismiss or snooze a briefing row
      description: 'Hides one "Needs you today" row for the credential''s user. `until` of `7d` / `30d` snoozes it; null or omitted hides it until the row''s underlying state changes (a bid is re-sent, an invoice balance moves). Re-dismissing an already-dismissed row refreshes it. 404 when the entity does not exist or the credential''s user cannot read it (the two are indistinguishable on purpose). Requires the read scope of the entity the row points at: invoices:read, bids:read, pay_apps:read, site_logs:read or projects:read.'
      security:
      - bearerAuth:
        - invoices:read
        - bids:read
        - pay_apps:read
        - site_logs:read
        - projects:read
      tags:
      - Briefing
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                itemKey:
                  type: string
                  minLength: 1
                  maxLength: 128
                until:
                  type:
                  - string
                  - 'null'
                  enum:
                  - 7d
                  - 30d
              required:
              - itemKey
              additionalProperties: false
      responses:
        '201':
          description: Dismissed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BriefingDismissal'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '400':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postDashboardBriefingDismissals
      x-rate-limit-cost: 5
  /dashboard/briefing/dismissals/{itemKey}:
    delete:
      summary: Undo a briefing dismissal
      description: 'Brings a dismissed or snoozed row back for the credential''s user. 404 when the row is not currently dismissed. Requires the read scope of the entity the row points at: invoices:read, bids:read, pay_apps:read, site_logs:read or projects:read.'
      security:
      - bearerAuth:
        - invoices:read
        - bids:read
        - pay_apps:read
        - site_logs:read
        - projects:read
      tags:
      - Briefing
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - schema:
          type: string
          description: The row's itemKey, URL-encoded.
        required: true
        description: The row's itemKey, URL-encoded.
        name: itemKey
        in: path
      responses:
        '200':
          description: Undone
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BriefingDismissal'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '400':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: deleteDashboardBriefingDismissalsByItemKey
      x-rate-limit-cost: 5
components:
  schemas:
    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
    BriefingDismissal:
      type: object
      properties:
        id:
          type: integer
        itemKey:
          type: string
          description: '`<category>:<entityType>:<entityId>`, as on the briefing row.'
        dismissedUntil:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
          description: Snooze end, or null until the row's state changes.
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
        deletedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
      required:
      - id
      - itemKey
      - dismissedUntil
      - createdAt
      - updatedAt
      - deletedAt
    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'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Idempotent retry key for mutating operations. The first request with a given key executes normally and BuildWorkPro caches the response. Replaying the same key with the same request body (method + path + JSON body, SHA-256 hashed) returns the cached response without re-executing the mutation. Replaying with a DIFFERENT body returns `409 idempotency_key_reused`. The cache TTL is 24 hours; after expiry the key is treated as a new operation. Keys are tenant-scoped. Recommended: a fresh UUID v4 per logical operation.'
      schema:
        type: string
        format: uuid
        maxLength: 255
  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: {}