> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kordless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer quickstart

> Create a Test API key and make your first request.

This guide walks through creating a Test API key, reading the quote spec, and running your first simulation.

## Before you start

* A Kordless workspace with a published Live Book.
* An organization admin account (required to mint API keys).
* The API access feature on your plan.

<Info>
  If your workspace has no published Book yet, the quote-spec and simulation endpoints return a `no_published_book` error. Publish a Book first — see [Start your first Book](/product/getting-started/start-your-first-book).
</Info>

## Create a Test API key

1. Open your workspace and go to **Developers**.
2. Under **API keys**, choose **Create key**.
3. Name the key (for example, `Quickstart test`).
4. Select **Test** as the environment.
5. Choose the scopes you need. For this quickstart, select `accounts:read`, `quote-spec:read`, and `simulations:write`.
6. Copy the secret immediately — it is shown only once.

The secret starts with `sk_test_`, which marks it as a Test key. Test keys reach only test-mode data and never affect Live customers or billing.

## Check your key

Verify your key works and see what scopes it has:

```bash theme={null}
curl -s https://your-kordless-instance.com/v1/accounts/current \
  -H "Authorization: Bearer sk_test_..." | jq .
```

The response includes your account ID, the environment (`test`), and the scopes your key holds:

```json theme={null}
{
  "object": "account",
  "id": "acct_abc123",
  "name": "Brandon's Auto Studio",
  "environment": "test",
  "scopes": ["accounts:read", "quote-spec:read", "simulations:write"],
  "entitlements": ["api_access", "price_book", "quote_engine", "quote_ui", "accounts"]
}
```

## Find your account ID

List the account targets your key can reach:

```bash theme={null}
curl -s https://your-kordless-instance.com/v1/accounts \
  -H "Authorization: Bearer sk_test_..." | jq .
```

The first entry is your own account (relationship `self`). Connected Accounts appear after it. Find the `id` of the account you want to quote against — you will use it in the next steps.

## Read the quote spec

Fetch the published Book's services and required inputs:

```bash theme={null}
curl -s https://your-kordless-instance.com/v1/accounts/acct_abc123/quote-spec \
  -H "Authorization: Bearer sk_test_..." | jq .
```

The response lists every service the Book covers, its inputs, and the Book version:

```json theme={null}
{
  "object": "quote_spec",
  "book": {
    "key": "brandon-auto-primary",
    "version": 3,
    "currency": "USD",
    "artifact_hash": "sha256:..."
  },
  "services": [
    {
      "service": "oil_change",
      "label": "Oil change",
      "description": "Full-service oil and filter change.",
      "quote_mode": "instant",
      "inputs": [
        {
          "key": "vehicle_type",
          "label": "Vehicle type",
          "type": "select",
          "required": true,
          "options": [
            { "value": "sedan", "label": "Sedan" },
            { "value": "suv", "label": "SUV" },
            { "value": "truck", "label": "Truck" }
          ]
        }
      ]
    }
  ]
}
```

## Run a simulation

Simulate a quote without persisting it. Pass the service key and selections from the quote spec:

```bash theme={null}
curl -s -X POST https://your-kordless-instance.com/v1/accounts/acct_abc123/quote-simulations \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "context": {},
    "services": [
      {
        "service": "oil_change",
        "selections": { "vehicle_type": "sedan" }
      }
    ]
  }' | jq .
```

The response includes the decision, total, line items, derivation, and the Book version used:

```json theme={null}
{
  "object": "quote_simulation",
  "decision": "priced",
  "quote_mode": "instant",
  "book": {
    "key": "brandon-auto-primary",
    "version": 3,
    "currency": "USD",
    "artifact_hash": "sha256:..."
  },
  "total": {
    "low_cents": 5900,
    "high_cents": 5900,
    "currency": "USD"
  },
  "line_items": [
    {
      "source": "oil_change",
      "label": "Oil change — Sedan",
      "kind": "service",
      "quantity": 1,
      "total": { "low_cents": 5900, "high_cents": 5900 }
    }
  ],
  "missing_inputs": [],
  "review_reasons": [],
  "inspection": null,
  "derivation": [
    { "kind": "base", "label": "Base price for oil change" }
  ],
  "warnings": []
}
```

## Success

You have authenticated, read the quote spec, and run a simulation. The simulation used the same evaluator and Book version that a formal quote would use — the only difference is that it was not persisted.

## Next steps

* [Produce a formal quote](/developers/overview) using `POST /v1/accounts/{id}/quotes` (requires `quotes:write` scope and an `Idempotency-Key` header).
* [Create a commitment](/developers/overview) when the customer accepts using `POST /v1/accounts/{id}/quotes/{quoteId}/commitment`.
* [Set up webhooks](/developers/webhooks) to receive commitment events.
* Read [Authentication](/developers/authentication) to understand scopes, environments, and key rotation.
* Read [Test and Live](/developers/test-and-live) to understand environment isolation.
* Browse the full [API reference](/api-reference/openapi) for request and response schemas.