Skip to content
Context docs

Quickstart

Create a key, make your first HTTP request and run your first CLI command.

This quickstart takes about five minutes. You create a task API key, list your datasets over HTTP, then install the CLI and do the same from the command line.

You need Evals turned on for your deployment, and Evals access in the app. Organization owners and admins have access by default.

  1. Create a task API key

    In the app, open Settings > API > Task keys and choose New key. Give it a name. New keys start with most capabilities checked; for this read-only key, clear everything except Read evals. Then choose Create key. Copy the key now: it is shown only once.

    Store it in an environment variable, never in your code or in a repository:

    Terminal window
    export CONTEXT_API_KEY="<task-api-key>"

  2. Set your deployment's address

    Your deployment is the Context address your organization signs in to. Set it without a trailing slash:

    Terminal window
    export CONTEXT_APP_ORIGIN="https://<your-deployment>"

  3. Find your workspace ID

    Datasets and evaluations belong to a workspace. In the app, open the workspace’s menu, choose Workspace settings, and copy the Workspace ID field on the General tab:

    Terminal window
    export WORKSPACE_ID="<workspace-id>"

  4. List your datasets over HTTP

    cURL
    curl -sS --fail-with-body --get "$CONTEXT_APP_ORIGIN/api/v1/evals/datasets" \
      -H "Authorization: Bearer $CONTEXT_API_KEY" \
      --data-urlencode 'workspaceScope={"kind":"one","workspaceId":"'"$WORKSPACE_ID"'"}'
    Python
    import json
    import os
    

    import requests
    

    origin = os.environ["CONTEXT_APP_ORIGIN"]
    api_key = os.environ["CONTEXT_API_KEY"]
    scope = {"kind": "one", "workspaceId": os.environ["WORKSPACE_ID"]}
    

    resp = requests.get(
        f"{origin}/api/v1/evals/datasets",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"workspaceScope": json.dumps(scope)},
        timeout=60,
    )
    resp.raise_for_status()
    for dataset in resp.json():
        print(dataset["id"], dataset["name"])
    TypeScript
    function env(name: string): string {
      const value = process.env[name]
      if (!value) throw new Error(`Set ${name} first`)
      return value
    }
    

    const url = new URL("/api/v1/evals/datasets", env("CONTEXT_APP_ORIGIN"))
    url.searchParams.set("workspaceScope", JSON.stringify({ kind: "one", workspaceId: env("WORKSPACE_ID") }))
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${env("CONTEXT_API_KEY")}` },
    })
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
    const datasets = (await res.json()) as Array<{ id: string; name: string }>
    for (const dataset of datasets) console.log(dataset.id, dataset.name)

    The TypeScript example uses top-level await, so run it as an ES module (a .mts file, or a package with "type": "module").

    workspaceScope is JSON in one query value; let your HTTP library URL-encode it. Without it, an organization owner or admin gets datasets from every workspace. If your Evals access covers exactly one workspace, you get that one; otherwise the server answers 403 and asks you to name a workspace.

    A 401 means the key is missing or isn’t a task API key. A 403 means the key lacks evals:read, you don’t have Evals access, the key is limited to specific agents, or you didn’t name a workspace. The body’s error says which, and only the missing-capability 403 carries a code; see Errors.

  5. Install the CLI

    In the app, open Settings > Terminal. It shows the install command for your operating system, built from your deployment’s address. On macOS and Linux it has this form:

    Terminal window
    curl -fsSL "$CONTEXT_APP_ORIGIN/install.sh" | bash

    This installs the Context command-line tools, including the context command these pages use. Windows users copy the command that Settings > Terminal shows for Windows. The CLI’s help and error messages still write context-cli; type context instead.

  6. Set your organization ID

    The CLI also needs your organization ID. Copy it from the Organization ID field in your organization’s Settings > General:

    Terminal window
    export CONTEXT_ORG_ID="<org-id>"

  7. List your datasets from the CLI

    Terminal window
    context evals datasets list --workspace "$WORKSPACE_ID"

    The command prints one JSON document: a page with items and nextCursor. The CLI’s list commands page their results, while the HTTP list of datasets returns a plain array. Without --workspace, an organization owner or admin gets every workspace, and anyone whose Evals access covers exactly one workspace gets that one; anyone else gets exit code 2 and is asked to name one. Organization owners and admins can also pass --workspace all.

Next steps