# curl examples -- the no-SDK path

Drive the Tetrate Agent Router (TARS) REST API with nothing but `curl` and
`jq`. This is the language-agnostic option: no SDK, no build step, just HTTP.
For typed clients (Go, Python, TypeScript), see the per-language SDK examples
under `examples/quickstart` (and, for TypeScript, `examples/api`).

These same scripts ship inside every SDK download tarball under
`examples/curl/`, so you always have the SDK-less option on hand.

## Prerequisites

- `curl` and `jq` on your PATH.
- A base URL and a credential, supplied via the environment:

  ```
  export AGENTROUTER_BASE_URL=https://api.tetrate.ai   # optional; defaults to prod
  export AGENTROUTER_API_KEY=<keyid>.<secret>          # an issued key OR a session token
  ```

The credential is sent as `Authorization: Bearer <token>`. It can be either:

- an **issued API key** (looks like `<keyid>.<secret>`), or
- a **session token** from an interactive login.

The key/session carries its own customer + project, so the smallest calls need
nothing else.

### How to get a credential

- **Issued key (recommended):** install the `tare` CLI, then

  ```
  tare api login            # opens a browser for OIDC sign-in
  tare api keys create      # prints a new key like <keyid>.<secret> -- copy it
  ```

- **Local dev stack:** mint a throwaway key + base URL from the
  seeded admin session (repo-only helper):

  ```
  eval "$(bash examples/quickstart-bootstrap.sh)"   # sets AGENTROUTER_API_KEY + BASE_URL
  ```

  The local stack serves `https://api.your.domain.tetrate.ai` with a self-signed
  certificate, so add `-k` by exporting `AGENTROUTER_CURL_INSECURE=1` (or point
  `CURL_CA_BUNDLE` at the dev CA).

## Scripts

### `quickstart.sh` -- one prompt, first catalog model

The smallest example: send a single prompt and print the completion. Mirrors
the per-language SDK quickstart.

```
export AGENTROUTER_API_KEY=<keyid>.<secret>   # from: tare api keys create
bash quickstart.sh
```

Lists the catalog and uses the first available model (the inference handler
requires a non-empty model). Pin a specific one with
`AGENTROUTER_QUICKSTART_MODEL=claude-haiku-4-5`.

### `walkthrough.sh` -- a guided tour of the REST surface

A read-along tour: each step echoes what it does, prints the `curl` command, and
pretty-prints the JSON response. It covers whoami, issuing a key, catalog reads,
BYOK register/list/revoke, clients, MCP catalog + profiles, insights logs +
stats, prompts (explicit provider/model and bare model), the session-default
prompt (no customer/project), and an RFC 7807 `application/problem+json` error
(a deliberately bad model, so you can see the machine-readable `reason`).

```
export AGENTROUTER_API_KEY=<keyid>.<secret>   # from: tare api keys create
bash walkthrough.sh
```

Project-scoped steps (BYOK, clients, MCP profiles, insights, explicit-scope
prompts) need a customer + project; set them to include those steps:

```
export AGENTROUTER_CUSTOMER_ID=acme
export AGENTROUTER_PROJECT_ID=default
```

Without them, the walkthrough runs the credential-derived default-tenant prompt
plus the ungated catalog reads, and tells you what it skipped.

## Environment variables

| Variable                        | Required | Default                  | Purpose                                            |
| ------------------------------- | -------- | ------------------------ | -------------------------------------------------- |
| `AGENTROUTER_API_KEY`           | yes      | --                       | Bearer credential (`<keyid>.<secret>` key or session token). |
| `AGENTROUTER_BASE_URL`          | no       | `https://api.tetrate.ai` | API base URL.                                      |
| `AGENTROUTER_CUSTOMER_ID`       | no       | --                       | Customer for project-scoped walkthrough steps.     |
| `AGENTROUTER_PROJECT_ID`        | no       | --                       | Project for project-scoped walkthrough steps.      |
| `AGENTROUTER_QUICKSTART_MODEL`  | no       | (empty = default)        | Pin the quickstart model.                          |
| `AGENTROUTER_WALKTHROUGH_MODEL` | no       | `openai/gpt-4o-mini`     | Model for the walkthrough's explicit-model demos.  |
| `AGENTROUTER_CURL_INSECURE`     | no       | `0`                      | Set to `1` to add `curl -k` (self-signed dev cert).|

No secrets are baked into the scripts -- credentials come from the environment
only.
