Versioning and compatibility

The API version is part of the URL. Every route in this documentation lives under https://api.scribewren.com/v1.

Changes that ship without a new version

Inside /v1, changes are additive only. These can appear at any time:

• new endpoints;
• new optional request fields;
• new fields in responses;
• new values in an enum, such as a status, a stage or a warning;
• new error.code values.

Your client has to tolerate them. The next section lists what that means in practice.

Breaking changes

A change that could break a working client needs a new version path, such as /v2. That includes:

• removing or renaming a field;
• changing the type of a field;
• making validation stricter.

Scribewren announces a breaking change on the changelog at least 30 days before it takes effect, as the Terms of Service say.

Plan limits are not part of the version

Limits such as file size and concurrency belong to the plan, not to the API version, and the Terms cover how plan changes are announced. Read the current values from GET /me/usage and GET /plans instead of hardcoding them. See Usage.

Write a tolerant client

• Ignore response fields you do not know. Do not fail on an extra key.
• Treat an unknown enum value as unknown. Give every switch on a status, stage or warning a default branch.
• Branch on the HTTP status and on error.code, never on message. If you meet an error.code you do not know, handle it by its HTTP status. See Errors.
• Do not depend on the order of keys in JSON, or on the exact format of an ID beyond treating it as an opaque string.
• Send only the request fields this documentation lists. The API rejects unknown fields in a request body on purpose, so a typo does not pass silently.
• Keep /v1 in your base URL setting, so a move to a later version is a configuration change.

What counts as the API

The documented routes on api.scribewren.com are the API. The first-party routes that the Scribewren app uses are not part of it, and the API host does not serve them: a path that is not documented returns 404 NOT_FOUND. Managing keys and webhook endpoints happens in the app, not through the API.

Not in version 1

These are not available in /v1. They are listed so you do not wait for them in your integration:

• a published OpenAPI file;
• key scopes;
• team keys;
• IP allowlists;
• more webhook event types.

Stay informed

Read the changelog when you plan a release of your integration. It is where breaking changes are announced.