`api.json`

Path: apis/<api>/api.json

Holds everything about an API that isn't the spec itself: its identity, where to re-import the spec from, the defaults used when creating requests, and the root-level overrides projected into the effective spec.

Example

{
  "version": 1,
  "name": "Swagger Petstore",
  "slug": "petstore-api",
  "baseUrl": "{{baseUrl}}",
  "specSource": {
    "type": "url",
    "url": "https://petstore3.swagger.io/api/v3/openapi.json"
  },
  "defaults": {
    "auth": { "type": "apiKey", "in": "header", "name": "api_key", "value": "{{apiKey}}" },
    "headers": { "Accept": "application/json" }
  },
  "overrides": {
    "info": { "description": "Pet store demo service" }
  }
}

Fields

Field	Type	Required	Description
`version`	`1`	yes	File format version.
`name`	string	yes	Display name.
`slug`	string	yes	URL/path-safe identifier; matches the directory name.
`baseUrl`	string	no	Base URL for requests. Usually a `{{variable}}`; the first import sets it to `{{baseUrl}}`.
`specSource`	object	no	Where to re-import the spec from (see below).
`defaults`	object	no	Templates merged into new request instances (see below).
`overrides`	object	no	Root-level OpenAPI fields projected into the effective spec (e.g. `info`, `servers`, `tags`, `security`).

`specSource`

Three shapes: a file, a URL, or self:

{ "type": "file", "path": "../../backend/openapi.json" }

{ "type": "url", "url": "https://petstore3.swagger.io/api/v3/openapi.json", "headers": { "Authorization": "Bearer {{apiKey}}" } }

{ "type": "self" }

self means API Craft owns the spec: there is nothing upstream to re-import. It is set when you promote defined operations into the spec, and an API without specSource means the same.

The source is used only when you explicitly import. Nothing fetches it in the background, so the project stays self-contained.

`defaults`

A template applied when an instance is created, not inherited at run time. Changing it later doesn't touch existing instances.

Field	Type	Description
`auth`	object	Default auth: `bearer`, `basic`, `apiKey` or `custom` (see request instance).
`headers`	object	Default headers (name → value).
`cookies`	object	Default cookies (name → value).
`middlewares`	object	Default `before`/`after` chains, same shape as on a request instance, `options` included.

The first import fills baseUrl and defaults.auth from the spec's servers and securitySchemes; see what the first import sets up. Re-imports leave both alone.

When an instance is created, the chains from the API, resource and operation defaults are concatenated (first occurrence of a function fixes its position); its options and enabled flag come from the most specific level that lists it.