> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchyard.run/llms.txt
> Use this file to discover all available pages before exploring further.

# V1 API Overview

> Unified domain-based API for all Switchyard operations

# 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

<CardGroup cols={2}>
  <Card title="Dual ID Support" icon="fingerprint">
    All endpoints accept both UUIDs and 18-digit taxonomy IDs as identifiers.
  </Card>

  <Card title="Domain-Based Structure" icon="sitemap">
    Endpoints are organized by business domain (products, orders, sweeps, etc.).
  </Card>

  <Card title="Consistent Authentication" icon="lock">
    All routes require Bearer token authentication via Supabase Auth.
  </Card>

  <Card title="Zod Validation" icon="shield-check">
    Request/response validation using Zod schemas for type safety.
  </Card>
</CardGroup>

## Authentication

All V1 API endpoints require authentication using a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.switchyard.run/v1/products
```

<Note>
  Get your access token by authenticating with Supabase Auth. See the [Authentication Guide](/authentication/overview) for details.
</Note>

## 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:

<CodeGroup>
  ```bash UUID theme={null}
  GET /v1/products/550e8400-e29b-41d4-a716-446655440000
  ```

  ```bash Taxonomy ID theme={null}
  GET /v1/products/011300000012345042
  ```
</CodeGroup>

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](/architecture/taxonomy-ids) for details on the ID format.

## Common Response Formats

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

### List Response

```json theme={null}
{
  "items": [ ... ],
  "total": 100,
  "limit": 20,
  "offset": 0
}
```

### Error Response

```json theme={null}
{
  "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                           |

```bash theme={null}
GET /v1/products?limit=50&offset=100
```

## Filtering

Many list endpoints support filtering:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="TypeScript Types" icon="code">
    Auto-generated TypeScript types from the OpenAPI spec.
  </Card>

  <Card title="MCP Server" icon="plug" href="/guides/mcp-installation">
    Connect Claude and other AI assistants to your Switchyard data.
  </Card>
</CardGroup>

## Next Steps

* Browse the auto-generated API documentation below for detailed endpoint references
* [Authentication Guide](/authentication/overview) - Set up API access
* [Taxonomy ID Guide](/architecture/taxonomy-ids) - Understand the ID system