Reference

stateanchor.yaml Reference

The stateanchor.yaml file is the single source of truth for your API. It declares your service identity, endpoints, authentication, and output configuration. StateAnchor parses this file on every push and derives everything else from it.

Top-level schema

Field	Type	Required	Description
`service`	string	Yes	Service name. Max 100 chars. Used in generated code class names.
`version`	string	Yes	Spec version. Max 20 chars. Semantic versioning recommended.
`info`	object	No	Optional metadata: title, description.
`server`	object	Yes	Server configuration including base_url.
`endpoints`	array	Yes	List of API endpoints. Max 50.
`outputs`	object	Yes	Which outputs to generate.
`models`	object	No	Shared data models referenced by endpoints.

service

The service name identifies your API across StateAnchor. It appears in generated SDK class names, MCP server tool prefixes, and artifact metadata.

service: payments-api

Constraints: string, max 100 characters, no special characters except hyphens and underscores.

version

The spec version. StateAnchor tracks version changes and includes the version in generated artifact metadata.

version: "2.4.0"

Constraints: string, max 20 characters. Quoted to prevent YAML number coercion.

info

Field	Type	Required	Description
`title`	string	No	Human-readable API title. Max 200 chars.
`description`	string	No	API description. Max 2000 chars.

server

Field	Type	Required	Description
`base_url`	string	Yes	Base URL for the API. Must be https://. Max 500 chars.
`auth.type`	enum	No	Authentication type: bearer, api_key, basic, oauth2, none.

Example:

server:
  base_url: https://api.acme.com/v2
  auth:
    type: bearer

endpoints

Array of endpoint objects. Maximum 50 endpoints per spec.

Field	Type	Required	Description
`name`	string	Yes	Unique endpoint identifier. Max 100 chars. Used as method name in SDKs.
`method`	enum	Yes	HTTP method: GET, POST, PUT, PATCH, DELETE.
`path`	string	Yes	URL path. Must start with /. Max 200 chars. Supports {param} placeholders.
`description`	string	No	Endpoint description. Max 500 chars.
`auth`	enum	No	Per-endpoint auth override: bearer, api_key, none.
`parameters`	array	No	Query/path parameters.
`request_body`	string	No	Reference to a model name for the request body.
`responses`	array	No	Response definitions with status codes.

Example:

endpoints:
  - name: createCharge
    method: POST
    path: /charges
    description: Create a new payment charge
    auth: bearer
    responses:
      - status: 201
        description: Charge created

outputs

Controls which artifacts StateAnchor generates. At least one must be enabled.

Field	Type	Description
`typescript`	boolean	Generate TypeScript SDK
`python`	boolean	Generate Python SDK
`go`	boolean	Generate Go SDK
`rust`	boolean	Generate Rust SDK
`php`	boolean	Generate PHP SDK
`mcp`	boolean	Generate MCP server
`docs`	boolean	Generate API documentation

Complete annotated example

service: payments-api
version: "2.4.0"

info:
  title: Acme Payments API
  description: Payment processing for the Acme platform

server:
  base_url: https://api.acme.com/v2
  auth:
    type: bearer

endpoints:
  - name: createCharge
    method: POST
    path: /charges
    description: Create a new charge
    auth: bearer
    responses:
      - status: 201
        description: Charge created

  - name: getCharge
    method: GET
    path: /charges/{id}
    description: Get a charge by ID
    auth: bearer

  - name: listCharges
    method: GET
    path: /charges
    description: List all charges
    auth: bearer

  - name: getHealth
    method: GET
    path: /health
    description: Health check
    auth: none

outputs:
  typescript: true
  python: true
  go: true
  mcp: true

Common patterns

Public + authenticated endpoints

Mix auth: none and auth: bearer on different endpoints. Public endpoints like health checks use auth: none, while data endpoints use auth: bearer.

Path parameters

Use {param} syntax in the path: /charges/{id}. Path parameters are automatically extracted and included in generated SDK method signatures.

Multiple output languages

Enable multiple boolean flags under outputs to generate SDKs in several languages from a single spec. All outputs are generated in a single sync run.

Next:Gate Engine →