JobTread Agent

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:

   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

Every POST to /pave must include the grant key under query.$.grantKey. Example payload:

  {
    "query": {
      "$": { "grantKey": "grant_xxx" },
      "currentGrant": { "id": {}, "user": { "name": {} } }
    }
  }
  

You can also set notify, timeZone, or viaUserId inside $ when you need to suppress notifications or scope results.

For signed queries (PDF tokens, pre-signed data), call pdfToken: { _: signQuery, $: { query: {...} } } and append the token to https://api.jobtread.com/t/.

API Basics & Request Flow

All requests go to POST https://api.jobtread.com/pave with Content-Type: application/json.

Structure:

  {
    "query": {
      "$": { "grantKey": "grant_xxx" },  
      "operation": {
        "$": { ...inputs... },
        "field": { ...fields... }
      }
    }
  }
  

Fields you request (id, name, etc.) determine what JobTread returns. Always include id when you plan to reference the object later.

_type in responses tells you the schema for that node.

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

Customer

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

Vendor (same as above but type: vendor).

3. Read or update accounts

Read account by supplying id and requesting fields:

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

Update and include customFieldValues if needed:

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

Find account by custom field name:

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

Get a job's documents grouped by type/status and sums:

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

Get document PDF token (append to https://api.jobtread.com/t/{{token}}):

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

8. Custom fields

Read a record's custom field values (limit 25 per request):

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

Update a custom field via customFieldValues map:

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

9. Webhooks

Use the JobTread UI to create a webhook (Webhooks page) and copy its ID.

Manage them via the API: list webhook(id: "ID") or deleteWebhook to cancel.

Example create query:

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

Using This Skill with OpenClaw

Use curl or your preferred HTTP client from OpenClaw's exec tool.

Build the JSON payload as shown (always include the grant key inside $).

You can also wrap the payload in shell variables or helper scripts for portability.

Save reusable queries in the skill file or separate scripts so Claude or you can call them by name ("run job summary", "create customer", etc.).

Document each automation in the JobTread vault so you can copy/paste from future sessions without digging through logs.

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

Rate limits: Grant keys have a throughput cap. If you hit rate limits, add time.sleep between requests or batch fewer objects.

Missing IDs: The API complains id field required when you forget to request id. Always include it when you plan to mutate the record later.

Grant expiration: If a request returns invalid key, rotate the grant and update ~/.config/jobtread/grant_key.

Webhooks: Keep a log of webhook IDs so you can disable or reconfigure them later.

Signed tokens: Use signQuery when you need temporary access to document PDFs without storing raw document IDs.