Recipes

These examples show complete requests and the identifiers to carry from one call to the next. Tool and feature exposure still follows the environment you are calling; a documented request can return a typed rollout refusal before that surface is enabled there. 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"

For an unattended project, Data or Pages setup, a key narrowed to one workspace keeps the workspace argument off every call. An account-wide key works everywhere too — including the Pages import, asset and preview-link endpoints — as long as you pass workspace when your holder reaches more than one.

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.

5 · Create a project and move a board into it

Read the workspace tree before using any board id. kind and root_board_id are optional; use kind: "site" to narrow the result to Pages boards and the projects that contain them. Creating or moving a project requires an operator role.

curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/board.tree" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"kind":"site"}'

{
  "ok": true,
  "roots": [
    {
      "board_id": "<site-board-id>",
      "name": "Imported site",
      "kind": "site",
      "parent_board_id": null,
      "updated_at": "<ISO-8601 timestamp>",
      "referenced": false,
      "children": []
    }
  ],
  "truncated": false,
  "answer_note": "Use only board ids returned by this tree for later board operations."
}

Create a named project with a stable idempotency_key. Reuse that key only when retrying this same create. parent_board_id is optional and creates a nested project when present.

curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/board.create_folder" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"Deconstructed","idempotency_key":"project:deconstructed:v1"}'

{
  "ok": true,
  "board_id": "<project-board-id>",
  "name": "Deconstructed",
  "parent_board_id": null,
  "answer_note": "The project is ready in the resolved workspace."
}

Move a board returned by board.tree into that project. Omit from_parent_board_id when the board has one current location; the service resolves it. Send to_parent_board_id: null to move a board back to the root.

curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/board.move" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"board_id":"<site-board-id>","to_parent_board_id":"<project-board-id>"}'

If a board appears in several places, board.move refuses with boards_tree.parent_ambiguous. Read the tree again and retry with the exact from_parent_board_id it should leave.

6 · Create and maintain a Data-backed CMS

Create a typed table on the project board. name, columns, and idempotency_key are required. board_id is optional; omitting it creates a board for the table. Column keys use lower snake case, start with a letter, and are at most 64 characters. Supported types are text, number, boolean, date, email, phone, url, and json. All six Data actions require an operator role.

curl --request POST \
  --url "https://app.goosybear.ai/api/v1/tools/data.create_table" \
  --header "Authorization: Bearer $GOOSY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name":"Episodes",
    "board_id":"<project-board-id>",
    "idempotency_key":"data:episodes:v1",
    "columns":[
      {"key":"title","label":"Title","type":"text","required":true},
      {"key":"slug","label":"Slug","type":"text","required":true},
      {"key":"published_at","label":"Published at","type":"date"},
      {"key":"cover_url","label":"Cover URL","type":"url"}
    ]
  }'

{
  "ok": true,
  "table_id": "<table-id>",
  "name": "Episodes",
  "board_id": "<project-board-id>",
  "board_item_id": "<board-item-id>",
  "column_count": 4
}

The six Data API actions accept these JSON payloads. Each can also take the adapter-owned optional workspace handle when the key is not pinned.

Tool	JSON payload
`data.create_table`	`{"name":"Episodes","columns":[{"key":"title","label":"Title","type":"text"}],"board_id":"<board-id>","idempotency_key":"data:episodes:v1"}`
`data.describe`	`{"table_id":"<table-id>"}` or `{"board_id":"<board-id>"}`; both fields are optional
`data.query`	`{"table_id":"<table-id>","has_value_in":["slug"],"missing_value_in":["cover_url"],"equals":{"slug":"episode-1"},"order_by":"published_at","descending":true,"limit":25,"cursor":"<cursor>"}`
`data.append`	`{"table_id":"<table-id>","values":{"title":"Episode 1","slug":"episode-1"},"idempotency_key":"episode:1:v1"}`
`data.update_cell`	`{"table_id":"<table-id>","row_id":"<row-id>","column_key":"cover_url","value":"https://example.com/cover.webp"}`
`data.set_published_columns`	`{"table_id":"<table-id>","published_columns":["title","slug"]}`

