Configuration

Use the config to keep SDK behavior predictable across generated targets. The top-level targets map controls which artifacts are generated, while resources controls the public client shape.

For SDK-specific behavior embedded in an OpenAPI document, see OpenAPI Extensions. Root-level Scalar extensions mirror the corresponding configuration blocks, while operation and schema extensions can refine individual generated methods and types.

Minimal config#

{
  "name": "Acme API",
  "environments": {
    "production": "https://api.acme.com"
  },
  "environmentOrder": ["production"],
  "targets": {
    "typescript": {
      "packageName": "@acme/api"
    },
    "python": {
      "packageName": "acme_api",
      "projectName": "acme-api"
    },
    "cli": {
      "binaryName": "acme"
    }
  },
  "resources": {}
}

Required properties#

Property	Description
`name`	Human-readable SDK or product name used for generated metadata and clients.
`resources`	Resource tree that defines the generated client and resource shape.
`targets`	Per-language packaging, publishing, and emitter options.
`environments`	Named base URLs the generated client can switch between.
`environmentOrder`	Environment insertion order. The first entry is the default environment.

Targets#

Add a key under targets for every artifact you want Scalar to generate.

{
  "targets": {
    "typescript": {
      "packageName": "@acme/api",
      "packageManager": "pnpm",
      "destinations": {
        "production": {
          "repo": "acme/acme-typescript"
        }
      }
    },
    "python": {
      "packageName": "acme_api",
      "projectName": "acme-api"
    },
    "cli": {
      "binaryName": "acme",
      "defaultFormat": "json"
    }
  }
}

Supported target keys are typescript, python, cli, go, rust, java, kotlin, swift, ruby, php, csharp, cpp, and dart.

Set skip: true on a target to keep its config in place without generating it.

Set promotion: "manual" on a target to hold each build at staging until you promote it, instead of pushing to its production repository automatically. See GitHub Repositories.

Resources#

The resources object defines the public client tree. Each resource can contain generated methods, public models, nested resources, default request options, and per-target visibility rules.

{
  "resources": {
    "users": {
      "methods": {
        "list": "get /users",
        "create": {
          "kind": "http",
          "endpoint": "post /users",
          "verb": "post",
          "path": "/users",
          "defaultRequestOptions": {
            "headers": {}
          }
        }
      },
      "models": {
        "User": "User"
      },
      "subresources": {
        "billing": {
          "methods": {
            "listInvoices": "get /users/{user_id}/invoices"
          }
        }
      }
    }
  }
}

Use skip to omit a method, model, or resource globally or for specific targets. Use only to restrict it to a list of targets.

Client Settings#

Use clientSettings for constructor options, authentication values, default headers, environment variable names, timeouts, retries, and response headers surfaced by generated SDKs.

{
  "clientSettings": {
    "opts": {
      "apiKey": {
        "type": "string",
        "description": "API key for Acme.",
        "readEnv": "ACME_API_KEY",
        "securityScheme": "apiKey",
        "role": "value"
      }
    },
    "defaultHeaders": {
      "X-Acme-SDK": "true"
    },
    "defaultClientName": "Acme",
    "defaultEnvPrefix": "ACME",
    "defaultTimeout": 30000,
    "defaultRetries": {
      "maxRetries": 2,
      "initialDelaySeconds": 1,
      "maxDelaySeconds": 10
    }
  }
}

Client options can send values in headers, query parameters, body parameters, or path parameters. They can also map to OpenAPI security schemes or server variables.

Environments#

environments maps names to base URLs. environmentOrder controls the generated order and default.

{
  "environments": {
    "production": "https://api.acme.com",
    "sandbox": "https://sandbox.acme.com"
  },
  "environmentOrder": ["production", "sandbox"]
}

Pagination#

Define reusable pagination schemes in pagination, then reference them from methods with paginated. Schemes are declared, never inferred from parameter names, so a method paginates only when it names one. See Pagination for the full field vocabulary, one worked example per strategy, and the generated helpers each target produces.

{
  "pagination": [
    {
      "name": "cursor",
      "type": "cursor",
      "request": {
        "cursor": {
          "type": "cursor",
          "param": "cursor",
          "location": "query"
        }
      },
      "response": {
        "items": {
          "type": "items",
          "location": "body",
          "path": ["data"]
        },
        "next": {
          "type": "cursor",
          "location": "body",
          "path": ["next_cursor"]
        }
      }
    }
  ]
}

Bind a scheme to a method with paginated, which takes a scheme name, or false to keep the method unpaginated:

{
  "resources": {
    "users": {
      "methods": {
        "list": {
          "endpoint": "get /users",
          "paginated": "cursor"
        }
      }
    }
  }
}

Supported pagination types are cursor, cursorId, cursorUrl, offset, pageNumber, and fakePage for an operation that returns a whole collection in one response but should still be iterated as a page.

Serialization#

Use querySettings and multipartSettings to control how generated request builders serialize arrays and nested objects.

{
  "querySettings": {
    "arrayFormat": "repeat",
    "nestedFormat": "brackets"
  },
  "multipartSettings": {
    "arrayFormat": "brackets"
  }
}

Supported array formats are comma, repeat, indices, and brackets. Supported nested query formats are brackets and dots.

OpenAPI Overrides#

Use openapi for SDK-specific overrides that sit next to the source API document.

{
  "openapi": {
    "codeSampleLanguages": {
      "typescript": true,
      "python": true,
      "cli": true
    },
    "security": [
      {
        "apiKey": []
      }
    ],
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "X-API-Key",
        "in": "header"
      }
    },
    "operationSecurity": true
  }
}

Other Options#

Property	Description
`customCasings`	Override symbol casing and configure initialisms.
`ignoredEndpoints`	Drop endpoints from generation using `"<verb> <path>"`, such as `get /me`.
`errors`	Configure how generated runtimes read error response messages.
`streaming`	Configure global streaming event handling hints for generated SDKs.
`settings`	Cross-target generator behavior, such as file headers and response unwraps.
`multipartSettings`	Multipart/form-data serialization preferences.
`diagnostics`	Gate the build on diagnostic severity, override per-rule severity, and suppress rules.

Diagnostics#

Every build analyzes your OpenAPI document and this configuration together and reports what generation had to skip, guess, or degrade. Use diagnostics to decide which of those findings fail the build. See Diagnostics for how the analysis works and the full list of rules.

{
  "diagnostics": {
    "failOn": "error",
    "maxWarnings": 20,
    "rules": {
      "Endpoint/NotConfigured": "warn"
    }
  }
}

Property	Description
`failOn`	Lowest severity that fails the build: `off`, `info`, `warn`, or `error`. Defaults to `error`; `off` disables severity gating.
`maxWarnings`	Maximum allowed warnings before the build fails.
`maxErrors`	Maximum allowed errors before the build fails.
`rules`	Per-rule severity override keyed by rule id, such as `Endpoint/NotConfigured`. Set a rule to `off` to disable it.
`ignored`	Per-rule suppressions keyed by rule id.

Updated Sep 24, 2026