API Reference
API Overview
Carrot API overview, environments, core conventions, and resource map.
The Carrot API is a document-centric API used by Network Integrators to submit and retrieve traceability data.
The public surface is intentionally small: 6 endpoints across 3 resources (documents, events, attachments).
Base URL
- API:
https://api.carrot.eco - Auth:
https://auth.api.carrot.eco/oauth2/token - Explorer:
https://explore.carrot.eco
Core conventions
- Content type is JSON for API requests and responses.
- Date-time values follow ISO 8601 (for example,
2020-01-01T00:00:00.000Z). - Metadata fields are flexible key-value structures.
- Document history is append-only through events.
Environments
Carrot uses the same base URL for test and production traffic. Environment selection is based on the
clientId used to request an access token.
- Test credentials can only operate on test documents.
- Production credentials can only operate on production documents.
- Cross-environment document relations are not allowed.
Resource map
- Authentication: OAuth 2.0 client credentials flow and token lifecycle.
- Documents: create and retrieve documents.
- Events: append immutable events to document timelines, individually or in batch.
- Attachments: generate presigned upload/download URLs.
- Errors: error codes, rate limits, and troubleshooting.
Integration quick start
For an end-to-end onboarding sequence, use Integrations Quick Start.