Core Concept

How to describe an API

StateAnchor accepts descriptions in many formats. The more signal you give, the higher the quality of the generated wrapper.

What StateAnchor understands

You can describe your API in any of these ways — or mix and match:

Format	Description
Plain English	Simple descriptions of what each endpoint does.
Endpoint paths	Actual URL patterns with parameters. e.g. `GET /users/{id}`
OpenAPI / Swagger	Full or partial YAML/JSON schema.
curl examples	A curl command — infers method, path, headers, and body.
Response samples	Example JSON responses — infers return types automatically.
Error formats	Describe your error shape — generates matching error classes.

Format examples

Plain English (minimal)

Stripe Payments API.
- Create a charge: POST /v1/charges with amount, currency, source
- Retrieve a charge: GET /v1/charges/{id}
- Refund a charge: POST /v1/refunds with charge_id

With paths and parameters

GitHub REST API — repositories
GET  /repos/{owner}/{repo}           → RepoObject
GET  /repos/{owner}/{repo}/issues    → Issue[]  (params: state, labels, per_page, page)
POST /repos/{owner}/{repo}/issues    → Issue    (body: title, body, assignees[], labels[])

Auth: Bearer token in Authorization header.
Base URL: https://api.github.com

With response shapes

Notion API — pages
GET /v1/pages/{id}
Response:
{
  "id": "uuid",
  "created_time": "ISO8601",
  "properties": { [key: string]: PropertyValue }
}

Errors: { "status": 400|401|404, "code": string, "message": string }
Auth: Bearer token. Notion-Version header required.

OpenAPI snippet

paths:
  /weather:
    get:
      summary: Get current weather
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  name: { type: string }
                  main:
                    type: object
                    properties:
                      temp: { type: number }

Tips for better output

TIP: Include the base URL. StateAnchor uses it to set the correct default in the constructor and README examples.

TIP: Describe the auth pattern. e.g. "Bearer token in Authorization header" or "API key in X-Api-Key header". This generates a proper constructor and request helper.

TIP:Describe the error shape. Even a simple note like "Errors return { error: string, code: number }" lets StateAnchor generate a typed error class.

WARNING: Avoid including sensitive values (actual API keys, tokens) in your description. Use placeholders like YOUR_API_KEY instead.

What happens to your description

StateAnchor sends your description to a language model with a structured prompt that extracts:

All endpoints (method, path, parameters, body shape)
Response types for each endpoint
Authentication method and required fields
Error format and status codes
Any special behavior (pagination, rate limits, versioning)

The extracted structure is then used to render the final wrapper in your chosen language. Your description is never stored beyond the generation process.

← Quickstart Output format →