#Endpoints

Complete reference for the public Universal Goods API endpoints. All paths are relative to /api.

#Products

Product definitions. Each product belongs to an organization and can have structured data sections, batches, and items.

#CRUD

Create request body:

{
  "organizationId": "org_abc123",
  "title": "Premium Leather Handbag",
  "description": "Full-grain Italian leather, brass hardware",
  "uidPrefix": "PLH",
  "imageUrl": "https://cdn.example.com/plh.jpg",
  "categoryId": "cat_uuid"
}

Only organizationId and title are required. All other fields are optional.

#Data sections

Each product can have multiple detail sections (materials, sustainability, certifications, etc.) managed through the metadata API.

Detail upsert body:

{
  "slug": "materials",
  "title": "Material Composition",
  "visibility": "public",
  "description": "Breakdown of materials used",
  "data": {
    "primary": "Full-grain bovine leather",
    "lining": "Cotton",
    "hardware": "Brass"
  },
  "schema": {
    "version": "1.0",
    "jsonSchema": { "type": "object", "properties": { "..." : "..." } },
    "uiSchema": {}
  },
  "includeInDefaultPassport": true,
  "typeUri": "https://schema.universalgoods.io/materials/v1"
}

Only slug and title are required. Set visibility to "public" or "private" to control passport disclosure. Set includeInDefaultPassport to include the section in shared passports by default.

#Credentials

#Batches

Production batches within a product. Batches can be created under a product and also accessed directly by ID.

#Create and list (nested under products)

Create request body:

{
  "productId": "uuid",
  "uidPrefix": "PLH-2603",
  "friendlyUid": "March 2026, Milan Factory",
  "description": "Spring production run",
  "state": "draft"
}

Only productId is required. state defaults to "draft".

#Direct batch access

#Batch states

#Data sections

#Items

Individual tokenised items within a batch. Items can be created one at a time or in bulk, and accessed directly by ID.

#Create and list (nested under batches)

Create request body:

{
  "batchId": "uuid",
  "friendlyUid": "PLH-2603-0001",
  "ethereumAddress": "0x1234...abcd",
  "metadata": {}
}

batchId, friendlyUid, and ethereumAddress are required. The ethereumAddress cannot be changed after creation.

Bulk create body:

{
  "items": [
    { "friendlyUid": "PLH-2603-0001", "ethereumAddress": "0x1234..." },
    { "friendlyUid": "PLH-2603-0002", "ethereumAddress": "0x5678..." }
  ]
}

#Direct item access

#Data sections

#Common patterns

#Pagination

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

Response format:

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

#Error responses

Errors follow a consistent shape:

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