API Design Settings
The API Designer is configurable at three levels: personal editor preferences that follow you across projects, per-specification settings, and the choices you make when creating or importing a spec — including the OpenAPI version and, later, the release target and export formats of each version.
Personal preferences
Open Settings → API Designer to configure your personal editor preferences. Changes are saved automatically, apply immediately, and are stored locally per user — they don't affect teammates. A Reset to Defaults button restores everything.
Editor
| Setting | Description | Default |
|---|---|---|
| Auto-Save | Automatically save changes after editing. | On |
| Save Delay | How long after your last edit auto-save triggers (0.5s–5s). | Shown when Auto-Save is on |
| Default HTTP Method | Method preselected for new endpoints (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS). | GET |
| Default Content Type | Content type preselected for new bodies (application/json, application/xml, application/x-www-form-urlencoded, multipart/form-data, text/plain). |
application/json |
| Path Parameter Warnings | Show warnings for undocumented path parameters. | On |
Display
| Setting | Description | Default |
|---|---|---|
| Property Descriptions | Show descriptions inline in schema properties. | On |
| Code Preview Font Size | 12px Small / 14px Default / 16px Large. | 14px |
| JSON Indentation | 2 or 4 spaces. | 2 |
| Reset Panel Sizes | Restore the default layout of resizable panels. | — |
Validation
| Setting | Description | Default |
|---|---|---|
| Validation Strictness | Relaxed (show only critical errors), Normal (show errors and important warnings), or Strict (show all issues including best practice suggestions). | Normal |
| Show Warnings | Include warnings in validation output. | On |
| Real-time Validation | Validate as you type (may affect performance). | On |
Shortcuts
A searchable list of every keyboard shortcut. Rebind any shortcut by recording a new key combination (modified shortcuts get a Modified badge and conflicts are flagged), reset shortcuts individually or all at once, and Import/Export your bindings as a JSON file.
Quick settings
The Quick Settings popover in the designer toolbar exposes the most-used preferences — Auto-Save and validation strictness — with a link to All API Designer Settings.
Per-spec settings
Open Spec Settings from within a specification. The sheet contains four cards (editing requires specs:write):
- General — the spec's Name and its Base Path (a path prefix for all endpoints, e.g.
/billing/v1). - Versioning Strategy — how consumers select a version (URL path, header, query parameter, or content negotiation), plus version aliases and sunset dates. Covered in detail in Versioning.
- Editor Preferences — a shortcut to your personal Auto-Save and validation settings ("Personal editor settings. These apply immediately and are stored locally.").
- Danger Zone — Delete this specification: permanently deletes the spec and all its versions, endpoints, and schemas, after a confirmation dialog. Requires the specs:delete permission (Admins and Owners).
A sticky Save Changes button appears once you've modified anything.
Creating a specification
Click to create a new spec and the New API Specification wizard asks how you want to start:
| Mode | Description |
|---|---|
| Import | Import OpenAPI, Postman, or Insomnia files. |
| Empty Specification | Start with a blank canvas and add endpoints. |
| Use Template | Start with a pre-built template (CRUD, Auth). |
For Empty and Template modes you fill in the spec's Name, Version (semantic versioning is expected — the wizard warns if the version isn't MAJOR.MINOR.PATCH, since publishing and diffing rely on it), OpenAPI Version, Base Path, and Description. Available templates are CRUD API, Authentication, and Real-time API, each listing how many endpoints it scaffolds.
OpenAPI version
Specs are authored as OpenAPI 3.0 or OpenAPI 3.1 — new specs default to 3.1. Some style-guide rules apply to 3.0 documents only, and the version affects how nullability and numeric bounds are expressed.
Importing an existing API
Choose Import in the wizard to bring in an OpenAPI file, a Postman collection, or an Insomnia export. The full flow — entry points, the preview, the import options and what to do when validation fails — is on its own page: Import & Export.
Renaming and deleting
- Rename API Specification — change the spec's Name and Base Path.
- Delete API Specification — permanently removes the spec: "All endpoints, schemas, and versions associated with this specification will also be deleted." Requires specs:delete.
Releasing and exporting
A version is released through the Release Version wizard, which freezes it and optionally promotes it into an environment — the environment's roles decide whether the release also feeds the public documentation. See Versioning for the full release flow.
Freezing is also what makes a version exportable, in YAML, JSON, Postman or Insomnia form — see Import & Export.
Related
- Versioning — versioning strategy, publishing, and exports
- Endpoints — working inside the designer
- Style Guide — validation rules behind the strictness settings
- Projects — where specifications live