Scheduler API & AI access

Connect your own tools, scripts, and AI assistants to BayWise Scheduler. The API lets external systems — your DMS, ERP, or custom workflows — create and track jobs, manage workshop resources, and read operations back, and lets AI assistants answer questions about your workshop.

What the Scheduler API is — and when to use it

BayWise Scheduler runs the operational side of a workshop: the vehicles in for work, the tasks on each one, and the people and bays doing the work. The API exposes that so other systems can drive it or read from it.

The real problem: one vehicle’s work, scattered across systems and people

Just like the money, a single repair’s work is spread across systems that each hold only a fragment — and the one thing nobody has is a live picture of where the car actually is right now:

The DMS knows it was booked; HR knows who’s in; parts knows what’s pending — but no single system can answer “where is this car right now, who’s working on it, and will it be ready by 5?” That live operational truth is the fragment that usually lives on a whiteboard.

How the API turns the fragments into one live picture

You sync the static fragments once, then drive the live ones through one job (the vehicle’s visit):

1. Sync resources — push technicians (with skills), bays, and the service catalog from your systems, idempotent on your externalKey so re-syncing never duplicates.
2. Create the job — for RO-4821 / VIN MA3…7K, with the promise time.
3. Add steps — the tasks: Diagnose brakes → Replace pads → Oil change → QC — each one assignable, sequential or parallel.
4. Assign and schedule — put Ravi + Bay 2 on the brake steps; whoever’s free on the oil change.
5. Track — move each step pending → in_progress → completed; the job’s derived status always reflects the active step, so the board is live.
6. Deliver — mark the job delivered when the car leaves.
7. Across locations — a group drives and reads every site through the same API, scoped by location.

What that gives you back

Because every fragment now hangs off one job, reading jobs and their steps answers the questions the underlying systems can’t — no separate reporting system required:

• A live job board — where every vehicle is, who’s on it, and what’s next.
• On-time tracking — promise time vs actual progress, so you see slippage early.
• Resource picture — which technicians and bays are busy, plus attendance for who’s actually in.
• Day-close — the end-of-day record per location.

Use the API to:

• Sync resources from your DMS/ERP — keep technicians, bays, and your service catalog in step, without anyone re-typing them.
• Automate jobs — create jobs and their steps from another system and track them to delivery.
• Build a live board / dashboards — read jobs, steps, and attendance for real-time operational views.
• Record attendance and day-close from third-party time-tracking or end-of-day tooling.
• Ask an AI assistant (Claude, Cursor, and others) about your workshop — read-only.

If you only need one sentence: use this API to pull the scattered facts about each vehicle’s work — booking, people, bays, parts, progress — into one live picture: where every car is, who’s on it, and whether it’ll be ready on time, per location or across the group.

Core concepts

(For the business background, see the in-product concept guides on The Job, The Technician, and The Bay.)

Technicians, bays, and catalog items are the ones you’ll typically sync from your own system — see the sync pattern below.

Getting a key

1. In BayWise, open Settings → Developer.
2. Choose the permissions the key should have (you can only grant what your own role allows).
3. Optionally scope the key to a single location and set an expiry.
4. Click Create API key. The full key is shown once — copy and store it safely.

Who can do this: Account Owners and Org Admins (anyone with developer access). On the free plan, API access is an upgrade.

Using the API

Send your key as a bearer token (Authorization: Bearer …) to the BayWise API base URL. The full request/response details, every field, and a “try it” console are in the Scheduler API reference ; a ready-to-import Postman collection is linked from the Developer tab.

A few rules worth knowing up front:

• Retries are safe. Send an idempotency key when creating — repeating the same key never double-records.
• No silent overwrites. Updates require the record’s current last-updated time, so two systems can’t clobber each other’s changes (you’ll get a conflict if you’re out of date).
• Lists are paginated. Job lists return a cursor; pass it back to get the next page.
• Times are workshop-local. Attendance and day-close use the location’s local time, not your server’s.
• Every response has a request id you can quote to support.

The sync pattern (DMS → BayWise)

For technicians, bays, and catalog items, send a create with your own externalKey on every sync. The endpoint is idempotent on that key: the first call creates the record, and later calls with the same key update the existing one instead of duplicating. You don’t need to track BayWise’s IDs — just keep sending your own.

Example — upsert a technician:

POST /v1/scheduler/techs
Authorization: Bearer bw_live_…
Idempotency-Key: dms-tech-E-12
Content-Type: application/json

{
  "name": "Ravi Kumar",
  "externalKey": "dms-tech-E-12",
  "skills": ["brakes", "suspension", "oil_change"],
  "locationId": "loc-uuid"
}

First call → 201 Created (new record). Every subsequent call with the same externalKey → 200 with the same record. Nothing duplicates.

A typical flow

1. Sync resources — push technicians, bays, and catalog from your DMS (once on startup, then incrementally).

2. Create a job:

POST /v1/scheduler/jobs
Idempotency-Key: dms-ro-4821

{ "locationId": "loc-uuid", "vehiclePlate": "ABC 123", "vehicleMake": "Toyota",
  "vehicleModel": "Camry", "promiseTime": "2026-06-28T17:00:00+04:00",
  "priority": "normal", "source": "phone" }

3. Add steps:

POST /v1/scheduler/jobs/{jobId}/steps

{ "label": "Diagnose brakes", "phase": 1, "schedulingMode": "sequential",
  "estimatedDuration": 1800 }

4. Assign and track — PATCH /v1/scheduler/jobs/{jobId}/steps/{stepId} to set techIds, bayId, and update status (pending → in_progress → completed). Each update requires the step’s current updatedAt for concurrency safety.

5. Deliver:

POST /v1/scheduler/jobs/{jobId}/deliver

Idempotent — an already-delivered job returns its current state unchanged.

6. React in real time — instead of polling, subscribe to webhooks (job/step events) — see below.

Workshop settings

Read the workshop configuration (operating hours, break times, bay buffer) for a location:

GET /v1/scheduler/workshop
Authorization: Bearer bw_live_…

A location-scoped key returns a single object. An org-scoped key returns { "data": [...] } with one entry per location. Workshop settings are read-only via the API — edit them in Settings → Workshop in the app.

Webhooks

Subscribe to job and step events so your systems react in real time instead of polling — see Webhooks for the full event list, payload shape, and signature verification.

Current events: job.created, job.updated, job.delivered, step.created, step.updated, step.completed.

Connecting an AI assistant (MCP)

From Settings → Developer → Connect via MCP, generate a token and copy the config into your AI client (for example, Claude Desktop → Settings → Developer → Edit Config). The assistant then acts as you and can only do what your role permits — in this version, AI access is read-only (it can answer questions about your workshop, not change it).

What the AI can read via MCP:

The AI cannot create jobs, update steps, or clock technicians in or out — write actions require a human using the app or the REST API.

Need help?

Quote the request id from any response when contacting support. Keys can be revoked any time from the Developer tab — a revoked key stops working immediately.