BayLineup Public API
A REST API over your shop's own data. Create and manage keys on API Keys.
Authentication
Send your key as a bearer token on every request. Keys are org-scoped, individually revocable, and each carries its own set of granted scopes.
curl https://YOUR-SHOP.baylineup.com/api/v1/me \ -H "Authorization: Bearer bl_live_xxxxxxxxxxxxxxxx"
Base URL
https://YOUR-SHOP.baylineup.com/api/v1
Scopes
Every endpoint below except /me requires a specific scope. A key without the required scope gets a 403 forbidden. Grant only the scopes an integration actually needs when creating a key.
Rate limits
Endpoints are grouped into three classes with independent per-minute sustained-rate limits per key:
- Class A · 120 req/min · lightweight single-record reads
- Class B · 60 req/min · collection/search reads
- Class C · 30 req/min · mutations
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
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.
Correlation IDs
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. |
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. |
| GET | /api/v1/customers | customers:read | B | Customers. Query: search |
| GET | /api/v1/vehicles | vehicles:read | B | Vehicles. Query: customerId |
| GET | /api/v1/jobs | jobs:read | B | Jobs/work orders. Query: status |
| GET | /api/v1/employees | employees:read | B | Employees. |
| GET | /api/v1/job-types | job_types:read | A | Job type catalog, needed to build a valid appointment line item. |
| 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/parts | parts:read | B | Parts catalog. Query: search, category |
| 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. |
| 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.