Skip to main content
The Octogen Platform Catalog API v1 is a server-to-server REST API for Catalog Partner organizations. It lets you search products across your granted catalogs, look up a product by its page URL, and list the catalogs your organization has been granted access to. Choose the REST API for API-key server workloads, or use the Catalog Partner MCP server for OAuth-based agent workflows.

​
Base URL and content type

All requests go to: 
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 every request: 
Authorization: Bearer octo_live_<32-hex-id>_<base64url-secret>
Content-Type: application/json
API keys are organization-scoped and currently usable only by Catalog Partner organizations. A key can access only the catalogs granted to the organization that owns it. Rotate or deactivate keys via the partner portal; deactivation takes effect on the next request.
Never expose your Platform API key in client-side code or public repositories. Treat it like a password.

​
OpenAPI specification

The machine-readable contract is published at every platform deploy: 
https://cdn.octogen.ai/openapi/platform/v1/openapi.json
The document includes server URLs, operation IDs (listCatalogs, searchProducts, lookupProduct), 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 API exposes three endpoints.
MethodPathOperationDescription
GET/catalogslistCatalogsReturns the catalogs granted to your organization.
POST/products/lookuplookupProductResolves a product page URL to a canonical product record.
POST/products/searchsearchProductsSearches products across all granted catalogs, or within one catalog when catalog is provided.

​
Error model

All error responses carry a top-level detail field. String detail (auth, authorization, and not-found errors): 
{"detail": "product_not_found"}
Array detail (validation errors): 
{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal"
    }
  ]
}

​
Error status codes

StatusMeaningAction
401Missing, malformed, or invalid Bearer token.Rotate or replace the API key.
403Key is valid but not authorized for this resource.Confirm the organization has access to the requested catalog.
404Catalog or product is not visible for this key.Verify the catalog key and that the product URL belongs to a granted catalog.
422Request body or field validation failed.Surface the field-level loc and msg to identify the invalid field.
429Per-organization rate limit exceeded.Wait the Retry-After interval, then retry — see 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 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 forBackends, batch jobs, server-to-serverInteractive agents (Claude Code, Codex, Claude Desktop)
AuthBearer octo_live_... keyOAuth 2.1 + PKCE, audience-bound access token
Token lifetimeUntil manually revoked~5 minutes access; refresh until session expiry
RevocationRevoke the API keySign out or remove the user from the organization
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.