data.describe returns table definitions, counts, row limits, sources, and the current published_columns. data.query returns count_line, total, returned, rows shaped as { "row_id", "values", "source" }, and next_cursor when another page exists. Its limit is 1 through 100. Equality filters take string values and can name only real columns. data.append validates and coerces the whole row against the table schema; unknown keys are refused. Reuse its idempotency_key only for the same append. data.update_cell accepts a JSON string, number, boolean, null, array, or object, then revalidates the complete row. data.set_published_columns replaces the entire public list; an empty array publishes no columns. It decides what a public Page may read, so it answers in two calls: without confirmation_id it proposes, returning state: "confirmation_required", a confirmation_id and a request_summary, and changes nothing; send the same payload again with that confirmation_id, on a member’s own API key, to apply it. A service account’s key can propose but never confirm, and a table whose columns or public list changed in between answers proposal_changed — propose again. After the Page itself is live, its server or Worker can read only those public columns. This read has no bearer credential and never permits writes:

GET https://app.goosybear.ai/api/pages/<site-id>/data/<table-id>?limit=25&eqColumn=slug&eqValue=episode-1

{
  "ok": true,
  "data": {
    "table": {
      "id": "<table-id>",
      "name": "Episodes",
      "columns": [
        {"key":"title","label":"Title","type":"text"},
        {"key":"slug","label":"Slug","type":"text"}
      ]
    },
    "rows": [
      {"id":"<row-id>","values":{"title":"Episode 1","slug":"episode-1"}}
    ],
    "nextCursor": null
  }
}

The public read accepts limit from 1 through 1,000, optional cursor, and one equality filter expressed by the pair eqColumn and eqValue. Supplying only half of that pair is refused.

7 · Finish a Page setup without opening the app

Use the same workspace-pinned key for the whole sequence:

Create the project with board.create_folder.
Create and populate the CMS table with data.create_table and data.append, then set its explicit public projection with data.set_published_columns (propose, then confirm on a member’s own key).
Send the site ZIP to POST /api/pages/ingest. Supplying an existing siteId replaces that same site’s bundle or managed source; a source upload returns buildRunId.
Follow a source build with page.build_status, passing that buildRunId as build_run_id, until it returns succeeded and a revision.
Upload PNG, JPEG, WEBP, or GIF references with POST /api/pages/{siteId}/assets. Each upload is attached to that site’s board automatically.
Read board.tree with kind: "site", then use board.move to place the site’s board in the project.
Create a review link with POST /api/pages/{siteId}/preview-links.
Call page.publish once to obtain the exact-revision confirmation. Show the returned site and revision to the approver, then call it again with the confirmation_id after approval.

The Pages API guide gives the exact multipart fields, status responses, preview-token handling, and two-call publication bodies; the deploy contract and site and project databases cover what a bundle declares. The complete run is below. Hosted Pages managed AI tools are still under construction and are not part of this setup flow.

The whole Pages lifecycle, from a clean directory

This is a real run, recorded verbatim on 2026-09-12 against the Dev environment, from an empty directory with only an API key and these pages — no repository, no Cloudflare account, no platform credential. The key used was account-wide (not narrowed to a workspace), which is why workspace appears on every call. The two multipart steps were re-run after workspace moved to the query string, so the commands below are the ones that were executed. Responses are trimmed to the fields the next step needs; identifiers are the real ones from the run.

0 · What was in the directory

Two files, written by hand:

my-site/
  index.html
  pages.deploy.json

{
  "routes": [],
  "bindings": { "projectDatabase": "none", "secrets": [] },
  "limits": { "cpuMs": 10000, "subRequests": 20 }
}

cd my-site && zip -q -r ../site.zip .
export API="https://app.goosybear.ai"
export GOOSY_API_KEY="…"
export GOOSY_WORKSPACE="aictw-main"

1 · Which workspaces can this key reach?

The fastest way to find out is to name one that does not exist. The refusal lists the real ones.

curl -sX POST "$API/api/v1/tools/page.read" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d '{"site_id":"…","workspace":"not-a-real-workspace"}'

{
  "ok": false,
  "code": "workspace_unreachable",
  "message": "\"not-a-real-workspace\" is not a workspace this key reaches in AI Code That Works. Pass one of the workspaces listed below.",
  "workspaces": ["aictw-main", "aictw-secondary", "northwind-coffee", "revastack", "…"]
}

