BuildWorkPro Search API

openapi: 3.2.0
info:
  title: BuildWorkPro Search 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: Search
  description: One ranked search across records, limited to the types and rows the credential may read.
paths:
  /search:
    get:
      summary: Search across records
      description: Full-text and fuzzy search across projects, contacts, site logs, documents, bids, leads, invoices, pay apps and change orders, blended into one relevance-ranked list. Requires `projects:read`; each other type is included only when the credential also holds that type's read scope (e.g. `bids:read`), and results are limited to records the authorizing user may open.
      security:
      - bearerAuth:
        - projects:read
      tags:
      - Search
      parameters:
      - schema:
          type: string
          minLength: 2
          description: Search text, at least 2 characters. `*` lists recent records.
        required: true
        description: Search text, at least 2 characters. `*` lists recent records.
        name: q
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 50
          description: Maximum results (default 20, max 50).
        required: false
        description: Maximum results (default 20, max 50).
        name: limit
        in: query
      responses:
        '200':
          description: Matches, best first
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
                  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'
      operationId: getSearch
      x-rate-limit-cost: 1
components:
  schemas:
    SearchResult:
      type: object
      properties:
        type:
          type: string
          enum:
          - project
          - contact
          - site_log
          - document
          - bid
          - lead
          - invoice
          - pay_app
          - change_order
          description: Entity type of the match.
        id:
          type: integer
          description: Id of the matched record; fetch it from that type's own endpoint.
        title:
          type: string
          description: Display title (name, number or filename).
        subtitle:
          type:
          - string
          - 'null'
          description: Short secondary text — email, project number, or the start of the matched body. Null when there is none.
        projectId:
          type:
          - integer
          - 'null'
          description: Parent project for change orders, pay apps, site logs and invoices; null when the record has none. Absent for other types.
      required:
      - type
      - id
      - title
      - subtitle
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Server-generated request identifier
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
    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
    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
  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: {}