Documentation
Jobs
jobs.panels
REST
ShippingPOST /api/v1/jobs/panelsMCP tool
Livejobs.panelsExposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Jobs domain.
Operating contract
THE REAL PROGRESS ON AN INSTALL, panel by panel: what is planned, what is done, what was skipped and why, and which panel somebody has a timer running on right now.
A JOB'S STAGE SAYS 'IN PROGRESS' FOR DAYS; THIS SAYS HOW FAR IN. done_count against panel_count is the answer to 'how much longer', and it is the only honest one — a job on its last panel and a job on its first read identically everywhere else.
photos_outstanding IS A BLOCKER, NOT A CHORE. Those panels cannot be finished until somebody photographs them, so a job that looks nearly done with photos outstanding is not nearly done.
TWO TIME FIGURES, AND THEY ARE NOT THE SAME NUMBER. banked_labour_seconds is what the panel COST — closed segments across every worker. elapsed_seconds is what it TOOK — last close minus first start, interruptions and all. Reporting elapsed as labour overstates the cost of every job that was put down and picked back up.
running_since MEANS SOMEBODY IS ON IT AT THIS MOMENT. Say so — it changes what 'when will it be ready' means.
sequence_actual is the order panels were really worked, which often differs from sequence_planned. Neither is wrong; the difference is how the bay actually ran.
AN EMPTY LIST IS NOT AN UNSTARTED JOB. A job with no panel template, and any job at all on a database without the panels migration, has no panels — the work is real either way, and the honest answer is that this job is not tracked panel by panel.
This is one job's panels, entirely returned, so nothing is truncated.
Who may call it
- Permission
jobs.accessThe caller must hold Jobs at the ACT level. A read-only dashboard grant on the same section is refused.- Plan
- Every planNo plan gate. Available on every Service VIN plan.
- Retries
naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.- Rate class
readCounted against the read budget — the widest of the four.
Input
| Field | Type | Description |
|---|---|---|
| job_idrequired | stringuuid | The job to inspect, as returned by jobs.list or calendar.day. |
Output
| Field | Type | Description |
|---|---|---|
| job_id | string | — |
| tracked | boolean | — |
| totals | object | — |
| totals.panel_count | number | — |
| totals.done_count | number | — |
| totals.skipped_count | number | — |
| totals.banked_labour_seconds | number | — |
| totals.expected_minutes | number | null | — |
| totals.photos_outstanding | number | — |
| running_panel_id | string | null | — |
| panels | object[] | — |
| panels[].id | string | — |
| panels[].panel_code | string | — |
| panels[].label | string | — |
| panels[].discipline | string | null | — |
| panels[].status | string | — |
| panels[].assignee_id | string | null | — |
| panels[].sequence_planned | number | — |
| panels[].sequence_actual | number | null | — |
| panels[].started_at | string | null | — |
| panels[].ended_at | string | null | — |
| panels[].banked_labour_seconds | number | — |
| panels[].elapsed_seconds | number | — |
| panels[].running_since | string | null | — |
| panels[].segment_count | number | — |
| panels[].required_photos | number | — |
| panels[].photo_count | number | — |
| panels[].expected_minutes | number | null | — |
| panels[].skip_reason | string | null | — |
| panels[].rework_reason | string | null | — |
Examples
Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.
export SERVICEVIN_API_KEY=svk_live_…
curl -X POST https://www.servicevin.com/api/v1/jobs/panels \
-H "Authorization: Bearer $SERVICEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"job_id":"9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"}'const res = await fetch("https://www.servicevin.com/api/v1/jobs/panels", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"job_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
}),
});
// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;import os, requests
res = requests.post(
"https://www.servicevin.com/api/v1/jobs/panels",
headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
json={
"job_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
},
timeout=30,
)
payload = res.json()
if not res.ok:
raise RuntimeError(payload["error"]["code"])
data = payload["data"]{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "jobs.panels",
"arguments": {
"job_id": "9b2f1c6e-4a77-4d2b-9f31-0f1c9a8e5d20"
}
}
}Refusals
The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.
| Status | Code | When |
|---|---|---|
| 404 | not_found | The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both. |
| 403 | forbidden | This login does not hold jobs.access. |
| 422 | validation_error | An argument was wrong. The message names the field. |
| 429 | rate_limited | Too many read calls. Back off and retry. |
| 500 | internal_error | Something failed on our side. Nothing was changed. |