BBEdit AI Worksheet Models

[Note: The information in this document applies to BBEdit 15.1 and later.]

Introduction

BBEdit AI Worksheet API models reside in the "Chat API Descriptions" application support folder. This folder does not exist by default, but can be created by choosing "Application Support" from the Folders submenu of the BBEdit application menu, and then manually creating a new folder named "Chat API Descriptions".

Changes in this folder, or to models in this folder, generally take effect the next time you make a new AI worksheet that uses that model.

File Format

API model files are written as JSON, and may contain comments as documented here. The file must be valid and well formed, and the file's name must end with .json.

The following descriptions of keys and values make reference to an example models, which are themselves derived from BBEdit's built-in models. You can download the examples here.

Basic Structure

An API model contains the following keys and values. Some (but not all) are required, and not all values are necessary for all services.

1. com.barebones.DocumentType: required, and must always be "com.barebones.bbedit.ChatAPIDescription".

2. com.barebones.DocumentFormatVersion: required, and must always be "1".

3. identifier: required, and must be of nonzero length and human-readable. This is a string which uniquely identifies the service, and although it doesn't appear in the UI, its value is used to create preferences keys. Therefore it should be an unbroken sequence of printable ASCII characters, letters and numbers only.

4. displayName: required, and must be of nonzero length and human readable. This is displayed in the UI.

5. endpoint: required, and must be of nonzero length and a valid absolute URL string. This is the URL of the API's endpoint. Usually this will be an https URL, but in the case of a local-only service it is not required (e.g. for Ollama).

6. models: required, and must contain at least one nonzero length string. This is an array of strings, listing the available language models supported by the service. The list is not expected to be comprehensive, but should include any models that the user might typically want to employ. BBEdit provides a facility for entering a custom model name. Zero-length strings in the array will cause BBEdit to generate a menu separator. This can be used to group related models together, in case the list is more than a few models long.

7. defaultModel: required, and must be a nonzero-length string. This is the identifier for the model that BBEdit will use by default for this service, in the event the user does not choose (or enter) something different in the Settings window.

8. requiresAPIKey: optional: if present must be a numeric "0" or "1". Most services require a valid API key. Some do not (for example, Ollama). Thus, a typical usage for a local service would be to specify requiresAPIKey: 0;. If omitted, the default value is 1 and BBEdit will require entry of a valid API key.

9. getAPIKeyURL: required if requiresAPIKey is true; if present must be a valid absolute URL string. BBEdit will use this as a link for users to go to a suitable location on the API provider's web site in order to obtain an API key for use in BBEdit.

10. accountHelpURL: required if requiresAPIKey is true; if present must be a valid absolute URL string. BBEdit will use this as a link for users to get help obtaining account (which is usually required in order to use the API).

11. endpointKeyHeaderName: optional; if present must be a valid HTTP header name. The ChatGPT API uses "Authorization" as the HTTP header name for API validation. Other services may use other names (for example, Claude uses "x-api-key"). If not specified, BBEdit will put the API key in the Authorization: header.

12. endpointKeyHeaderValueFormat: optional: if present specifies the value formatting for the API key header value. This string is case sensitive, and must contain "${key}" as a placeholder for where the API key value should be placed. For example, the API key header format for ChatGPT is "Bearer: ${key}". This model key is documented only for completeness; see the note below.

13. endpointAdditionalHeaders: optional: if present must be a dictionary of key/value pairs. This is provided in order to specify additional HTTP headers that the API requires. At the moment this is used only by Claude, which requires a version specifier to be provided in the HTTP request headers.

14. additionalRequestParameters: optional: if present must be a dictionary of key/value pairs. This is provided to specify parameters that the API requires with each request. At the moment this is used only for Claude, which alone requires that max_tokens be specified with each request.

15. explicitStreamParameterRequired: optional: if present must be true or false. Specifies whether the service API requires that BBEdit explicitly specify the "stream" API request parameter. This is necessary only for services which will report an API error if the "stream" parameter is not included. Most service providers will default to false for streaming unless otherwise indicated.

Special Considerations

• Service identifiers used by BBEdit's built-in supported services are reserved for the application: do not use chatgpt, claude, or ollama as a service identifier.

• Only ChatGPT is likely to need the endpointKeyHeaderValueFormat override; most services use only the plain API key string as the API key's header value.

---

Back to Technical Notes