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

# Recipes

> Four end-to-end calls you can run today: the credit balance, this week's grid, the library, and a question of your knowledge base.

Four calls that do real work. Each one is complete — paste it, and it runs.

They assume your key is in an environment variable and that you have picked a
workspace, either by setting a default or by passing `workspace` as shown. See
[Quickstart](/quickstart) if you have not made a key yet.

```bash theme={null}
export GOOSY_API_KEY="your-key"
export GOOSY_WORKSPACE="your-workspace"
```

## 1 · How many credits are left

The one call that takes no workspace — credits belong to the account, not to a
single workspace.

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/credits.balance" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

```json theme={null}
{ "ok": true, "balance": 1250 }
```

Worth running on a schedule if you have automation that spends — a job that
stops for want of credits is easier to prevent than to notice.

## 2 · What is going out this week

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/schedule.read" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"workspace\": \"$GOOSY_WORKSPACE\"}"
```

```json theme={null}
{
  "ok": true,
  "week_start": "2026-08-24",
  "days": ["2026-08-24", "2026-08-25", "2026-08-26", "2026-08-27", "2026-08-28", "2026-08-29", "2026-08-30"],
  "meta_line": "0 pieces this week",
  "rows": [],
  "pieces": [],
  "workspace": "acme-main",
  "working_in": { "label": "working in: Acme Main", "note": "this call only" }
}
```

`meta_line` is the same sentence the schedule board shows you, so it is the
right thing to put in a status message. To see where a specific piece has got
to, `content.status` gives you counts by state plus the pieces behind them.

## 3 · Find something in the library, then open it

Two calls, because searching and fetching are different jobs. Search first:

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/library.search" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"launch graphic\", \"workspace\": \"$GOOSY_WORKSPACE\"}"
```

```json theme={null}
{
  "ok": true,
  "total": 17,
  "truncated": false,
  "items": [
    {
      "kind": "image_generation",
      "id": "50874eb8-95a0-4a1b-adab-bf4f7e5956de",
      "roll": "images",
      "title": "A digital announcement graphic for a new developer tool launch…",
      "pinned": true,
      "source_board_name": "Capstone"
    }
  ]
}
```

Then fetch one in full, using **both** the `kind` and the `id` from the search
result — an id alone is not enough, because different kinds of thing can share
one:

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/library.get" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"kind\": \"image_generation\", \"id\": \"50874eb8-95a0-4a1b-adab-bf4f7e5956de\", \"workspace\": \"$GOOSY_WORKSPACE\"}"
```

An empty `query` returns the most recent items, which is a cheap way to see what
a workspace has.

## 4 · Ask your knowledge base a question

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/knowledge.search" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"how do we talk about pricing\", \"workspace\": \"$GOOSY_WORKSPACE\"}"
```

```json theme={null}
{
  "ok": true,
  "query": "how do we talk about pricing",
  "hits": [
    { "source": "brand_guide", "excerpt": "…", "relevance": 0.48 }
  ]
}
```

Ask it the way you would ask a person — it matches on meaning, not on keywords,
so a whole question works better than two words. `relevance` lets you drop weak
hits before you show them to anyone.

## Also useful

**`connections.status`** answers which providers a workspace has connected and
which need attention, split into `connected`, `needs_attention` and `available`.
It is the call to make before an automation tries to publish somewhere, so a
failure becomes a warning you saw coming.

```bash theme={null}
curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/connections.status" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"workspace\": \"$GOOSY_WORKSPACE\"}"
```

## Two habits worth keeping

* **Branch on `ok`, never on the status code.** An action that declines still
  answers `200`. [Errors and refusals](/api/errors-and-refusals) has the full
  list.
* **Log `working_in` alongside the result.** It is the fastest way to catch an
  integration quietly working in the wrong workspace.

Every action, with its arguments and its answers, is in the [API
reference](/api-reference/overview).