Pin integrations to an explicit API version and keep staging traffic away from production credentials — the same baseline Stripe- and Crisp-style hubs expect from serious partners.
REST versioning
Platform HTTP lives under the V2 prefix:
https://api.tradeics.example/v2/- Prefer path versioning (
/v2/...) over guessing undecided hosts. - Do not hard-code scrapes of undocumented V1 paths; REST API V2 is the contract.
- Breaking changes are called out in Platform Changes (breaking entries appear emphasized).
The LLM proxy is separately versioned as OpenAI-compatible /v1 on https://llm.tradeics.example — that v1 is the LLM surface, not Tradeics REST V1.
Environments
| Environment | Purpose | Credentials |
|---|---|---|
| Staging / sandbox | Integration testing, agent experiments | Dedicated early-access keys when issued |
| Production | Live buyer / supplier data | Production keys only |
Practices:
- Never reuse production tokens in CI or local agent configs.
- Point staging at staging base URLs when provided; otherwise isolate with separate keys even on the same host.
- Document which environment each webhook or MCP connection targets.
Compatibility expectations
- Additive fields may appear without a major bump — clients must ignore unknown JSON properties.
- Removals and semantic changes land as breaking changes in the ledger.
- MCP tool schemas evolve with REST scopes; pin agent prompts to stable tool names when you automate.