Docs › api-stability

TabMind v1.0.0 — API Stability Contract & Deprecation Policy

Status: Live as of v1.0.0 (2026-07-31)

Owner: api@seele.agency

Review cadence: Per release, with annual structural review

Last revised: 2026-07-31

1. Why this document exists

The xkg-server API is the public face of TabMind. Anyone building a custom

client, a mobile app, or a partner integration depends on it. The single

worst thing we can do is break someone's integration without warning.

This document is the contract. It says:

If you build against the API, you should be able to read this document and

trust it for the next 12 months with no surprises.

2. Versioning

2.1 URL versioning

The xkg-server API uses URL path versioning:


https://seele.agency/api/v1/...
https://seele.agency/api/v2/...

in v2 lifetime.

2.2 SemVer commitment

We follow Semantic Versioning 2.0.0:

The API version is exposed in three places:

  1. URL path: /api/v1/...
  2. Response header: X-API-Version: 1.0.0
  3. JSON body: {"api_version": "1.0.0"} (on /api/health)

2.3 SDK versioning

If a client SDK is shipped (e.g., xkg-cli, xkg-mobile-flutter,

xkg-desktop), it follows the same SemVer. The SDK version is independent

of the API version — they advance on their own cadence.

3. Stability tier

Every endpoint is tagged with one of three stability tiers:

Tier Meaning Deprecation notice Removal
Stable Production-ready, locked semantics 6 months After notice period
Beta Production-ready, may change 3 months After notice period
Experimental Active development, semantics may shift 1 release Anytime

3.1 Tier rules

the same rules as Stable.

promotion.

deprecation notice.

3.2 Stability Tier response

Every API response includes a X-API-Stability header:

3.3 Path prefix convention

Endpoints under /api/v1/ are Stable by default. Beta and Experimental

endpoints carry a suffix:


/api/v1/...                              → Stable
/api/v1-beta/...                         → Beta
/api/v1-experimental/...                 → Experimental

Deprecated endpoints gain a X-API-Deprecated header with a date and

successor URL.

4. What's in the API

4.1 Stable (v1)

Endpoint Method Purpose
/api/v1/health GET Service health
/api/v1/capture POST Submit a captured conversation
/api/v1/capture/ GET Fetch a specific capture
/api/v1/search GET Full-text search
/api/v1/conversations GET List recent conversations
/api/v1/conversations/ GET Conversation detail
/api/v1/releases/latest GET Latest release info
/api/v1/license/check POST Validate Pro license

4.2 Beta (v1-beta)

Endpoint Method Purpose
/api/v1-beta/sync/devices POST Register a device
/api/v1-beta/sync/devices GET List devices
/api/v1-beta/sync/changes POST Push delta
/api/v1-beta/sync/changes GET Pull delta
/api/v1-beta/kg/links POST Add a graph link
/api/v1-beta/kg/links GET Query graph

4.3 Experimental (v1-experimental)

Endpoint Method Purpose
/api/v1-experimental/providers GET Active LLM providers
/api/v1-experimental/embeddings POST Generate embeddings

5. Deprecation policy

5.1 Deprecation window

Tier Window Notice
Stable 6 months Emailed to api-announce@ + header + status page
Beta 3 months Header + status page, no email
Experimental 1 release Header only

5.2 What "deprecation" means

We mark an endpoint deprecated by:

  1. Adding X-API-Deprecated: true to every response
  2. Adding Sunset header with the removal date (RFC 8594)
  3. Logging a Link: header pointing to the

replacement endpoint, when applicable

  1. Updating the docs at https://seele.agency/docs/api/*
  2. Sending an api-announce@ email (Stable only)
  3. Updating the changelog at https://seele.agency/releases.html

We will never:

notes

5.3 Removal

After the deprecation window:

successor.

the deprecation record.

so we can detect old clients.

5.4 Withdrawal

If we discover a security issue that requires immediate removal:

removed endpoint (see SECURITY.md)

6. Response shapes

6.1 Stable response shape

Stable responses may add fields without notice. They may not

remove, rename, or change the type of any field.


// Stable, can add "metadata" without breaking:
{
  "id": "abc-123",
  "title": "Knowledge graphs",
  "metadata": {
    "tokens": 4231,
    "model": "gpt-4o"
  }
}

6.2 Field-level deprecation

A field may be deprecated independently from an endpoint. We mark it

with _deprecated suffix in the docs and a runtime warning header:


Warning: 299 - "tokens" field is deprecated; use "metadata.tokens" instead

After 6 months, the deprecated field is removed from the response. The

field will return null in the meantime (never raise an error).

6.3 Error shapes

Errors are stable:


{
  "error": {
    "code": "license_invalid",
    "message": "License key revoked or expired",
    "details": {
      "reason": "expired",
      "tier": "free"
    }
  }
}

Error codes are never renamed. New codes may be added. The error

envelope is Stable.

6.4 Status codes

Stable-status codes are bound to the spec:

We may add new 4xx codes. Existing 5xx codes are stable. We will not

add 5xx codes without an entry in the changelog.

7. Backward compatibility

7.1 What we guarantee

requires the deprecation policy.

require a new version (v1 → v2).

flow, and license key checks are all Stable.

algorithms (e.g., zstd) but will not disable gzip.

industry consensus.

7.2 What may change

notify via RateLimit-Limit and RateLimit-Reset headers.

demands it. This is a breaking change requiring deprecation.

7.3 What may not change

We don't promise element order. Don't rely on it.

8. Rate limits

Rate limits are defined per API key and per IP.

Tier Default RPS Burst Daily quota
Free (no auth) 1 5 1000
Pro license 10 50 1,000,000
Partner key 100 500 100,000,000

We may tighten these at any time. We will not loosen without

notice. If you rely on higher rates, contact api@seele.agency.

Rate-limit responses include Retry-After header.

9. Breaking change process

A breaking change is a change to any of:

If we want to make a breaking change:

  1. Design v2. Draft the new spec and circulate to api-announce@
  2. Beta release. v2 ships as /api/v2-beta/... flagged Experimental
  3. Deprecate v1. Mark v1 endpoints with X-API-Deprecated: true
  4. 6-month window. During this window, both v1 and v2 are reachable
  5. v1 removal. After 6 months, v1 returns 410 Gone
  6. v2 promotion. v2 becomes Stable, takes the /api/v2/ prefix

The full cycle takes at least 9 months from announcement to v1 removal.

10. Communication

10.1 Announcement channels

10.2 Changelog format

Each entry: version, date, type (added|changed|removed|fixed|security),

summary, affected_endpoints, deprecation_date (if applicable).

10.3 SDK changes

SDKs (Tauri, Flutter, mobile) follow their own SemVer but must match

the API SemVer for lock-step compatibility. If the API is on v1.4.0,

the SDK is on v1.4.x.

The SDK may have a minor version greater than the API (e.g., SDK v1.5.0

against API v1.4.0) for SDK-only features.

11. Security

Security fixes follow the standard responsible disclosure policy at

https://seele.agency/security.html. Critical CVEs may bypass the

deprecation window per §5.4.

12. Acceptance

This document is the contract. By using the API, you accept:

client code

If you need a different contract (e.g., higher rate limits, custom

endpoints), contact partner@seele.agency.

13. Acknowledgments

Published: 2026-07-31

This API stability contract is the result of v0.7 → v0.9 release work

plus 1 v1.0.0 sprint (TASK-HUB-20260731-188).

If you find a bug in this document, file at https://github.com/griptoad26/seele-agency-site/issues

with the api-stability label.

TL;DR for integrators: