Public API
A REST API over your own shop's data.
Every endpoint below is scoped to a single BayLineup shop, authenticated with a key you create and revoke yourself. This page documents what exists today — if something isn't listed, it isn't built yet.
Getting access
Sign in to your BayLineup account and create a key on the API Keys page — no separate application process. Keys are org-scoped, individually revocable, and each carries its own set of granted scopes.
Authentication
Send your key as a bearer token on every request.
curl https://app.baylineup.com/api/v1/me \ -H "Authorization: Bearer blp_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Base URL: https://app.baylineup.com/api/v1
Scopes & rate limits
Every endpoint below except /me requires a specific scope — a key without it gets a 403 forbidden. Grant only the scopes an integration actually needs when creating a key. Endpoints are grouped into three classes with independent per-minute limits per key:
| Class | Limit |
|---|---|
| Class A | 120 req/min (burst 60/10s) |
| Class B | 60 req/min (burst 30/10s) |
| Class C | 30 req/min (burst 15/10s) |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. A key may also carry an optional daily quota (X-DailyQuota-* headers when set) and a concurrency limit. Exceeding any of these returns 429 with a Retry-After header. Check current usage on your key's API Keys dashboard, or call GET /api/v1/me (which never itself counts against your daily quota).
Idempotency & correlation IDs
Mutation endpoints marked idempotent below accept an Idempotency-Key header. Retrying the same key with the same body returns the original result rather than creating a duplicate; retrying with a different body returns 409 conflict.
Every response includes an X-Correlation-Id header (also echoed in error bodies) — include it when reporting an issue.
Errors
Errors always come back as a consistent JSON envelope.
{
"error": {
"code": "forbidden",
"message": "This API key does not have the \"jobs:read\" scope.",
"correlationId": "..."
}
}| Code | HTTP status | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid Authorization: Bearer <api key> header. |
forbidden | 403 | The key is valid but lacks the scope this endpoint requires. |
not_found | 404 | The requested resource does not exist. |
validation_error | 400 | Request body/query failed validation; see fieldErrors. |
rate_limit | 429 | Per-minute rate limit exceeded for this key's endpoint class. Retry-After header set. |
burst_limit | 429 | Too many requests inside a short 10-second window for this key's endpoint class. Retry-After header set. |
daily_quota | 429 | This key's configured daily quota is exhausted. Retry-After header set. |
concurrency_limit | 429 | Too many in-flight requests for this key at once. |
conflict | 409 | The request conflicts with existing state (e.g. duplicate Idempotency-Key with a different body). |
service_unavailable | 503 | The public API is temporarily disabled (kill switch) or the database is unavailable. |
internal_error | 500 | Unexpected server-side failure. Include the correlationId when reporting it. |
Endpoints
| Method | Path | Scope | Class | Summary |
|---|---|---|---|---|
| GET | /api/v1/me | none | A | Identity of the calling API key: name, key prefix, granted scopes, and rate-limit/quota policy. Does not itself consume daily quota. |
| GET | /api/v1/locations | locations:read | B | Shop locations, including business hours and any upcoming special closures. |
| GET | /api/v1/bays | bays:read | A | Bay/lift roster and real-time availability (no active or held job currently occupying it). Query: active, locationId |
| GET | /api/v1/equipment | equipment:read | A | Tool/equipment roster and real-time availability (active, not out-of-service, no current reservation). Query: active, category, locationId |
| GET | /api/v1/service-vehicles | service_vehicles:read | B | Mobile-service fleet roster, dispatch state, and truck-readiness signals. Query: active |
| GET | /api/v1/customers | customers:read | B | Customers. |
| GET | /api/v1/vehicles | vehicles:read | B | Vehicles. Query: customerId |
| GET | /api/v1/jobs | jobs:read | B | Jobs/work orders. Query: state |
| GET | /api/v1/jobs/{id}/assignments | assignments:read | A | Current and historical employee membership for a job assignment group. |
| GET | /api/v1/jobs/{id}/line-items | job_line_items:read | A | Service/job line items with quantity and staff-entered price. |
| GET | /api/v1/jobs/{id}/promises | job_promises:read | A | Customer promise/ETA ledger for a job, including status and resolution. |
| GET | /api/v1/jobs/{id}/completion | job_completion:read | A | QC, teardown/reassembly, payment/keys, and pickup completion state for a job. |
| GET | /api/v1/employees | employees:read | B | Employees. Query: active |
| GET | /api/v1/employees/{id}/credentials | employee_qualifications:read | A | Employee certification references with sensitive credential numbers and verification notes withheld. |
| GET | /api/v1/employees/{id}/job-permissions | employee_qualifications:read | A | Lead/Assist/No job-type permission matrix for an employee. |
| GET | /api/v1/job-types | job_types:read | A | Job type catalog, needed to build a valid appointment line item. Query: zone |
| GET | /api/v1/appointments | appointments:read | B | Appointments/queue. Query: status |
| POST | /api/v1/appointments | appointments:write | C | Create an appointment, or a walk-in when requestedAt is omitted (created directly checked_in). · idempotent |
| GET | /api/v1/inspection-findings | findings:read | B | DVI inspection findings. Query: status, vehicleId |
| GET | /api/v1/measurements | measurements:read | B | BayGauge measurements with vehicle/job filtering. Query: vehicleId, jobId, limit, cursor |
| POST | /api/v1/measurements | measurements:write | C | Create a normalized BayGauge measurement; source is forced to api. · idempotent |
| GET | /api/v1/form-templates | form_templates:read | A | Current BayForms templates and their field schemas. |
| GET | /api/v1/form-submissions | form_submissions:read | B | BayForms submissions and confidence/review state. Query: vehicleId, jobId, formTemplateId, limit, cursor |
| POST | /api/v1/form-submissions | form_submissions:write | C | Create an API-origin BayForms submission. · idempotent |
| GET | /api/v1/messages | messages:read | B | Outbound message metadata and delivery state without phone numbers or message bodies. Query: customerId, jobId, status, limit, cursor |
| POST | /api/v1/messages | messages:write | C | Request an operational send using a published script through the Messaging Safety Envelope. · idempotent |
| GET | /api/v1/message-scripts | message_scripts:read | A | Message script/template references without version body content. Query: includeArchived |
| GET | /api/v1/parts | parts:read | B | Parts catalog. Query: search, category |
| GET | /api/v1/inventory/items | inventory:read | B | On-hand inventory per (part, location): quantity on hand, quantity reserved, and min/max levels. Query: partId, locationId |
| GET | /api/v1/inventory/locations | inventory:read | A | Inventory location reference list (shop/warehouse/room/bin/truck/staging/takeoff). Query: active |
| POST | /api/v1/inventory/reservations | inventory:write | C | Reserve a quantity of a part at a location, e.g. holding stock for a job. · idempotent |
| POST | /api/v1/inventory/reservations/release | inventory:write | C | Release a quantity previously reserved at a (part, location) without consuming it. · idempotent |
| GET | /api/v1/purchase-orders | purchase_orders:read | B | Purchase orders. Query: status, supplierId |
| GET | /api/v1/purchase-orders/{id} | purchase_orders:read | A | A single purchase order and its lines, including unit cost and core charge. |
| GET | /api/v1/purchase-orders/{id}/receipts | purchase_orders:read | A | Every receiving event recorded against a purchase order's lines, including returns. |
| GET | /api/v1/suppliers/{id}/performance | analytics:read | A | Supplier on-time, timing percentile, fill-rate, and receipt-condition metrics. |
| GET | /api/v1/integrations/connections | integrations:read | B | This org's configured integration connections and their sync status. Secret-shaped config values are redacted. |
| GET | /api/v1/integrations/connections/{connectorKey}/mappings | integrations:read | B | External-id to internal-id mapping crosswalk for one connection. Query: entityType |
| GET | /api/v1/integrations/connections/{connectorKey}/sync-events | integrations:read | A | Recent sync run history for one connection: status, timing, records processed, errors. Query: limit (max 100) |
| GET | /api/v1/analytics/messaging-health | analytics:read | B | Aggregate messaging health: counts by status, total segments/estimated cost. Query: sinceHours (max 720) |
| GET | /api/v1/partner-opportunities | partner_intake:read | B | Partner referral/opportunity intake records. |
| POST | /api/v1/partner-opportunities | partner_intake:write | C | Submit a partner referral/opportunity. · idempotent |
| GET | /api/v1/reviews | reviews:read | B | Customer reviews. Query: source, escalationStatus, responseStatus |
| POST | /api/v1/reviews/{id}/respond | reviews:respond | C | Post a shop response to a review. |
| GET | /api/v1/review-scripts | review_scripts:read | B | Review-request message scripts. |
| POST | /api/v1/review-scripts | review_scripts:write | C | Create/update a review-request message script. |
| GET | /api/v1/reputation | reputation:read | A | Aggregate review/reputation score. |
This surface expands over time as new scopes and endpoint families ship. If your integration needs data or a scope that isn't listed here yet, contact support.