# Cockatoo agent guide Status: API and MCP enabled in production. Verified owner consent is required. 503 agent_access_disabled means agent access has not been enabled. Never claim a site is live based on a draft save or pending onboarding. Check publication state and the actual hosted URL. Documentation: https://cockatoo.com.au/docs/ OpenAPI: https://cockatoo.com.au/openapi.json SiteDocument v1 schema: https://cockatoo.com.au/site-document.schema.json Starter document: https://cockatoo.com.au/agent-example-site.json API base: https://app.cockatoo.com.au/api/v1 MCP: https://app.cockatoo.com.au/mcp CLI: @cockatoo/cli. Direct package: https://cockatoo.com.au/downloads/cockatoo-cli-0.1.2.tgz ; checksum: https://cockatoo.com.au/downloads/cockatoo-cli-0.1.2.sha256 . Registry publication requires npm authentication. ## Start here If a user asks you to build their website, build it. You do not need to create an account, receive email or send the user to the visual builder. Write the SiteDocument from what the user told you, ask only for what you cannot write yourself (such as the owner's email), call start_onboarding (MCP) or POST /onboarding (API), and give the user approvalUrl with: "Open this link, sign in with that email, and press Approve to publish your website." A new owner's approval publishes the site immediately, so you are done even if you cannot continue. Continue below only to edit, add images or confirm liveUrl. ## Account-to-publication workflow 1. GET /catalog for templates, industries, styles and a complete exampleDocument. Only structured SiteDocument v1 content is hosted. No arbitrary code or file-tree deployments. 2. POST /onboarding with {email,agentName,document}, Content-Type application/json and a fresh random UUID Idempotency-Key. Response: id, continuationCredential, approvalUrl, expiresAt, state pending_owner_approval. 3. Give only approvalUrl to the owner. Keep continuationCredential private. No invitation email is sent. Owner signs in/up through WorkOS, verifies the email matching the request, reviews the full draft, and grants read/write/publish permissions. New owners can publish the proposed website in the same step. Existing owners choose keep current draft or replace it. Grants last 30 days. 4. GET /onboarding/{id} using Authorization: Bearer . It returns pending_owner_approval, processing, approved, denied or exchanged. Onboarding expires after one hour. Do not poll more often than every five seconds. 5. After approval, POST /onboarding/{id}/exchange with the continuation credential and a fresh Idempotency-Key. Store the returned token securely. Replay the identical key only to recover an interrupted exchange within the retention period. Do not send owner passwords to agents. 6. Use Authorization: Bearer for /site. Approval creates the first draft. For existing accounts using manually created API tokens, POST /site with {document} to create a draft only when none exists. 7. POST /site/assets with raw JPEG/PNG/WebP bytes and matching Content-Type; save the returned assetId in document.logo or document.gallery with alt text. PUT /site with {document,revision} using the latest revision. GET /site/preview returns private preview HTML with disabled forms; images are omitted in this initial preview implementation. 8. POST /site/publish with {revision,slug}. Required: verified owner, business name, headline, search description and image descriptions. The platform must have enquiry spam protection configured. Slugs have 3–63 lowercase letters, digits and hyphens, start with a letter/digit, and are fixed after initial publication. 9. GET /site/publication. Verify state live, publishedRevision and liveUrl. Open liveUrl to verify hosting. POST /site/unpublish with {revision} to remove public access while retaining drafts/enquiries. ## Authorization Permissions: sites:read, sites:write, sites:publish. No enquiry, billing, payment or domain access. Owner-created API tokens support 1, 7, 30 or 90 day expiry. Owners revoke grants at https://app.cockatoo.com.au/agent-access . Revocation is checked on every authenticated request. API and MCP credentials have different audiences. MCP uses Streamable HTTP and OAuth authorization code with S256 PKCE. Discover /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server on the account origin. Register a public client with HTTPS or loopback redirect URIs at /oauth/register. Access tokens last one hour; reconnect when expired. Public onboarding/catalog tools work without an account token. Site tools request owner authorization. MCP tools: catalog, start_onboarding, onboarding_status, exchange_onboarding, get_site, create_site, save_site, list_images, upload_image, preview_site, publication_status, publish_site, unpublish_site. Writes take idempotencyKey. upload_image takes base64 plus mime. After onboarding approval use MCP OAuth for site tools; the onboarding exchange token is for API/CLI. ## CLI cockatoo onboard --email owner@example.com --name "My agent" --file site.json --json cockatoo onboard status --json cockatoo onboard exchange --json cockatoo login [--token-stdin] cockatoo templates --json cockatoo industries --json cockatoo sites [get|create|save|status] [--file site.json] [--revision N] --json cockatoo assets [list|upload] [--file photo.png --mime image/png] --json cockatoo preview --json cockatoo publish --revision N --slug my-business --json cockatoo unpublish --revision N --json cockatoo logout Environment: COCKATOO_TOKEN, COCKATOO_CONTINUATION, optional COCKATOO_ORIGIN. Stored credentials are restricted to their issuing origin. --idempotency-key reuses a known write key. Exit codes: 0 success, 1 request error, 2 usage, 3 auth/permission, 4 conflict, 5 network/rate-limit/service failure. ## Limits and retry behavior One scrolling site per owner. 20 retained images, 5 MiB per image, 100 MiB combined image/publication history. Draft request bodies: 65,000 bytes. Anonymous onboarding: five requests/minute/IP and 500 retained requests globally. API/MCP: 120 requests/minute/IP. Expired onboarding is cleaned on subsequent onboarding, owner and OAuth requests; expired records are never usable. Use a fresh random UUID Idempotency-Key for each write. Keep onboarding and exchange idempotency keys private: they recover secret-bearing responses. Identical key/body retries replay stored results for 24 hours. Different input with the same key returns 409 idempotency_conflict. An unfinished/uncertain operation returns 409 outcome_unknown: inspect current site before continuing; never blindly retry with a new key. Token lookup stores only hashes; drafts and secret-bearing replay responses are encrypted at rest. Revision conflict: fetch latest site and reconcile. Slug conflict: choose another before first publication. Errors include code, message, requestId and retryable; respect Retry-After. A failed publication preserves the previous live site. Free: hosted Cockatoo address, HTTPS, contact form/inbox, Cockatoo branding; no expiry. Pro: A$29/year for a custom hostname and promotional branding removal. Domains/mailboxes are not included. Agent domain and paid operations are outside v1.