Developer docs

5 min read

Getting Started Scaffold

The getting-started scaffold is a structured template generated from your stateanchor.yaml spec. You fill it in once -- and it auto-updates as your spec evolves.

What is the scaffold?

When a new developer needs to integrate with your API, they typically need to answer four questions before writing a single line of code: how do I authenticate, what do I call first, what are the common operations, and how do I handle errors?

StateAnchor generates a structured document that answers those questions from your spec, so you spend time filling in the specifics rather than writing the skeleton.

The scaffold has five sections, each corresponding to a part of the developer onboarding journey:

• Authentication-- derived from your spec’s auth configuration. If your spec declares Bearer, API key, or OAuth2 auth, this section is pre-written. If your spec has no auth declaration, it is marked as a placeholder.
• Making your first call -- finds the simplest GET endpoint in your spec (fewest required params, most complete description) and generates a working curl example.
• Common operations -- groups all your endpoints by path prefix or tag and lists them with their descriptions.
• Error handling -- extracts the unique error response codes from your spec and explains each one.
• Upcoming changes -- always generated. Reads from active drift exceptions with deprecation kinds and from spec endpoints or fields marked deprecated: true. Auto-updates on every scaffold regeneration.

What’s automatically generated vs. what needs human input

Sections are either generated (pre-filled from your spec) or placeholders (the scaffold template is there, but the content needs to be written by you).

A section is a placeholder when the spec does not have enough information to generate it deterministically. For example, if your spec declares no authentication scheme, the authentication section is a placeholder -- only you know what token to use and where to get one.

Placeholder sections are clearly marked with [text in brackets] so you know exactly what to replace.

How it auto-updates as your spec evolves

The Upcoming changessection is always regenerated. It reads from your project’s active drift exceptions and deprecated fields in the current spec. When a deprecation is resolved or a new one is added, the section updates automatically on the next regeneration.

Other sections can be regenerated on demand from the project cockpit using the Regenerate button. The scaffold reflects the spec as of the most recent successful sync run.

The scaffold is a template for your docs, not a document stored in StateAnchor. Copy it out, paste it into your README, wiki, or docs platform, and edit it from there.

How to access it

1. Open your project in the StateAnchor dashboard.
2. Click Docs scaffold in the sidebar.
3. Fill in any placeholder sections (marked in brackets) with your project-specific details.
4. Click Copy as Markdown to assemble all sections into a clean Markdown document and copy it to your clipboard.
5. Paste into your README, Notion, Confluence, or GitHub Wiki.

Example output

Here is what a generated scaffold looks like for a realistic payments API:

# Getting Started

## Authentication

This API uses Bearer token authentication. Pass your token in the Authorization header:

```
Authorization: Bearer <your-token>
```

## Making your first call

The simplest endpoint to start with is `GET /health`.

Returns the current service health status.

```bash
curl -X GET "https://api.example.com/health" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

## Common operations

### /payments

- `POST /payments` -- Create a new payment
- `GET /payments/{id}` -- Retrieve a payment by ID
- `GET /payments` -- List payments with optional filters

### /customers

- `POST /customers` -- Create a customer
- `GET /customers/{id}` -- Retrieve customer details

## Error handling

All errors follow a consistent JSON response format:

```json
{ "error": "error_code", "message": "Human-readable description" }
```

**Status codes returned by this API:**

- `400` -- Bad Request -- The request body or parameters are malformed
- `401` -- Unauthorized -- Authentication is required or the token is invalid
- `404` -- Not Found -- The requested resource does not exist
- `429` -- Too Many Requests -- You have exceeded the rate limit
- `500` -- Internal Server Error -- A server-side error occurred

## Upcoming changes

No deprecations at this time.

Generation rules

• Zero LLM calls. The scaffold is fully deterministic -- it reads from the spec IR and drift exception data. No tokens are consumed.
• Idempotent. The same spec always produces the same scaffold, so you can regenerate safely.
• The scaffold is not stored as a document. StateAnchor caches the generated output in your project record so repeated loads are fast, but the editable version lives in your docs platform, not here.