#API Reference

The Universal Goods REST API provides programmatic access to products, batches, and items, including their structured data sections and verifiable credentials.

#Base URL

All API endpoints are served under the /api prefix:

https://your-instance.universalgoods.io/api

For local development, the base URL is typically http://localhost:3000/api.

#Authentication

All API requests require an API key passed as a Bearer token:

curl -H "Authorization: Bearer ug_live_abc123..." \
     https://your-instance.universalgoods.io/api/products

Create a key in Settings > API Keys in the dashboard. Keys are scoped to either your personal permissions or the full organization.

See Authentication for full details on key scopes and organization context.

#Common response patterns

#Success responses

Most endpoints return JSON with a 200 status. List endpoints return paginated objects:

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

Single-resource endpoints return the resource object directly:

{
  "id": 1,
  "title": "Organic Cotton T-Shirt",
  "organizationId": "org_abc123",
  "createdAt": "2026-03-01T12:00:00Z"
}

#Error responses

Errors follow a consistent shape:

{
  "error": "NOT_FOUND",
  "message": "Product with ID 999 not found"
}

Common HTTP status codes:

#Pagination

List endpoints accept limit and offset (or page) query parameters:

#Resource groups

The API is organised around three core resources, each with structured data sections managed through the metadata API:

#Next steps

• Authentication: session and API key details
• Endpoints: complete endpoint reference