Quickstart

1. Get An API Key

Use one of the supported API-key sources:

• User-generated keys from willaOS Settings → API Keys. These inherit role, client, and project scope.
• Provisioned integration keys in environment variables such as API_KEY_ADMIN, API_KEY_KICKOFF, API_KEY_SHOPIFY_APP, API_KEY_QA_EXTENSION, and API_KEY_FIGMA_SECTION_LEDGER.

Keys are bearer tokens. Never put them in query strings, browser-visible client components, screenshots, or logs.

2. Call REST

curl https://os.willacreative.dev/api/clients \
  -H "Authorization: Bearer $WILLA_API_KEY" \
  -H "Accept: application/json"

Successful REST responses use a JSON envelope:

{
  "data": [],
  "request_id": "req_..."
}

Mutable resources that expose a version field use optimistic concurrency. Send the current version in X-Version:

curl -X PATCH https://os.willacreative.dev/api/projects/prj_123 \
  -H "Authorization: Bearer $WILLA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Version: 7" \
  -d '{"phase":"build"}'

3. Connect MCP

MCP uses the same bearer token model at /api/mcp.

{
  "mcpServers": {
    "willaos": {
      "url": "https://os.willacreative.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${WILLA_API_KEY}"
      }
    }
  }
}

Use a scoped API key for each agent. Start with read-only keys where possible; grant write routes only for workflows that have an explicit approval path.

4. Check Health

curl https://os.willacreative.dev/api/status

The /api-status page renders the same health data with links to REST and MCP docs.