Both workspace refusals answer HTTP 403, never a 5xx — the request is fine and so is your key; you only have to say where. On the import and asset endpoints, whose envelope has no workspaces array, the slugs are appended to error.message instead.

2 · Import

workspace is a query parameter on this endpoint, not a form field — the body is your archive, and reading a field out of it would mean decoding up to 40 MB before your key was checked.

curl -sX POST "$API/api/pages/ingest?workspace=$GOOSY_WORKSPACE" \
  -H "Authorization: Bearer $GOOSY_API_KEY" \
  -F "file=@../site.zip" -F "name=External-operator acceptance run"

{
  "ok": true,
  "data": {
    "siteId": "cff400bb-077e-41cc-8430-49938683d94d",
    "kind": "prebuilt",
    "revision": "r768c19ee372d5d11",
    "objectCount": 2,
    "deploySource": "declared",
    "report": { "status": "staged" },
    "findings": ["…6 SEO/AEO findings — none blocking…"]
  }
}

deploySource: "declared" means our own pages.deploy.json was used. Omitting the file entirely returns "synthesized" and the manifest we wrote.

export SITE_ID="cff400bb-077e-41cc-8430-49938683d94d"

3 · Attach an image, and list what is attached

curl -sX POST "$API/api/pages/$SITE_ID/assets?workspace=$GOOSY_WORKSPACE" \
  -H "Authorization: Bearer $GOOSY_API_KEY" \
  -F "file=@./cover.png;type=image/png"

{ "ok": true, "data": { "boardItemId": "cf39f6d0-…", "storageObjectId": "58aba0a0-…", "displayName": "cover.png" } }

curl -sX POST "$API/api/v1/tools/page.assets" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"site_id\":\"$SITE_ID\",\"workspace\":\"$GOOSY_WORKSPACE\"}"

{
  "ok": true,
  "assets": [
    { "board_item_id": "cf39f6d0-…", "storage_object_id": "58aba0a0-…",
      "display_name": "cover.png", "mime_type": "image/png", "byte_size": 8,
      "uploaded_at": "2026-09-13T02:57:26Z" }
  ]
}

4 · Look at it

curl -sX POST "$API/api/pages/$SITE_ID/preview-links" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"ttlMinutes\":60,\"workspace\":\"$GOOSY_WORKSPACE\"}"

{
  "ok": true,
  "data": {
    "revision": "r768c19ee372d5d11",
    "url": "https://preview.…/__preview/<token>/",
    "expiresAt": "2026-09-13T03:57:51Z"
  }
}

5 · Publish, in two calls

curl -sX POST "$API/api/v1/tools/page.publish" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"site_id\":\"$SITE_ID\",\"workspace\":\"$GOOSY_WORKSPACE\"}"

{
  "ok": true, "state": "confirmation_required",
  "revision": "r768c19ee372d5d11",
  "confirmation_id": "6674dad7-e96b-4a50-b443-5871e660106a",
  "expires_in_seconds": 1800
}

Show that to whoever is approving, then repeat the call with the confirmation_id:

{
  "ok": true, "state": "published",
  "revision": "r768c19ee372d5d11",
  "hostname": "external-operator-acceptance-run.goosy.marketing",
  "url": "https://external-operator-acceptance-run.goosy.marketing",
  "shared_dev_host": false
}

6 · Where does it answer?

curl -sX POST "$API/api/v1/tools/page.domains" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"site_id\":\"$SITE_ID\",\"workspace\":\"$GOOSY_WORKSPACE\"}"

{
  "ok": true,
  "domains": [
    {
      "domain_id": "957cb3f9-…",
      "hostname": "external-operator-acceptance-run.goosy.marketing",
      "kind": "platform_subdomain",
      "state": "active",
      "steps": [],
      "records": []
    }
  ]
}

The free platform address is always active with no steps and no records — it is ours end to end. A domain you own is the one with a steps list to watch; connecting one returns the records to add:

{ "ok": false, "code": "pages.domain_platform_apex",
  "message": "That address belongs to the platform. Your site already has its free platform address — connect a domain you own instead." }

(That is what page.domain_connect answers if you try to claim one of ours.) A real connect returns the records to add, routing first — that CNAME is the one that makes the hostname resolve, and the certificate records alone are not enough. Shown here as an illustration, not a recording: this run drove only the refusal paths above, because a success would claim a real hostname.

