API interaction guide

For schemas, request models, and endpoint lists, see the API reference overview. For the internal design, see API structure.

The public API is versioned under /v1. Keep the API origin separate from the versioned path in your client configuration and build requests such as https://api.cml-relab.org/v1/products.

When to use the API directly

• scripted or batch access to structured research data
• connecting Relab records to notebooks or external tooling
• automating repetitive reference-data lookups
• building custom integrations on top of the platform

Authentication

• Browsers use cookies (POST /v1/auth/session/login)
• Apps and scripts use bearer tokens (POST /v1/auth/bearer/login)
• Refresh-token handling depends on the Redis-backed auth path (see Authentication)

Public vs. authenticated routes

Public reference data (taxonomies, materials, product types), product records, and uploaded media are accessible without authentication. Creating or changing records, account management, private user details, and owner-scoped workflows require a valid token.

Suggested first steps

1. Open the API reference overview and choose the surface you need.
2. Check whether the endpoint is public or requires authentication.
3. Start with a read-only request.
4. Inspect response models, especially linked entities and media.
5. Automate writes only once you understand how the product hierarchy is represented.

Interactive tooling and admin tasks

Point a client at the API and authenticate with a bearer token from POST /v1/auth/bearer/login. The same path covers superuser tasks like POST /v1/admin/cache/clear/{namespace}.

• Postman, Bruno, Insomnia: import the OpenAPI schema (app/src/types/openapi.json) for the full endpoint collection, then set auth to Bearer.
• VS Code REST Client / JetBrains HTTP Client: use scripts/admin.http from a repo checkout. Send login once; the token flows into the calls below it.

Integration advice

• Build against the generated OpenAPI schema, not copied examples, which drift.
• For product circularity notes, use circularity_properties as either null or an object with optional recyclability, disassemblability, and remanufacturability strings. Empty objects and empty note strings are normalized to null.
• If you need a stable exported dataset rather than live application access, check the dataset page first.