Skill: JobTread via Pave Query API

# Skill: JobTread via Pave Query API

Summary

This skill lets you operate JobTread entirely through openclaw using the Pave-based API at `https://api.jobtread.com/pave`. Every request is a single POST with a `query` object that mirrors GraphQL-style expressions, and you decide which fields you want back. With the right grant key, you can create and manage accounts (customers/vendors), jobs, documents, tasks, locations, custom fields, documents, and even subscribe to webhooks for live updates.

Setup & Credentials

1. **Create a grant:** Login to https://app.jobtread.com/grants and create a new grant for automation. Copy the one-time `grantKey` (it begins with `grant_` and will only show once).

2. **Store the key locally:** Use a secure file such as `~/.config/jobtread/grant_key`. Example:

```bash

mkdir -p ~/.config/jobtread

echo "grant_xxx" > ~/.config/jobtread/grant_key

chmod 600 ~/.config/jobtread/grant_key

```

3. **Keep it fresh:** JobTread expires keys after 3 months of inactivity, so schedule a reminder (cron/heartbeat) to rotate or re-use the grant before expiration.

4. **Optional webhook secret:** If you plan to receive webhooks, note your endpoint URL and save the webhook ID in the same folder so you can disable or inspect it later.

Authentication

```json

{

"query": {

"$": { "grantKey": "grant_xxx" },

"currentGrant": { "id": {}, "user": { "name": {} } }

}

}

```

API Basics & Request Flow

```json

{

"query": {

"$": { "grantKey": "grant_xxx" },

"operation": {

"$": { ...inputs... },

"field": { ...fields... }

}

}

}

```

Common Patterns & Examples

1. Discover your organization ID

currentGrant:
  user:
    memberships:
      nodes:
        organization:
          id: {}
          name: {}

Use the returned `organization.id` in any following query.

2. Create customers/vendors

createAccount:
  $:
    name: "Test Customer"
    type: customer
    organizationId: "ORG_ID"
  createdAccount:
    id: {}
    name: {}
    type: {}

3. Read or update accounts

account:
  $:
    id: "ACCOUNT_ID"
  id: {}
  name: {}
  isTaxable: {}

updateAccount:
  $:
    id: "ACCOUNT_ID"
    isTaxable: false
  account:
    id: {}
    isTaxable: {}

4. Query accounts list with pagination, sorting, and filters

organization:
  $: {}
  id: {}
  accounts:
    $:
      size: 5
      page: "1"
      sortBy:
        - field: type
          order: desc
      where:
        and:
          - - type
            - =
            - customer
          - - name
            - =
            - "Sebas Clients"
    nextPage: {}
    nodes:
      id: {}
      name: {}
      type: {}

5. Use `where` with `or`, nested fields, or custom fields

organization:
  $: {}
  id: {}
  contacts:
    $:
      with:
        cf:
          _: customFieldValues
          $:
            where:
              - - customField
                - name
              - "VIP"
            values:
              $:
                field: value
      where:
        - - cf
          - values
        - =
        - "Yes"
    nodes:
      id: {}
      name: {}

6. Locations and nested filters

Create location and find others tied to the same account:

createLocation:
  $:
    accountId: "ACCOUNT_ID"
    name: Test Location
    address: "123 Main St"
  createdLocation:
    id: {}
    name: {}

organization:
  $: {}
  id: {}
  locations:
    $:
      where:
        - - account
          - name
        - Test Name
    nodes:
      id: {}
      name: {}
      account:
        id: {}
        name: {}

7. Documents, jobs, and aggregates

job:
  $:
    id: "JOB_ID"
  documents:
    $:
      where:
        - - type
          - in
          - - customerInvoice
            - customerOrder
      group:
        by:
          - type
          - status
        aggs:
          amountPaid:
            sum: amountPaid
          priceWithTax:
            sum: priceWithTax
    withValues: {}

pdfToken:
  _: signQuery
  $:
    query:
      pdf:
        $:
          id: "DOCUMENT_ID"

8. Custom fields

account:
  $:
    id: "ACCOUNT_ID"
  customFieldValues:
    $:
      size: 25
    nodes:
      id: {}
      value: {}
      customField:
        id: {}

updateAccount:
  $:
    id: "ACCOUNT_ID"
    customFieldValues:
      "CUSTOM_FIELD_ID": "New value"
  account:
    id: {}

9. Webhooks

createWebhook:
  $:
    organizationId: "ORG_ID"
    url: "https://your-endpoint/hooks/jobtread"
    eventTypes:
      - jobCreated
      - documentUploaded
  createdWebhook:
    id: {}
    url: {}

Using This Skill with OpenClaw

Automation Ideas

1. **Nightly job summary:** Query each open job, sum approved customer orders, and store results in Obsidian (or send via WhatsApp).

2. **Webhook monitor:** Automatically spin up a webhook for file uploads and forward notifications to your Slack/WhatsApp via a small server.

3. **Batch account creation:** Feed a CSV of customers/vendors and run `createAccount` for each with the same grant key.

4. **Document check-ins:** Query documents with `status: pending` and send you a summary each morning.

Troubleshooting & Tips