Quickstart

This is the 5-minute path — the same one we time on every release (§578 process runbook). If any step takes longer than expected, that’s a docs bug; please open an issue.

Note

You’ll need a Cortex tenant. Sign up at https://cortexlayer.dev/signup — Clerk handles auth and the first tenant is provisioned for you automatically (with a Stripe customer + free plan).

What you’ll have at the end

A working chat widget on a real page, talking to a real agent of yours, streaming tokens from Gemini.

1. Mint an API key (≈30 s)

   In the dashboard, Settings → API keys → Create. Copy the key immediately — it’s shown once. Format: ck_live_<prefix>_<secret>.

2. Create an agent (≈60 s)

   Server-side call (curl or your backend). System prompt + provider — everything else has sane defaults.

   curl -sS https://api.cortexlayer.dev/v1/agents \
     -H "Authorization: Bearer $CORTEX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Support bot",
       "system_prompt": "You are a friendly support agent for ACME Inc.",
       "provider": "gemini",
       "model": "gemini-2.0-flash-exp",
       "allowed_origins": ["https://your-site.com"]
     }'

   The response includes agent_id (looks like agt_abc123…). Save it.

   Caution

   allowed_origins is enforced server-side on every widget session mint. The widget refuses to load if the page’s origin isn’t in this list — it’s the boundary that keeps your agent off random sites.

3. Mint a widget session (≈45 s)

   This is the only call that needs your API key. Run it on your backend (so the key never reaches the browser) and inject the returned token into the page.

   curl

   curl -sS https://api.cortexlayer.dev/v1/widget/session \
     -H "Authorization: Bearer $CORTEX_API_KEY" \
     -H "Origin: https://your-site.com" \
     -H "Content-Type: application/json" \
     -d '{ "agent_id": "agt_abc123..." }'

   Returns { "session_token": "cs_…", "expires_at": "..." }. The token is valid for 15 minutes and 50 messages — refresh it on page load. For long-lived pages, refresh in-place via handle.setSessionToken(newToken) (see Widget reference) so the active conversation isn’t lost when the token rolls over.

   Next.js (App Router)

   app/api/cortex/session/route.ts

   import { createCortexClient } from '@cortex/sdk';
   import { createMintRouteHandler } from '@cortex/sdk/next';
   
   const client = createCortexClient({
     baseUrl: 'https://api.cortexlayer.dev',
     auth: { apiKey: process.env.CORTEX_API_KEY! },
   });
   
   export const POST = createMintRouteHandler({
     client,
     agentId: 'agt_abc123...',
   });

   The browser POSTs to /api/cortex/session; the handler forwards your real Origin header to Cortex.

4. Drop the script tag (≈30 s)

   Inject the token into your page (server-rendered or fetched on load) and paste this:

   <script
     src="https://cdn.cortexlayer.dev/widget.v1.js"
     integrity="sha384-EsA2JT5EXb3PH2k87CX4d7W764dt2ljIUpXKg+37GpWAvY+hR9tFAJnrsTvaKAuh"
     crossorigin="anonymous"
     data-cortex-widget
     data-api-base="https://api.cortexlayer.dev"
     data-agent-id="agt_REPLACE_ME"
     data-session-token="cs_REPLACE_ME"
   ></script>

   The integrity hash above is generated at docs build time from the live widget bundle. If the hash changes, copy the new one — the browser will refuse to execute a bundle whose hash doesn’t match.

5. Verify (≈60 s)

   Open the page. The launcher button should appear in the bottom-right corner. Click it, type “hello”, hit send. You should see streamed deltas within a second.

   If nothing appears, check the browser console:

   • Refused to load … integrity mismatch — the SRI hash in your snippet doesn’t match the bundle. Rebuild and copy the latest hash from this page.
   • session token rejected — the page’s origin isn’t in the agent’s allowed_origins. Update the agent.
   • 429 plan_limit_exceeded — you’re past your free-plan budget. Check /v1/usage.

Total: ~3:45 if you don’t fumble curl

Faster on second pass. Slower the first time only because the dashboard is a separate tab — once you have an API key, steps 2–5 take well under three minutes.

What’s next

• The Widget reference lists every data-* attribute (theming, position, greeting overrides).
• The API reference documents the agent/session endpoints.
• The SDK reference covers the @cortex/sdk npm package — useful if your UI is custom and the floating widget isn’t the right fit.