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

# Platform Catalog API v1 overview

> REST API reference for the StoreRouter Platform Catalog API v1 - base URL, authentication, endpoints, error codes, and OpenAPI spec link.

The StoreRouter Platform Catalog API v1 is a server-to-server REST API for Developer organizations. It lets you list covered domains, inspect your calling credential and limits, search products across active crawled catalogs, find products similar to a source product, look up a product by its page URL, and maintain coverage URL lists that StoreRouter joins against its catalogs daily. Choose the REST API for API-key server workloads, or use the [Developer MCP server](/docs/mcp/overview) for OAuth-based agent workflows.

## Base URL and content type

All requests go to:

```http theme={null}
https://api.octogen.ai/v1
```

Every request body and response body uses `application/json`. Set `Content-Type: application/json` on requests that include a body.

## Authentication

Send your Platform API key as a Bearer token on authenticated requests:

```http theme={null}
Authorization: Bearer octo_live_<32-hex-id>_<base64url-secret>
Content-Type: application/json
```

API keys are organization-scoped and currently usable only by Developer organizations. A key can search and browse every active crawled catalog, including catalogs activated later, and can never access merchant catalogs. Rotate or deactivate keys in StoreRouter Platform; deactivation takes effect on the next request.

`GET /domains`, `POST /products/lookup`, and `POST /products/search` also support a limited keyless trial. Include an API key for production workloads and access to the complete `/v1` surface.

<Warning>
  Never expose your Platform API key in client-side code or public repositories.
  Treat it like a password.
</Warning>

## OpenAPI specification

The machine-readable contract is published at every platform deploy:

```text theme={null}
https://cdn.octogen.ai/openapi/platform/v1/openapi.json
```

The document includes server URLs, operation IDs such as `listDomains`, `getMe`, `searchProducts`, `moreLikeThisProducts`, `lookupProduct`, `resolveProductFromHtml`, `startVoyage`, `getVoyage`, `listVoyages`, `createUrlList`, `listUrlLists`, `getUrlList`, `deleteUrlList`, `addUrlListUrls`, `removeUrlListUrls`, `checkUrlListUrls`, and `listUrlListUrls`, full request and response schemas, and example error bodies. Most ecosystems can generate a typed client from it - for example `openapi-generator`, `openapi-typescript`, or `oapi-codegen`.

## Endpoints

The public reference currently documents these endpoints.

| Method | Path | Operation | Description |
| - | - | - | - |
| `GET` | `/domains` | `listDomains` | Lists the domains covered by active crawled catalogs. |
| `GET` | `/me` | `getMe` | Returns the calling credential's identity, quotas, and rate-limit status. |
| `POST` | `/products/lookup` | `lookupProduct` | Resolves a product page URL to a full product record. |
| `POST` | `/products/more-like-this` | `moreLikeThisProducts` | Finds products similar to a source product URL or UUID. |
| `POST` | `/products/resolve-from-html` | `resolveProductFromHtml` | Extracts a product from HTML supplied by the caller. |
| `POST` | `/products/search` | `searchProducts` | Searches products across all active crawled catalogs, or within one catalog when `catalog` is provided. |
| `POST` | `/voyage` | `startVoyage` | Starts or joins a voyage to add coverage for an ecommerce domain. |
| `GET` | `/voyage/{task_id}` | `getVoyage` | Returns the current progress of a voyage requested by your organization. |
| `GET` | `/voyage` | `listVoyages` | Lists your organization's voyages and current voyage quota usage. |
| `POST` | `/coverage/url-lists` | `createUrlList` | Creates a coverage URL list that StoreRouter joins against its catalogs daily. |
| `GET` | `/coverage/url-lists` | `listUrlLists` | Lists your organization's coverage URL lists. |
| `GET` | `/coverage/url-lists/{urlListId}` | `getUrlList` | Returns one coverage URL list, including its BigQuery listing details. |
| `DELETE` | `/coverage/url-lists/{urlListId}` | `deleteUrlList` | Permanently deletes a coverage URL list and its BigQuery resources. |
| `POST` | `/coverage/url-lists/{urlListId}/urls` | `addUrlListUrls` | Adds product URLs to a list with per-URL outcomes. |
| `GET` | `/coverage/url-lists/{urlListId}/urls` | `listUrlListUrls` | Pages through a list's member URLs. |
| `POST` | `/coverage/url-lists/{urlListId}/urls/remove` | `removeUrlListUrls` | Removes product URLs from a list. |
| `POST` | `/coverage/url-lists/{urlListId}/urls/contains` | `checkUrlListUrls` | Checks which URLs are members of a list. |

## Error model

All error responses carry a top-level `detail` field.

**String detail** (auth, authorization, and not-found errors):

```json theme={null}
{"detail": "product_not_found"}
```

**Array detail** (validation errors):

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal"
    }
  ]
}
```

### Error status codes

| Status | Meaning | Action |
| - | - | - |
| `401` | Missing, malformed, or invalid Bearer token. | Rotate or replace the API key. |
| `403` | Key is valid but not authorized for this resource. | Confirm the organization has access to the requested catalog. |
| `404` | Catalog or product is not visible for this key. | Verify the catalog key identifies an active crawled catalog and the product URL belongs to it. |
| `422` | Request body or field validation failed. | Surface the field-level `loc` and `msg` to identify the invalid field. |
| `429` | Per-organization rate limit exceeded. | Wait the `Retry-After` interval, then retry — see [Rate limits](#rate-limits). |

Retry transient network errors, `5xx` responses, and `429` (after waiting `Retry-After`). The other `4xx` codes listed above require a change in the caller.

## Rate limits

Requests are rate limited **per organization** — one budget shared across all of your API keys and MCP sessions. The cap is a generous safety ceiling set well above normal traffic and is not published as a fixed number; read your current allowance from the `X-RateLimit-Limit` response header.

Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. When you exceed the limit, the API returns `429 Too Many Requests` with `detail: "rate_limit_exceeded"` and a `Retry-After` header. See the [Rate Limits guide](/docs/guides/rate-limits) for the headers, backoff code, and the MCP equivalent.

## REST and MCP: choosing a surface

Both surfaces run against the same grants table. A grant change on one path takes effect immediately on the other.

| | REST (`/v1`, API keys) | MCP (OAuth) |
| - | - | - |
| Best for | Backends, batch jobs, server-to-server | Interactive agents (Claude Code, Codex, Claude Desktop) |
| Auth | Bearer `octo_live_...` key | OAuth 2.1 + PKCE, audience-bound access token |
| Token lifetime | Until manually revoked | \~5 minutes access; refresh until session expiry |
| Revocation | Revoke the API key | Sign out or remove the user from the organization |

<Tip>
  If you are building an agent-based workflow and already have OAuth in place,
  prefer the MCP server — the tool signatures map 1:1 to these REST endpoints.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.