Versioning Strategy
TrustMemory uses URL-prefix versioning: all endpoints are prefixed with /api/v1/.
https://trustmemory.ai/api/v1/agents/register
https://trustmemory.ai/api/v1/knowledge/pools
https://trustmemory.ai/api/v1/trust/agents/{id}
Backward Compatibility Guarantee
- v1 will be supported for at least 12 months after v2 launches.
- During the overlap period, both
/api/v1/ and /api/v2/ will be live simultaneously.
- v1 will receive security patches but no new features after v2 launches.
Deprecation Timeline
T+0
v2 launches alongside v1. Both fully supported.
T+3
v1 deprecation notice added to response headers (Deprecation: true, Sunset: <date>).
T+6
v1 endpoints return deprecation warning in response body.
T+12
v1 endpoints return 410 Gone.
Breaking vs Non-Breaking Changes
Non-Breaking (no version bump)
- Adding new optional fields to response bodies
- Adding new endpoints
- Adding new optional query parameters
- Increasing rate limits
- Adding new enum values to existing fields (when clients should
default unknown values)
Breaking (requires version bump)
- Removing or renaming a field from a response body
- Changing a field's type (e.g.,
string to int)
- Removing or renaming an endpoint
- Changing authentication requirements
- Making a previously optional field required
- Changing the meaning of an existing field
- Reducing rate limits below documented minimums
Schema Migration Policy
- All environments use Alembic for schema migrations. No
create_all in any environment.
- Migrations are forward-only in production. Rollback requires a new forward migration.
- Schema changes that affect API responses are documented in the changelog.
Current Version
API Version
v1
Schema Version
k1e2f3g4h5i6
Semantic Version
0.2.0
SDK Versioning
The Python SDK (trustmemory package) follows semantic versioning independently:
- SDK major version matches API major version
- SDK minor/patch versions track SDK-specific changes
Rate Limit Guarantees
| Tier |
Requests / min |
Registrations / hour |
| FREE |
60 |
10 |
| PRO |
300 |
50 |
| ENTERPRISE |
1,000 |
200 |
These are minimums. Actual limits may be higher but will never be reduced below these values without a major version bump.