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

# Guides

Six things people build with the Agent API. Each one is a complete working
program, not a sequence of fragments — copy it, run it, then change the parts
that are about your business rather than ours.

The [quickstart](/quickstart) gets you from a token to a completed turn.
These go further, and each leans on a different part of the platform, so
reading two of them is not reading the same thing twice.

| I want to…                                                         | Guide                                                                                |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Turn a pile of PDFs, contracts or reports into rows in my database | [Turn documents into structured JSON](/guides/extracting-structured-data)            |
| Hand work to an agent from my own API and collect it later         | [Put an agent behind your own API](/guides/an-agent-behind-your-api)                 |
| Make a person approve something before the agent does it           | [Require human approval before the agent acts](/guides/approvals-in-your-product)    |
| Show my users what the agent is doing, live                        | [Stream the agent's progress into your UI](/guides/showing-the-agents-work)          |
| Keep one job going across hours, pausing in between                | [Continue work across hours and rounds](/guides/work-that-spans-hours)               |
| Change model or vendor without touching my code                    | [Swap model providers without changing your code](/guides/switching-model-providers) |

Every script here is standard library only. No SDK to install, in any language.

## Before any of them

```bash theme={null}
export GOBARE_API=https://api.gobare.dev
export GOBARE_TOKEN=gbr_pat_…
```

Mint the token in the Console under **Settings › Developer access**, choosing
**Agent API · read/write**. The default **CLI import** type holds only the `cli`
scope and is refused by every `/v1` route.

Then connect a model — `POST /v1/model-credentials`, or the Console under
**Settings › LLM models**. Gobare is bring-your-own-key: the model bill is
yours, the computer is ours.

One call proves all three:

```bash theme={null}
curl -s $GOBARE_API/v1/model-credentials -H "Authorization: Bearer $GOBARE_TOKEN"
```

A list back means your token is valid, scoped, and has a model to run. The
`model` in it is what goes in `agent.model`.

## Four things that will save you an afternoon

These are not trivia. Each one is a mistake that costs hours because it
produces *plausible* behaviour rather than an error.

**Wait for artifacts, not for the turn.** Files the agent writes under
`/workspace/outputs` are published *after* the turn settles, so for a moment
after `status: "completed"` the artifact list is legitimately empty — and
indistinguishable from a turn that produced nothing. Poll the turn's
`artifacts` field until it leaves `pending`. With [webhooks](/webhooks)
you can ignore this: `turn.completed` is sent once publishing has finished.

**Subscribe before you send.** Open the event stream first, then post the
message. The other order loses the opening frames whenever the agent starts
quickly — which is to say intermittently, and never on your machine.

**Tell the agent not to ask questions**, if nothing in your product can answer
one. An agent that meets ambiguity parks on a `question` and waits. You *can*
answer it — `input.question_answer`, see [input.md](/input) — but an
unattended pipeline with nobody to ask is better off never reaching that state.
One line in `instructions` prevents it:

```
Never ask the user a clarifying question: if something is ambiguous,
state your assumption and continue.
```

**Two `429`s mean opposite things.** `rate_limit_exceeded` is worth retrying;
`project_limit_exceeded` means the organization is at its session ceiling and
retrying never clears it. Branch on `error.code`, never on the status alone.

## The reference

The guides show a shape; the reference pages have every field.

* [sessions.md](/sessions) — repositories, files, secrets, permissions
* [input.md](/input) — the four things you can send a session
* [events.md](/events) — the event vocabulary
* [errors.md](/errors) — every refusal, in one shape
* [limits.md](/limits) — every ceiling, with its number
* [troubleshooting.md](/troubleshooting) — arriving with a symptom instead of a question

[`run-session.ts`](/run-session) is a TypeScript client that handles the
first two afternoon-savers above, plus answering the agent's calls into your
code. It is the same file our own end-to-end tests run against, so it cannot
quietly stop working.