Developer quickstart

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.

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.

Create a Test API key

Open your workspace and go to Developers.
Under API keys, choose Create key.
Name the key (for example, Quickstart test).
Select Test as the environment.
Choose the scopes you need. For this quickstart, select accounts:read, quote-spec:read, and simulations:write.
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:

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:

{
  "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:

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:

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:

{
  "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:

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:

{
  "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 using POST /v1/accounts/{id}/quotes (requires quotes:write scope and an Idempotency-Key header).
Create a commitment when the customer accepts using POST /v1/accounts/{id}/quotes/{quoteId}/commitment.
Set up webhooks to receive commitment events.
Read Authentication to understand scopes, environments, and key rotation.
Read Test and Live to understand environment isolation.
Browse the full API reference for request and response schemas.

Start here

Core concepts

Distribution

Operations

Developer quickstart

Before you start

Create a Test API key

Check your key

Find your account ID

Read the quote spec

Run a simulation

Success

Next steps

​Before you start

​Create a Test API key

​Check your key

​Find your account ID

​Read the quote spec

​Run a simulation

​Success

​Next steps

Before you start

Create a Test API key

Check your key

Find your account ID

Read the quote spec

Run a simulation

Success

Next steps