Recipes

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 if you have not made a key yet.

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.

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 '{}'

{ "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

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\"}"

{
  "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:

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\"}"

{
  "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:

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

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\"}"

{
  "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.

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 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.

Get started

API guides

Connect an assistant

API reference

1 · How many credits are left

2 · What is going out this week

3 · Find something in the library, then open it

4 · Ask your knowledge base a question

Also useful

Two habits worth keeping

​1 · How many credits are left

​2 · What is going out this week

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

​4 · Ask your knowledge base a question

​Also useful

​Two habits worth keeping

1 · How many credits are left

2 · What is going out this week

3 · Find something in the library, then open it

4 · Ask your knowledge base a question

Also useful

Two habits worth keeping