API Versioning & Deprecation

Krawl uses URL-based versioning and a predictable deprecation policy so agents can depend on stable behavior and get machine-readable advance notice before anything is removed.

URL versioningCopy Anchor Link

Versioned, compatibility-sensitive endpoints live under a version prefix:

https://api.krawl.sh/v1/chat/completions
https://api.krawl.sh/v1/models

• The /v1/* namespace is the stable, OpenAI-compatible surface. Breaking changes to these shapes ship under a new prefix (/v2/...), never in place.
• Some core endpoints (e.g. /research, /tasks, /lookouts) are currently served unversioned at the root. Treat the unversioned root as the current major version; additive, backward-compatible changes (new optional fields, new endpoints) can land there without a version bump.

Backward-compatible changes we may make without a version change:

• Adding new endpoints or new optional request fields.
• Adding new fields to response objects.
• Adding new enum values (e.g. new research modes or source types).

Build clients to tolerate unknown fields and ignore enum values they don't recognize.

Deprecation policyCopy Anchor Link

When an endpoint or field is scheduled for removal:

1. Minimum 6-month notice window between the deprecation announcement and the sunset (removal) date.
2. Deprecated responses carry standard RFC 8594 headers so agents detect the deprecation programmatically — no need to read a changelog.
3. A migration guide is linked directly from the response.

Deprecation headers (RFC 8594)Copy Anchor Link

A deprecated endpoint returns:

HTTP/1.1 200 OK
Deprecation: Wed, 01 Oct 2025 00:00:00 GMT
Sunset: Sun, 01 Mar 2026 00:00:00 GMT
Link: <https://docs.krawl.sh/docs/versioning>; rel="deprecation"; type="text/html"

What agents should doCopy Anchor Link

• Log a warning whenever a response contains a Deprecation or Sunset header, including the endpoint and the Sunset date.
• Schedule migration before the Sunset date — after it, the endpoint may return 404/410 or redirect.
• Follow the rel="deprecation" link for the replacement endpoint and migration steps.

resp = client.get("/v1/models")
if "Sunset" in resp.headers:
    logger.warning(
        "Endpoint deprecated; sunset on %s — migrate per %s",
        resp.headers["Sunset"],
        resp.headers.get("Link", "https://docs.krawl.sh/docs/versioning"),
    )

Checking for deprecationsCopy Anchor Link

You can proactively detect deprecations on any call by inspecting response headers — there is no separate endpoint required. Combine this with the OpenAPI spec, which always reflects the current, supported surface.