Developer documentation

From an agent to a live business website

Prepare a structured one-page website, get the owner’s verified permission, and publish it with hosting, HTTPS and a built-in contact form. API, MCP and CLI use the same site permissions and publishing service.

Rollout status: Agent endpoints are gated during the pilot. A 503 agent_access_disabled response means the environment has not been enabled. These docs describe the implementation; production acceptance and npm publication are release gates.

API quickstart

Download the example document, edit the business content, and validate it against the document schema. GET /api/v1/catalog provides current templates, industries, styles and a complete starter document.

export COCKATOO_ORIGIN=https://app.cockatoo.com.au
curl -fsS "$COCKATOO_ORIGIN/api/v1/catalog" > catalog.json
curl -fsS https://cockatoo.com.au/agent-example-site.json > site.json
# Edit site.json, then build the onboarding request:
jq --arg email [email protected] --arg agentName "My website agent"   '{email:$email,agentName:$agentName,document:.}' site.json > onboarding.json
curl -fsS "$COCKATOO_ORIGIN/api/v1/onboarding"   -H 'Content-Type: application/json'   -H "Idempotency-Key: $(uuidgen)" --data-binary @onboarding.json

Keep continuationCredential private. Give only approvalUrl to the owner. The owner signs up or signs in, verifies their email, reviews the draft and grants site access. For an existing website, the owner chooses whether to keep or replace the draft. No invitation email is sent automatically.

export ONBOARDING_ID='the-returned-id'
export COCKATOO_CONTINUATION='the-private-continuation-credential'
curl -fsS "$COCKATOO_ORIGIN/api/v1/onboarding/$ONBOARDING_ID"   -H "Authorization: Bearer $COCKATOO_CONTINUATION"
# After state becomes approved, exchange once; save the response securely.
curl -fsS -X POST "$COCKATOO_ORIGIN/api/v1/onboarding/$ONBOARDING_ID/exchange"   -H "Authorization: Bearer $COCKATOO_CONTINUATION"   -H "Idempotency-Key: $(uuidgen)"
export COCKATOO_TOKEN='the-returned-api-token'
curl -fsS "$COCKATOO_ORIGIN/api/v1/site"   -H "Authorization: Bearer $COCKATOO_TOKEN"

Approval applies the proposed draft when the owner has no site. Existing owners can instead create a token in Agent access, then call POST /site with {"document":{...}} if they do not yet have a website.

# Upload an image and save its returned assetId in logo or gallery, with alt text.
curl -fsS "$COCKATOO_ORIGIN/api/v1/site/assets"   -H "Authorization: Bearer $COCKATOO_TOKEN" -H 'Content-Type: image/png'   -H "Idempotency-Key: $(uuidgen)" --data-binary @photo.png
# Read the latest revision. Put the edited document and revision in save.json.
curl -fsS -X PUT "$COCKATOO_ORIGIN/api/v1/site"   -H "Authorization: Bearer $COCKATOO_TOKEN" -H 'Content-Type: application/json'   -H "Idempotency-Key: $(uuidgen)" --data-binary @save.json
curl -fsS "$COCKATOO_ORIGIN/api/v1/site/preview"   -H "Authorization: Bearer $COCKATOO_TOKEN" > preview.json
# Replace 2 with the latest revision returned by the service.
curl -fsS "$COCKATOO_ORIGIN/api/v1/site/publish"   -H "Authorization: Bearer $COCKATOO_TOKEN" -H 'Content-Type: application/json'   -H "Idempotency-Key: $(uuidgen)" --data '{"revision":2,"slug":"my-business"}'
curl -fsS "$COCKATOO_ORIGIN/api/v1/site/publication"   -H "Authorization: Bearer $COCKATOO_TOKEN"

Check state: live, the published revision and liveUrl, then open the URL. Draft saves do not publish. Unpublish with POST /site/unpublish and the current revision.

Connect through MCP

Remote endpoint: https://app.cockatoo.com.au/mcp. Add this URL in a client that supports Streamable HTTP and OAuth with PKCE. Discovery starts at /.well-known/oauth-protected-resource/mcp. Clients register HTTPS or loopback redirect URIs through the advertised registration endpoint. Tokens are bound to the MCP resource; API tokens cannot be reused as MCP tokens.

Public tools: catalog, start_onboarding, onboarding_status, exchange_onboarding. Website tools request owner authorization: get_site, create_site, save_site, list_images, upload_image, preview_site, publication_status, publish_site, unpublish_site.

Start with catalog, prepare the document, then call start_onboarding. Give the owner the approval URL. After approval, connect their account through OAuth to operate the site in MCP. The optional exchange returns an API token for API or CLI use. Supply a fresh random idempotencyKey for each write. Image uploads take base64 plus a MIME type. OAuth access tokens expire after one hour; reconnect to renew authorization.

