jobtread-api（jobtread 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:

   mkdir -p ~/.config/jobtread
   echo "grant_xxx" > ~/.config/jobtread/grant_key
   chmod 600 ~/.config/jobtread/grant_key

1. 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.
2. 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.