Docs / API versioning
API versioning and deprecation policy
Brandloop serves one public API version, v1, at /api/v1. The version is part of the URL, additive changes ship inside v1 without notice, and the change classes that would break an existing caller are blocked by a contract check rather than by an intention.
One version, and it lives in the URL
All 10 public API operations, across 9 paths, are served under /api/v1. The version is the path segment. There is no version header, no version query parameter, and no dated release to pin: calling /api/v1 is the pinning mechanism, and it is the only version Brandloop serves.
- v1 is the current and only public API version.
- No Accept-header, query-parameter, or dated version negotiation exists.
- A future major version would be a new path prefix served alongside /api/v1, not a change made to it.
The OpenAPI document version is not the API version
The machine-readable contract at /openapi.json carries info.version 0.1.0. That number describes the document — schemas, descriptions, examples — and not the URL major version; a document bump never moves an endpoint. It is a document-level label rather than a per-change counter: nothing requires it to move when the contract changes, so treat it as an identifier and diff the document itself rather than watching that number for change. The document and the rendered reference at /developers/api are generated from the same workspace contracts the API routes validate requests against, and the checked-in contract artifact is regenerated and drift-checked before a contract change ships, so the published document cannot fall behind the implementation unnoticed.
What cannot change inside v1
The list below is a repository gate rather than a stated intention. Every contract change is diffed against the currently published document, and each of these change classes fails that check. That is what makes them safe to build against.
What can change inside v1 without notice
Everything additive. New endpoints, new optional request fields, new fields on existing responses, new members of an existing enum, and newly documented response codes can all appear inside v1 at any time. Write clients that ignore response fields they do not recognise and treat an unfamiliar enum value as unknown rather than as an error — the Brandloop MCP server does exactly that with API status values, specifically so a new status cannot break something already shipped.
- New endpoints and new optional request fields.
- New response fields: ignore what you do not recognise.
- New enum members: treat an unknown value as unknown, not as a failure.
- Rate limits, credit costs, and generation-profile availability are product settings and can change inside v1.
Deprecation: what is actually in place today
Brandloop does not send Deprecation or Sunset response headers, does not publish a dated deprecation feed, and has not committed to a fixed notice window. Publishing a number nobody has agreed to would be worse than publishing none. What does exist is concrete: the change classes above cannot land on v1; the one availability signal the API itself carries is the status field on GET /api/v1/generation-profiles, which reports stable, preview, or deprecated per profile and which the contract explicitly labels a discovery label rather than an SLA; and if a removal or breaking change to /api/v1 is ever scheduled, it is announced on this page and in the product changelog before it takes effect.
- No Deprecation or Sunset response headers are sent today.
- No fixed notice period is promised, and this page does not create one.
- Generation profiles expose a stable, preview, or deprecated status for discovery.
- If a removal is ever scheduled, it is published here and on the changelog before it takes effect.
Error codes are part of the contract
Error responses use application/problem+json and carry a stable machine-readable code alongside the HTTP status. Codes behave like enums: new ones can appear, existing ones are not repurposed to mean something else. Branch on the status and the code, never on the human-readable detail string, which is free to be reworded.
Generating and pinning a client
The public contract for client generation is /openapi.json. The TypeScript SDK inside the Brandloop monorepo is generated from that same document, is an internal preview with no published package, and carries no separate public version guarantee. Generate your client from the document, keep the generated output under review in your own repository, and regenerate when you want the additions — that generated artifact is your pinned copy, because the API itself always serves current v1.
Changes that cannot ship inside /api/v1
| Change | What it would break | How it is prevented |
|---|---|---|
| Removing a path | Every client calling that URL. | The contract diff fails on a path present in the published document and absent from the change. |
| Removing an operation | Clients using that method on a path that still exists. | The contract diff fails on a method present in the published document and absent from the change. |
| Making a request body required | Callers that legitimately send no body today. | The contract diff fails when an optional request body becomes required. |
| Adding a required parameter | Every existing call, which omits it. | The contract diff fails on a required parameter that the published operation did not have. |
| Removing a documented response code | Error handling written against the documented status. | The contract diff fails on a response code present in the published document and absent from the change. |
Pin by path, review by document version
bashThe path is the version. The document is what to diff when reviewing what changed underneath it; info.version labels that document rather than counting changes to it.
# The version you call is the version you get.
curl "$BRANDLOOP_BASE_URL/api/v1/me" \
-H "Authorization: Bearer $BRANDLOOP_API_KEY"
# The contract document itself, for change review and client regeneration.
# Keep the fetched copy in your repository and diff it; info.version is a
# label on the document, not a counter that moves on every change.
curl -s "$BRANDLOOP_BASE_URL/openapi.json" -o brandloop.openapi.json
jq -r '.info.version' brandloop.openapi.jsonLimitations and boundaries
- This policy covers the public /api/v1 HTTP surface. The MCP server at /api/mcp and its tool manifest version separately from the REST contract.
- Versioning commitments are about contract shape, not availability. Nothing here is an uptime, latency, capacity, or support guarantee.
- No fixed deprecation window is published today, and this page should not be read as creating one.
- Rate limits, credit costs, plan entitlements, and generation-profile availability can change inside v1 without a version bump.
Common questions
- Is there a v2?
- No. v1 is the only public Brandloop API version. If a v2 is ever introduced it will be served at a new path prefix alongside /api/v1 rather than replacing it in place.
- Will fields be added to responses without telling me?
- Yes. Additive changes ship inside v1 without notice, which is exactly why clients should ignore unknown response fields and treat unknown enum members as unknown rather than as errors.
- Do Brandloop API responses carry Deprecation or Sunset headers?
- Not today. If an endpoint is ever scheduled for removal, the announcement is published on this page and on the changelog rather than delivered as a response header.
- How do I pin to a specific version of the contract?
- There is no server-side pinning. Generate a client from /openapi.json and treat that generated artifact as your pinned copy; the API always serves the current v1 contract.