# Send JobTread Agent to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "jobtread-api",
    "name": "JobTread Agent",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/Brokenwatch24/jobtread-api",
    "canonicalUrl": "https://clawhub.ai/Brokenwatch24/jobtread-api",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/jobtread-api",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=jobtread-api",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "jobtread-api",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-04T14:58:28.608Z",
      "expiresAt": "2026-05-11T14:58:28.608Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=jobtread-api",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=jobtread-api",
        "contentDisposition": "attachment; filename=\"jobtread-api-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "jobtread-api"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/jobtread-api"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/jobtread-api",
    "downloadUrl": "https://openagent3.xyz/downloads/jobtread-api",
    "agentUrl": "https://openagent3.xyz/skills/jobtread-api/agent",
    "manifestUrl": "https://openagent3.xyz/skills/jobtread-api/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/jobtread-api/agent.md"
  }
}
```
## Documentation

### 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

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).
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


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

### 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

Nightly job summary: Query each open job, sum approved customer orders, and store results in Obsidian (or send via WhatsApp).
Webhook monitor: Automatically spin up a webhook for file uploads and forward notifications to your Slack/WhatsApp via a small server.
Batch account creation: Feed a CSV of customers/vendors and run createAccount for each with the same grant key.
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.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: Brokenwatch24
- Version: 1.0.0
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-04T14:58:28.608Z
- Expires at: 2026-05-11T14:58:28.608Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/jobtread-api)
- [Send to Agent page](https://openagent3.xyz/skills/jobtread-api/agent)
- [JSON manifest](https://openagent3.xyz/skills/jobtread-api/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/jobtread-api/agent.md)
- [Download page](https://openagent3.xyz/downloads/jobtread-api)