# Script Bible API Lifecycle Policy

## Versioning

The current stable agent-facing REST base URL is `https://script.bible/api/v1`. The OpenAPI document's server URL includes that version and its paths are relative to it. Unversioned `/api/*` routes remain compatibility aliases for the Script Bible web application, but new external integrations should use `/api/v1/*`.

Within v1, Script Bible may add response fields, optional parameters, endpoints, and enum values. Removing or renaming fields, changing field meaning, making optional inputs required, or otherwise breaking documented clients requires a new major URL version.

## Deprecation

Script Bible will publish a deprecation notice at least six months before removing a documented major version. Deprecated responses will include `Deprecation: @<unix-seconds>` as defined by RFC 9745 and a `Link` with `rel="deprecation"` to migration guidance. When a removal date is scheduled, responses will also include an RFC 8594 `Sunset` HTTP-date. No v1 sunset is scheduled.

## Rate limits

API responses advertise the current IETF HTTPAPI structured fields `RateLimit` and `RateLimit-Policy`. They also expose `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` for clients using the earlier widely deployed field set. Reset values are delay seconds, not timestamps. A 429 response includes `Retry-After` in delay seconds; clients must wait at least that long before retrying.

Limits are per client IP and per application process. Current default traffic is limited to 600 requests per minute; more expensive search, similarity, word, event, and signup operations have lower route-specific limits. Published quota fields are operational hints, not a service-level guarantee.

## Errors

Every non-2xx response controlled by the Script Bible REST surface uses JSON with `error`, `code`, `message`, and `resolution`. Validation errors may also include `field`. Clients should branch on `code`, display or log `message`, and use `resolution` as recovery guidance.