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

# Quickstart

> From an API key to your first answers in five steps.

These are the same five steps as the onboarding page in the dashboard, which can also run them for you. You need an API key. To get one, sign up in the dashboard:

1. Name your organization and choose a plan.
2. Add a card on the secure payment page. Billing on your plan starts then: see [signing up](/pricing#signing-up).
3. Create your API key: read-write, scoped to `default/*`, and shown once. You can create more on the dashboard's Keys page.

If you leave before adding a card, sign-up picks up there when you come back. New organizations are limited each day. If sign-ups are full when you sign up, you go on the waitlist and we email you when there's room.

`default/quickstart` is a free place to try things. It holds up to 10,000 documents and 100 MB (a write past that is refused with `too_large`), and its judging pauses for the rest of the [billing period](/pricing#billing-periods) at a small usage limit ([pricing](/pricing#quickstart)). For real data, write to a namespace of your own.

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```sh Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      pip install brussle
      ```

      ```sh TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      npm install brussle
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a client">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      import os
      from brussle import Client

      db = Client(api_key=os.environ["BRUSSLE_API_KEY"])
      ns = db.namespace("default/quickstart")
      ```

      ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      import { Client } from "brussle";

      const db = new Client({ apiKey: process.env.BRUSSLE_API_KEY! });
      const ns = db.namespace("default/quickstart");
      ```
    </CodeGroup>

    The namespace does not exist yet. It is created by its first write or judgment.
  </Step>

  <Step title="Define a judgment">
    Start from the ticket triage [starter](/guides/starter-judgments): a ready-made judgment that asks whether a ticket is urgent. Tell it where your documents keep the subject, the first message and the customer's plan:

    <CodeGroup>
      ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      created = ns.judgments.create(
          from_starter="ticket_triage.urgency",
          paths={"subject": "state.subject", "body": "state.body", "plan": "attributes.plan"},
          engine={"name": "jev", "version": "current"},
          freshness={"policy": "on_change"},
      )
      if "definition" in created:  # a starter that reads related documents returns its cost estimate first
          print(created["definition"])
      ```

      ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      const created = await ns.judgments.create({
        from_starter: "ticket_triage.urgency",
        paths: { subject: "state.subject", body: "state.body", plan: "attributes.plan" },
        engine: { name: "jev", version: "current" },
        freshness: { policy: "on_change" },
      });
      if ("definition" in created) console.log(created.definition); // a starter that reads related documents returns its cost estimate first
      ```
    </CodeGroup>

    This creates a `bool` judgment named `urgent`, with its question, criteria, [context recipe](/guides/context-recipes) and an `urgent` threshold at 0.8. `definition` in the response shows all of it. Add `dry_run` to see it and its cost first without creating anything, or write your own definition instead; see [judgments](/concepts/judgments).

    `on_change` computes the answer whenever a document changes, so every document has a current answer to filter or sort on. Jev `current` runs whichever Jev model the provider serves now; each answer records the epoch of model behaviour that produced it in `engine_version`, such as `current+2026-09-24.1`, and a new epoch starts only when we detect the model's behaviour change. See the [engines](/engines/index) page.
  </Step>

  <Step title="Write three documents">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      ns.write(
          upsert=[
              {"id": "t_1", "attributes": {"plan": "pro"}, "state": {"subject": "Cancel my account", "body": "Third outage this week. Talking to my lawyer."}},
              {"id": "t_2", "attributes": {"plan": "free"}, "state": {"subject": "Dark mode?", "body": "Is there a dark mode?"}},
              {"id": "t_3", "attributes": {"plan": "pro"}, "state": {"subject": "Invoice", "body": "The bot sent me the wrong invoice twice."}},
          ],
          wait_for=["urgent"],
      )
      ```

      ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      await ns.write({
        upsert: [
          { id: "t_1", attributes: { plan: "pro" }, state: { subject: "Cancel my account", body: "Third outage this week. Talking to my lawyer." } },
          { id: "t_2", attributes: { plan: "free" }, state: { subject: "Dark mode?", body: "Is there a dark mode?" } },
          { id: "t_3", attributes: { plan: "pro" }, state: { subject: "Invoice", body: "The bot sent me the wrong invoice twice." } },
        ],
        wait_for: ["urgent"],
      });
      ```
    </CodeGroup>

    The write is durable once it returns. `wait_for` also waits until the answers exist, which usually takes a few seconds. Without it, the write returns in a fraction of a second and the answers follow.
  </Step>

  <Step title="Query by the answer">
    <CodeGroup>
      ```python Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      page = ns.query(
          filters=("answers.urgent.thresholds.urgent", "Eq", True),
          rank_by=("answers.urgent.p", "desc"),
          include={"attributes": ["plan"], "answers": ["urgent"]},
      )
      for row in page["rows"]:
          print(row["id"], row["answers"]["urgent"])
      ```

      ```ts TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
      const { rows } = await ns.query({
        filters: ["answers.urgent.thresholds.urgent", "Eq", true],
        rank_by: ["answers.urgent.p", "desc"],
        include: { attributes: ["plan"], answers: ["urgent"] },
      });
      for (const row of rows) console.log(row.id, row.answers?.urgent);
      ```
    </CodeGroup>

    Each answer carries its probability `p`, the `urgent` threshold as a boolean, its freshness, and the revision, judgment version and engine version it was computed with.
  </Step>
</Steps>

## Next

* See the answers, their history and the exact text the engine saw in the dashboard at [https://app.brussle.com](https://app.brussle.com).
* Learn what the [freshness](/concepts/freshness) states mean.
* Cut cost with a tighter [context recipe](/guides/context-recipes).
* Set up a [staging environment](/guides/staging-environments) of your own, separate from `default/quickstart`.


## Related topics

- [Pricing](/pricing.md)
- [Import existing data](/guides/import-existing-data.md)
- [namespace.budget_paused](/api-reference/webhooks/namespacebudget_paused.md)
- [namespace.budget_resumed](/api-reference/webhooks/namespacebudget_resumed.md)
- [Staging and test environments](/guides/staging-environments.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.