Skip to main content

​
V1 API Overview

The V1 API provides a unified, domain-based interface for all Switchyard operations. It consolidates the previous /admin/* and /scanner/* routes into a single, consistent API structure.

​
Base URL

Production: https://api.switchyard.run/v1
Development: https://api-dev.switchyard.run/v1

​
Key Features

Dual ID Support

All endpoints accept both UUIDs and 18-digit taxonomy IDs as identifiers.

Domain-Based Structure

Endpoints are organized by business domain (products, orders, sweeps, etc.).

Consistent Authentication

All routes require Bearer token authentication via Supabase Auth.

Zod Validation

Request/response validation using Zod schemas for type safety.

​
Authentication

All V1 API endpoints require authentication using a Bearer token: 
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.switchyard.run/v1/products
Get your access token by authenticating with Supabase Auth. See the Authentication Guide for details.

​
API Domains

The V1 API is organized into the following domains. All endpoint documentation is auto-generated from our OpenAPI specification.

​
Core Operations

DomainBase PathDescription
Products/v1/productsProduct catalog management
Scraped Products/v1/scraped-productsScraped product pipeline
Availability/v1/availabilityProduct availability scoring
Orders/v1/ordersOrder management and fulfillment
Sweeps/v1/sweepsRetail store sweep operations
RFC Picks/v1/rfc-picksWarehouse pick list management
Inventory/v1/inventoryInventory and stock management
Receiving/v1/receivingInbound receiving workflow

​
Organization

DomainBase PathDescription
Staff/v1/staffStaff member management
Roles/v1/rolesRole-based access control
Customers/v1/customersCustomer data and analytics
Retailers/v1/retailersRetailer and location management

​
Equipment

DomainBase PathDescription
Equipment/v1/equipment/*Carts, robots, totes, cold storage
Bags/v1/equipment/bagsCold storage bag management
Nodes/v1/nodesWarehouse location nodes

​
Scheduling & Auth

DomainBase PathDescription
Scheduling/v1/scheduling/*Shifts, timesheets, leave, approvals
Auth/v1/auth/*Clock in/out, PIN verification

​
Utilities

DomainBase PathDescription
Search/v1/searchGlobal and product search
Reference/v1/referenceBrands, categories reference data
Actions/v1/actionsEquipment actions and barcode identification
Tasks/v1/tasksUser task aggregation
Notifications/v1/notificationsNotification management
Settings/v1/settingsSystem configuration
Scrapers/v1/scrapersProduct scraper management
Scan History/v1/scan-historyScanner scan history

​
ID Resolution

All endpoints that accept an :id parameter support both formats: 
GET /v1/products/550e8400-e29b-41d4-a716-446655440000
The API automatically detects the format:
  • UUID: 36 characters with hyphens (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  • Taxonomy ID: Exactly 18 digits (DDDDDDDDDDDDDDDDDD)
See the Taxonomy ID Guide for details on the ID format.

​
Common Response Formats

​
Success Response

{
  "success": true,
  "data": { ... }
}

​
List Response

{
  "items": [ ... ],
  "total": 100,
  "limit": 20,
  "offset": 0
}

​
Error Response

{
  "error": "Error Type",
  "message": "Detailed error description"
}

​
Pagination

List endpoints support pagination via query parameters:
ParameterTypeDefaultDescription
limitnumber20Number of items per page (max varies by endpoint)
offsetnumber0Number of items to skip
GET /v1/products?limit=50&offset=100

​
Filtering

Many list endpoints support filtering: 
# Filter products by type
GET /v1/products?filter=rfc

# Filter orders by status
GET /v1/orders?status=pending

# Search products
GET /v1/products?search=organic%20milk

​
Rate Limiting

The API implements rate limiting to ensure fair usage:
TierRequests/minuteBurst
Standard60100
Service Account300500
Rate limit headers are included in responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

​
Versioning

The V1 API is versioned in the URL path. Future versions (v2, v3, etc.) will be introduced as separate paths while maintaining backward compatibility with existing versions. 
/v1/* - Current stable version

​
SDKs and Tools

TypeScript Types

Auto-generated TypeScript types from the OpenAPI spec.

MCP Server

Connect Claude and other AI assistants to your Switchyard data.

​
Next Steps