BuildWorkPro Jobs API

openapi: 3.2.0
info:
  title: BuildWorkPro Jobs 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: Jobs
  description: Asynchronous work — CSV imports and exports — with progress and result artifacts.
paths:
  /jobs:
    get:
      summary: List async jobs
      description: Returns a cursor-paginated list of async jobs in the authenticated tenant. Company admins, managers and tenant API keys see every job; other roles see only the jobs they started.
      security:
      - bearerAuth:
        - jobs:read
      tags:
      - Jobs
      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: string
        required: false
        name: type
        in: query
      - schema:
          type: string
        required: false
        name: status
        in: query
      - schema:
          type: string
        required: false
        name: resourceType
        in: query
      responses:
        '200':
          description: Jobs page
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '403':
          description: Scope insufficient
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getJobs
      x-rate-limit-cost: 1
  /jobs/{id}:
    get:
      summary: Get job by id
      description: Returns a single async job (status, progress, result, error message).
      security:
      - bearerAuth:
        - jobs:read
      tags:
      - Jobs
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Job
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Job'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getJobsById
      x-rate-limit-cost: 1
    delete:
      summary: Soft-delete job
      description: Soft-deletes the job row. Stored artifacts will be reaped on TTL expiry.
      security:
      - bearerAuth:
        - jobs:write
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '204':
          description: Deleted
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: deleteJobsById
      x-rate-limit-cost: 5
  /jobs/{id}/download:
    get:
      summary: Download job result artifact
      description: Redirects (302) to a short-lived pre-signed URL for the result artifact (succeeded/partial jobs only).
      security:
      - bearerAuth:
        - jobs:read
      tags:
      - Jobs
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '302':
          description: Redirect to signed download URL
        '404':
          description: Not found or no artifact
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Job not in a downloadable state
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getJobsByIdDownload
      x-rate-limit-cost: 1
  /jobs/{id}/errors:
    get:
      summary: Download job errors artifact
      description: Redirects (302) to a short-lived pre-signed URL for the row-level errors CSV (partial/failed jobs only).
      security:
      - bearerAuth:
        - jobs:read
      tags:
      - Jobs
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '302':
          description: Redirect to signed errors URL
        '404':
          description: Not found or no errors artifact
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getJobsByIdErrors
      x-rate-limit-cost: 1
  /jobs/{id}/cancel:
    post:
      summary: Cancel job
      description: Cancels a queued or running job. Already-terminal jobs return 409.
      security:
      - bearerAuth:
        - jobs:write
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - schema:
          type: string
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Job'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Job already terminal
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postJobsByIdCancel
      x-rate-limit-cost: 5
  /jobs/uploads:
    post:
      summary: Get signed URL for CSV upload
      description: Returns a short-lived signed PUT URL. Caller uploads the CSV bytes directly to that URL, then passes the returned sourcePath to POST /{module}/imports.
      security:
      - bearerAuth:
        - jobs:write
      tags:
      - Jobs
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contentType:
                  type: string
                  enum:
                  - text/csv
                  default: text/csv
      responses:
        '200':
          description: Signed URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uploadUrl:
                        type: string
                        format: uri
                      sourcePath:
                        type: string
                      expiresInSeconds:
                        type: integer
                    required:
                    - uploadUrl
                    - sourcePath
                    - expiresInSeconds
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postJobsUploads
      x-rate-limit-cost: 5
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
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
    Job:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        resourceType:
          type: string
        status:
          type: string
        progress:
          $ref: '#/components/schemas/JobProgress'
        params: {}
        result: {}
        errorMessage:
          type:
          - string
          - 'null'
        createdAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
        startedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
        completedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
        expiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
      required:
      - id
      - type
      - resourceType
      - status
      - createdAt
      - expiresAt
    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'
    JobProgress:
      type: object
      properties:
        processed:
          type: integer
        total:
          type: integer
        errorsCount:
          type: integer
      required:
      - processed
      - total
      - errorsCount
  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: {}