Use the CLI

The package is @cockatoo/cli. A versioned CLI package and SHA-256 checksum are available directly from Cockatoo. Install the download with npm install -g https://cockatoo.com.au/downloads/cockatoo-cli-0.1.1.tgz. Until npm publication, you can also run node packages/cli/bin/cockatoo.mjs from the source checkout. After publication:

npm install -g @cockatoo/cli
cockatoo templates --json
cockatoo industries --json
cockatoo onboard --email [email protected] --name "My agent" --file site.json --json
# Share the returned approvalUrl; set COCKATOO_CONTINUATION privately.
cockatoo onboard status "$ONBOARDING_ID" --json
cockatoo onboard exchange "$ONBOARDING_ID" --json
# Set COCKATOO_TOKEN privately from the exchange response.
cockatoo sites get --json
cockatoo assets upload --file photo.png --mime image/png --json
# Put the assetId and alt text in site.json; use the latest returned revision.
cockatoo sites save --file site.json --revision 1 --json
cockatoo preview --json
cockatoo publish --revision 2 --slug my-business --json
cockatoo sites status --json

cockatoo login provides the account token page. Pipe a token to cockatoo login --token-stdin to store it locally with restricted file permissions, or use COCKATOO_TOKEN without local persistence. logout removes the local credential; revoke the grant in Cockatoo to disable all copies. Do not commit tokens, continuation credentials or exchange output.

Exit codes: 0 success, 1 request failure, 2 usage error, 3 authentication or permission error, 4 conflict, 5 network/rate-limit/service failure. --json produces structured stdout; diagnostics go to stderr. Failed writes report their idempotency key.

API reference

This endpoint list is generated from the OpenAPI 3.1 contract. Base URL: https://app.cockatoo.com.au/api/v1.

Method	Path	Operation
`GET`	`/token`	Inspect the current API grant without requiring site-read permission
`GET`	`/catalog`	List templates, industries, style presets and an example document
`POST`	`/onboarding`	Prepare a private owner-approved account and website handoff
`GET`	`/onboarding/{id}`	Check pending_owner_approval, approved, denied, processing or exchanged
`POST`	`/onboarding/{id}/exchange`	Exchange approved onboarding for an API token
`GET`	`/site`	Read the owner’s site
`POST`	`/site`	Create a structured draft
`PUT`	`/site`	Replace the draft with revision checking
`GET`	`/site/assets`	List the site’s retained uploaded images
`POST`	`/site/assets`	Upload up to 5 MiB of JPEG, PNG or WebP
`GET`	`/site/preview`	Return private draft preview HTML; forms disabled
`GET`	`/site/publication`	Read live state and published revision
`POST`	`/site/publish`	Publish a saved revision
`POST`	`/site/unpublish`	Remove the public publication while retaining the draft

Permissions, limits and safe retries

sites:read: site, images, preview and publication state. sites:write: create/save drafts and upload images. sites:publish: publish and unpublish.
No access to customer enquiries, payments, billing settings or domains. Paid upgrades and domain setup remain in the owner dashboard.
Onboarding expires after one hour. Agent onboarding grants last 30 days. Owner-created tokens can expire after 1, 7, 30 or 90 days. Revocation is checked on every authenticated request.
One site and one scrolling page per owner. Up to 20 retained images; 5 MiB per image; 100 MiB total including publication history. Uploaded files are JPEG, PNG or WebP. No customer HTML, JavaScript or server code.
Draft requests are limited to 65,000 bytes. Anonymous onboarding is capped at five requests per minute per IP and 500 retained requests globally. Other API and MCP requests are capped at 120 per minute per IP.
Every write needs a random Idempotency-Key. Treat onboarding and exchange keys as private credentials because they recover secret-bearing responses. Identical retries replay the encrypted stored response for 24 hours. Never reuse a key for different input. After outcome_unknown, read current state before deciding what to do next.
After a revision conflict, reload the site and reconcile changes. After a slug conflict, choose another slug. A published slug is fixed. Do not blindly retry with a new key.
Errors include a code, message, request ID and retry guidance. Honor Retry-After on rate limits and service failures. Contact support with the request ID.
Preview returns private HTML, has no live form, and currently omits uploaded images. Render it in a sandboxed iframe. Publication checks the owner’s verified identity and the platform’s spam-protection configuration.

Hosting and pricing

Free includes one hosted site, HTTPS, a Cockatoo address, contact form and owner enquiry inbox, with Cockatoo branding. Pro is A$29/year for one custom hostname and branding removal. Domain registration and mailboxes are separate. See pricing.