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

Domain	Base Path	Description
Products	`/v1/products`	Product catalog management
Scraped Products	`/v1/scraped-products`	Scraped product pipeline
Availability	`/v1/availability`	Product availability scoring
Orders	`/v1/orders`	Order management and fulfillment
Sweeps	`/v1/sweeps`	Retail store sweep operations
RFC Picks	`/v1/rfc-picks`	Warehouse pick list management
Inventory	`/v1/inventory`	Inventory and stock management
Receiving	`/v1/receiving`	Inbound receiving workflow

Organization

Domain	Base Path	Description
Staff	`/v1/staff`	Staff member management
Roles	`/v1/roles`	Role-based access control
Customers	`/v1/customers`	Customer data and analytics
Retailers	`/v1/retailers`	Retailer and location management

Equipment

Domain	Base Path	Description
Equipment	`/v1/equipment/*`	Carts, robots, totes, cold storage
Bags	`/v1/equipment/bags`	Cold storage bag management
Nodes	`/v1/nodes`	Warehouse location nodes

Scheduling & Auth

Domain	Base Path	Description
Scheduling	`/v1/scheduling/*`	Shifts, timesheets, leave, approvals
Auth	`/v1/auth/*`	Clock in/out, PIN verification

Utilities

Domain	Base Path	Description
Search	`/v1/search`	Global and product search
Reference	`/v1/reference`	Brands, categories reference data
Actions	`/v1/actions`	Equipment actions and barcode identification
Tasks	`/v1/tasks`	User task aggregation
Notifications	`/v1/notifications`	Notification management
Settings	`/v1/settings`	System configuration
Scrapers	`/v1/scrapers`	Product scraper management
Scan History	`/v1/scan-history`	Scanner scan history

ID Resolution

All endpoints that accept an :id parameter support both formats:

GET /v1/products/550e8400-e29b-41d4-a716-446655440000

GET /v1/products/011300000012345042

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:

Parameter	Type	Default	Description
`limit`	number	20	Number of items per page (max varies by endpoint)
`offset`	number	0	Number 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:

Tier	Requests/minute	Burst
Standard	60	100
Service Account	300	500

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

Browse the auto-generated API documentation below for detailed endpoint references
Authentication Guide - Set up API access
Taxonomy ID Guide - Understand the ID system

​V1 API Overview

​Base URL

​Key Features

Dual ID Support

Domain-Based Structure

Consistent Authentication

Zod Validation

​Authentication

​API Domains

​Core Operations

​Organization

​Equipment

​Scheduling & Auth

​Utilities

​ID Resolution

​Common Response Formats

​Success Response

​List Response

​Error Response

​Pagination

​Filtering

​Rate Limiting

​Versioning

​SDKs and Tools

TypeScript Types

MCP Server

​Next Steps

V1 API Overview

Base URL

Key Features

Authentication

API Domains

Core Operations

Organization

Equipment

Scheduling & Auth

Utilities

ID Resolution

Common Response Formats

Success Response

List Response

Error Response

Pagination

Filtering

Rate Limiting

Versioning

SDKs and Tools

Next Steps