workwing-io Parts Catalogue API

openapi: 3.2.0
info:
  title: WorkWing Parts Catalogue API
  description: 'REST API for WorkWing field service management. Designed as an **integration point** for CRM, ERP, and dispatch systems. Admin configuration (webhooks, roles, job types, integrations) is managed via the web dashboard. Every resource is documented under its own section in the sidebar. ## Authentication


    Send your API key as a bearer token on every request:


    ```

    Authorization: Bearer ww_sk_live_. ```


    ### Scopes


    An API key carries a list of `action:resource` scopes. Every operation publishes the ones it requires as `x-required-scopes`, an array on the operation object; a key must hold all of them, or the wildcard scope `*`, and one that does not is refused with `403 E_AP_1102`. The two operations that declare `security: []` need no key at all: the health check, and the integration callback, which authenticates with the signed token in its own path. ## Querying collections


    List endpoints (jobs, customers, resources, and so on) accept query parameters for filtering, sorting, field selection, and pagination:


    - `?status=eq.T_PENDING` - filter by exact match

    - `?priority=in.(T_HIGH,T_URGENT)` - match any of several values

    - `?created_at=gte.2024-01-01` - range comparisons (`gt`, `gte`, `lt`, `lte`)

    - `?select=id,status,customer:customers(name)` - choose columns and embed related records. Only the resources listed here, the assignments and users they reference, and the foreign keys between them can be embedded; anything else is refused with `E_AP_6003`

    - `?order=created_at.desc` - sort (append `.asc` / `.desc`)

    - `?limit=25&offset=50` - paginate (maximum 1000 rows per page)


    ### Columns not available over the API


    Some columns are never returned: `tenant_id` on every resource (a key is bound to one tenant), `internal_notes` on jobs (staff-only; it can be set with `PATCH`, and a job''s note timeline is at `GET /v1/jobs/{jobId}/notes`), and the raw PostGIS geography columns `customers.location`, `locations.location` and `resources.current_location`. Read a position from `latitude`/`longitude` on locations and `current_latitude`/`current_longitude` on resources instead. `select=*`, at the top level or inside an embed, returns every other column. Naming one of these columns in `select`, a filter or `order` is refused with `E_AP_6003`. To read, update or delete one record, address it by id: `GET`, `PATCH` or `DELETE /v1/jobs/{jobId}` (likewise customers, resources and locations). `PATCH` and `DELETE` on a collection change every row matching its filters, e.g. `PATCH /v1/jobs?status=eq.T_PENDING`; they are listed under Workflows. ### Counting and paging


    Send `Prefer: count=exact` on a list request to get the total row count back in the `Content-Range` response header (`0-24/312`). `count=planned` and `count=estimated` are cheaper approximations for large tables. ## Idempotency


    **Guarantee.** Within 24 hours, a write sent with a given `Idempotency-Key` is applied at most once. If you did not receive a response, retrying with the same key and the same request is always safe. **Core rule.** A key is consumed only when the write is actually applied. The key and the write commit in the same database transaction, so they succeed or fail together. Every write request (`POST`, `PATCH`, `PUT`, `DELETE`) must send an `Idempotency-Key` header. | Situation | Response | Write applied?'
  version: 1.0.0
servers:
- url: https://api.workwing.io
  description: Production
security:
- bearerAuth: []
tags:
- name: Parts Catalogue
  description: Parts catalogue and brand-specific pricing (read-only)
paths:
  /v1/parts_catalog:
    get:
      operationId: listCatalogueParts
      summary: List catalogue parts
      tags:
      - Parts Catalogue
      description: 'List parts in your organisation''s catalogue (read-only).


        - `?is_active=is.true` - Only active parts

        - `?sku=eq.WIDGET-01` - Look up by SKU

        - `?select=id,name,sku,default_unit_cost` - Field selection'
      parameters:
      - schema:
          type: string
        in: query
        name: select
        required: false
        description: 'Comma-separated columns to return. Supports embedded resources: `*,customer:customers(name,email)`'
      - schema:
          type: string
        in: query
        name: order
        required: false
        description: Sort order, e.g. `created_at.desc` or `name.asc`
      - schema:
          type: integer
        in: query
        name: limit
        required: false
        description: Maximum number of rows to return (max 1000)
      - schema:
          type: integer
        in: query
        name: offset
        required: false
        description: Number of rows to skip for pagination
      security:
      - bearerAuth: []
      x-required-scopes:
      - read:parts_catalog
      x-postgrest-passthrough: true
      responses:
        '200':
          description: Array of catalogue parts
          content:
            application/json:
              schema:
                description: Array of catalogue parts
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                          description: Part name
                        description:
                          type:
                          - string
                          - 'null'
                        sku:
                          type:
                          - string
                          - 'null'
                          description: Stock keeping unit
                        default_unit_cost:
                          type:
                          - number
                          - 'null'
                          description: Default unit cost, to two decimal places
                        unit_label:
                          type: string
                          description: Unit of measure, e.g. `each`, `metre`, `hour`
                        is_active:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                        created_by_user_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
  /v1/parts_catalog_brand_pricing:
    get:
      operationId: listPartBrandPricing
      summary: List brand-specific part pricing
      tags:
      - Parts Catalogue
      description: 'List brand-specific pricing overrides for catalogue parts (read-only).


        - `?brand_id=eq.{uuid}` - Pricing for one brand

        - `?part_id=eq.{uuid}` - Pricing for one part

        - `?select=part_id,brand_id,unit_cost,is_available` - Field selection'
      parameters:
      - schema:
          type: string
        in: query
        name: select
        required: false
        description: 'Comma-separated columns to return. Supports embedded resources: `*,customer:customers(name,email)`'
      - schema:
          type: string
        in: query
        name: order
        required: false
        description: Sort order, e.g. `created_at.desc` or `name.asc`
      - schema:
          type: integer
        in: query
        name: limit
        required: false
        description: Maximum number of rows to return (max 1000)
      - schema:
          type: integer
        in: query
        name: offset
        required: false
        description: Number of rows to skip for pagination
      security:
      - bearerAuth: []
      x-required-scopes:
      - read:parts_catalog
      x-postgrest-passthrough: true
      responses:
        '200':
          description: Array of brand pricing rows
          content:
            application/json:
              schema:
                description: Array of brand pricing rows
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        part_id:
                          type: string
                          format: uuid
                          description: Reference to the catalogue part
                        brand_id:
                          type: string
                          format: uuid
                        unit_cost:
                          type:
                          - number
                          - 'null'
                          description: Brand-specific unit cost, to two decimal places; overrides the default
                        is_available:
                          type: boolean
                          description: Whether the part is available for this brand
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Use your WorkWing API key (format: `ww_sk_live_<tokenId>.<secret>`). The scopes an operation requires are published on it as `x-required-scopes`.'