Configuration

Scalar SDK generation is driven by a single config object: which languages to generate, the resource tree the clients expose, the environments they can reach, and how each package is named, versioned, and published.

The top-level targets map controls which artifacts are generated, while resources controls the public client shape.

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

Minimal config

Every property the schema requires, with a real value apiece. $schema is the one addition: it is not required, and an editor that reads it validates the file and completes its keys as you type.

{
  "$schema": "https://registry.scalar.com/@scalar/schemas/sdk-config",
  "organization": {
    "name": "Acme"
  },
  "environments": {
    "production": "https://api.acme.com"
  },
  "environmentOrder": [
    "production"
  ],
  "targets": {
    "typescript": {
      "packageName": "@acme/api"
    },
    "python": {
      "packageName": "acme_api",
      "projectName": "acme-api"
    },
    "cli": {
      "binaryName": "acme"
    }
  },
  "resources": {
    "users": {
      "methods": {
        "list": "get /users",
        "create": "post /users"
      },
      "models": {
        "User": "User"
      }
    }
  }
}

Properties

organization

{
  "organization": {
    "name": "Acme",
    "docs": "https://docs.acme.com",
    "contact": "sdk@acme.com",
    "securityContact": "security@acme.com"
  }
}

resources

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

Each resource can carry generated methods, public models, nested subresources, default request options, and per-target visibility rules.

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

targets

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

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

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.

environments

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

environments maps a name to a base URL; environmentOrder fixes the order the generated client lists them in, and its first entry is the environment a client uses when none is chosen.

clientSettings

{
  "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, though not every target supports every location. They can also map to OpenAPI security schemes or server variables.

pagination

Define reusable pagination schemes in pagination, then bind them to methods with paginated. See Pagination for the full field vocabulary, one worked example per strategy, and the helpers each target generates.

{
  "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": {
          "kind": "http",
          "endpoint": "get /users",
          "paginated": "cursor"
        }
      }
    }
  }
}

A scheme nothing references is reported as unused rather than silently ignored.

Supported pagination types are cursor, cursorId, cursorUrl, fakePage, offset, and pageNumber.

querySettings

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

nestedFormat

Allowed values: "brackets", "dots"

arrayFormat

Allowed values: "comma", "repeat", "indices", "brackets"

multipartSettings

arrayFormat

Allowed values: "comma", "repeat", "indices", "brackets"

openapi

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

{
  "openapi": {
    "securitySchemeSettings": {
      "OAuth": {
        "resource": [
          "https://api.example.com"
        ],
        "audience": "https://api.example.com"
      }
    }
  }
}

These sit next to the source API document rather than in it: they override its security for the generated SDKs, transform it before generation, and control the code samples and tags written to the augmented OpenAPI document the generator writes, without editing the document you maintain.

securitySchemeSettings adds what an OpenAPI security scheme has no field for, keyed by scheme id. Unlike securitySchemes, an entry does not replace the scheme. For an OAuth 2.0 or OpenID Connect scheme, resource (RFC 8707 resource indicators) and audience name the API a token is requested for, so an authorization server that fronts several APIs issues one this API accepts. Each generated client that requests tokens sends them: the Rust SDK's client-credentials exchange, and every request the CLI's login makes, the refresh included. A key naming no OAuth 2.0 or OpenID Connect scheme does nothing, and generation reports it as Config/UnusedSecuritySchemeSettings.

diagnostics

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

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

failOn

Allowed values: "off", "info", "warn", "error"

maxWarnings

Constraints: minimum: 0

maxErrors

Constraints: minimum: 0