{
  "ok": true,
  "domain": { "hostname": "offers.example.com", "kind": "custom", "state": "waiting_dns" },
  "records": [
    { "type": "CNAME", "name": "offers", "value": "<the platform target>", "purpose": "routing" },
    { "type": "CNAME", "name": "_acme-challenge.offers", "value": "…", "purpose": "certificate" }
  ]
}

7 · Ship a second revision, then put the first one back

Re-import onto the same siteId, publish it the same two-call way, and the site now has two builds:

curl -sX POST "$API/api/v1/tools/page.revisions" -H "Authorization: Bearer $GOOSY_API_KEY" \
  -H "Content-Type: application/json" -d "{\"site_id\":\"$SITE_ID\",\"workspace\":\"$GOOSY_WORKSPACE\"}"

{
  "ok": true,
  "published_revision": "r9fd1c9f36d8719ae",
  "revisions": [
    { "revision": "r9fd1c9f36d8719ae", "origin": "ingest", "published": true,  "has_functions": false },
    { "revision": "r768c19ee372d5d11", "origin": "ingest", "published": false, "has_functions": false }
  ]
}

Rolling back takes the same two calls as publishing, and the first one tells you both ends of the swap:

{
  "ok": true, "state": "confirmation_required",
  "revision": "r768c19ee372d5d11",
  "previous_revision": "r9fd1c9f36d8719ae",
  "confirmation_id": "a74728ce-…", "expires_in_seconds": 1800
}

The confirmation is bound to both the site and the revision. Spending it on a different one is refused:

{ "ok": false, "code": "confirmation_invalid",
  "message": "That confirmation is missing, expired, already used, or belongs to a different rollback." }

Confirming it puts the earlier build back on the live address, and page.revisions shows the flag has moved:

{ "published_revision": "r768c19ee372d5d11",
  "revisions": [{ "revision": "r9fd1c9f36d8719ae", "published": false },
                { "revision": "r768c19ee372d5d11", "published": true }] }

The same surface over MCP

Every tool above answers identically over the MCP endpoint — same names, same arguments, same envelope. A tools/list on POST /api/mcp/mcp with the same bearer key returned 41 tools, ending:

… page.publish · page.read_lead · page.revisions · page.rollback · page.assets ·
page.domains · page.domain_connect · automations.create_board …

and tools/call on page.revisions returned the same body the REST facade did. That is not a coincidence to re-check per tool: both transports run one dispatch, and a test walks the whole advertised list over both and deep-compares.

Two refusals worth wiring for

`code`	What it means	What to do
`workspace_ambiguous`	Your key reaches more than one workspace and the call named none	Pass `workspace`. The answer lists the slugs.
`pages.revision_already_published`	You asked to roll back to the build already live	Nothing to do — it is already serving.

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

5 · Create a project and move a board into it

6 · Create and maintain a Data-backed CMS

7 · Finish a Page setup without opening the app

The whole Pages lifecycle, from a clean directory

0 · What was in the directory

1 · Which workspaces can this key reach?

2 · Import

3 · Attach an image, and list what is attached

4 · Look at it

5 · Publish, in two calls

6 · Where does it answer?

7 · Ship a second revision, then put the first one back

The same surface over MCP

Two refusals worth wiring for

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

​5 · Create a project and move a board into it

​6 · Create and maintain a Data-backed CMS

​7 · Finish a Page setup without opening the app

​The whole Pages lifecycle, from a clean directory

​0 · What was in the directory

​1 · Which workspaces can this key reach?

​2 · Import

​3 · Attach an image, and list what is attached

​4 · Look at it

​5 · Publish, in two calls

​6 · Where does it answer?

​7 · Ship a second revision, then put the first one back

​The same surface over MCP

​Two refusals worth wiring for

​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

5 · Create a project and move a board into it

6 · Create and maintain a Data-backed CMS

7 · Finish a Page setup without opening the app

The whole Pages lifecycle, from a clean directory

0 · What was in the directory

1 · Which workspaces can this key reach?

2 · Import

3 · Attach an image, and list what is attached

4 · Look at it

5 · Publish, in two calls

6 · Where does it answer?

7 · Ship a second revision, then put the first one back

The same surface over MCP

Two refusals worth wiring for

Also useful

Two habits worth keeping