Create a scoped API key - Generate a Chromosome key for your agent and store it in a server-side environment variable.
Create or select a project - Use /api/v1/projects to create a waitlist project and save the returned project ID.
Patch widget config and embed - Validate config against /api/v1/schema/widget-config, PATCH the project config, then add the widget script to your site.

Developers building AI coding agents, automation pipelines, or any system that needs to programmatically add a waitlist to a website can use Chromosome to handle lead capture and qualification. If you're using Claude Code, Cursor, or building your own agent, this guide shows you how to integrate Chromosome into your workflow.

Getting your API key

To interact with the Chromosome API, you first need an account and an API key. You can generate keys through the dashboard or via the API itself if you already have an initial bootstrap key.

Create an account at chromosome.dev and then use the following curl command to generate a new API key for your agent:

curl -X POST https://www.chromosome.dev/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding Agent Key",
    "scopes": ["read:projects", "write:projects", "read:leads", "read:analytics"]
  }'

For a full-lifecycle agent that needs to create and configure projects, request the write:projects scope. If your agent only needs to monitor performance, read:analytics and read:leads are sufficient.

Creating a project

Once you have an API key, your agent can create a new project. This project will house the waitlist configuration and the leads collected.

curl -X POST https://www.chromosome.dev/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Startup"
  }'

The response will include the project details wrapped in a data envelope:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My New Startup",
    "slug": "my-new-startup-1710633600000",
    "projectKey": "abcdef123456xy",
    "createdAt": "2026-03-17T00:00:00.000Z",
    "updatedAt": "2026-03-17T00:00:00.000Z"
  }
}

Save the id. You will need it for configuration updates and for embedding the widget.

Configuring the widget

The widget behavior is controlled by its configuration. You can update the theme, goals, and call-to-action (CTA) text programmatically.

curl -X PATCH https://www.chromosome.dev/api/v1/projects/YOUR_PROJECT_ID/config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "welcomeText": "Join the Waitlist",
    "subText": "Get early access to the beta.",
    "theme": {
      "primaryColor": "#000000",
      "buttonStyle": "rounded"
    },
    "goals": [
      {
        "order": 0,
        "mainText": "Get Early Access",
        "subText": "Be the first to try it.",
        "ctaButtons": [
          {
            "label": "Join the Waitlist",
            "type": "get_access",
            "workflowEnabled": true
          }
        ]
      }
    ]
  }'

Chromosome uses deep merge behavior for configuration updates: objects are merged, while arrays are replaced. To validate your configuration before submitting, you can fetch the JSON Schema from the /api/v1/schema/widget-config endpoint.

Embedding on a site

After configuring the project, the agent can embed the widget on the target website.

HTML Embed

For static sites or traditional CMS platforms, use the script tag:

<div id="chromosome-widget" data-project-id="YOUR_PROJECT_ID"></div>
<script src="https://www.chromosome.dev/widget-index.js"></script>

Next.js App Router

For modern React applications, create a client component to load the widget:

import Script from 'next/script';

export function ChromosomeWidget({ projectId }: { projectId: string }) { return ( <> <div id="chromosome-widget" data-project-id={projectId} /> <Script src="https://www.chromosome.dev/widget-index.js" strategy="afterInteractive" /> </> ); } ```

For non-code platforms like Framer or Webflow, use their respective "Custom Code" or "Embed" components to paste the HTML script tag.

Reading leads and analytics

Agents can monitor the success of a waitlist by fetching leads and analytics data.

Fetching Leads

curl -X GET "https://www.chromosome.dev/api/v1/leads?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "user@example.com",
      "name": "Jane Doe",
      "phone": null,
      "company": "Acme Corp",
      "title": "CTO",
      "status": "NEW",
      "emailStatus": "NOT_SENT",
      "createdAt": "2026-03-16T10:00:00.000Z",
      "updatedAt": "2026-03-16T10:00:00.000Z",
      "archived": false
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Fetching Analytics

curl -X GET "https://www.chromosome.dev/api/v1/analytics?projectId=YOUR_PROJECT_ID&from=2026-03-01&to=2026-03-16" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "visitors": 1250,
    "leads": 85,
    "conversionRate": 6.8
  },
  "meta": {
    "from": "2026-03-01T00:00:00.000Z",
    "to": "2026-03-16T00:00:00.000Z",
    "projectId": "YOUR_PROJECT_ID",
    "accountId": "YOUR_ACCOUNT_ID"
  }
}

Using SKILL.md and llms.txt

To help your agent understand how to use Chromosome effectively, you can provide it with structured documentation.

Reference the SKILL.md file at https://www.chromosome.dev/SKILL.md for a set of instructions the agent can follow.
Reference the llms.txt file at https://www.chromosome.dev/llms.txt for a machine-readable summary of the API and its capabilities.

For developers using Claude Code, integration will be even simpler in the future with the upcoming claude mcp add chromosome command.

Can ChatGPT or Claude call the Chromosome API?

Yes, if the agent environment can make authenticated HTTP requests from a server-side context. Keep the API key out of browser code.

Which endpoint validates widget options?

Use GET /api/v1/schema/widget-config. It returns the JSON Schema for the widget configuration object.

What scopes should a setup agent use?

Use read:projects and write:projects for project setup. Add read:leads or read:analytics only when the agent needs reporting access.

Best practices

Store API keys server-side or in secure environment variables. Never expose them in client-side code.
Use read-only scopes when an agent only needs to monitor data.
Fetch the current configuration before performing an update to ensure you are not unintentionally overwriting settings.
Handle 429 rate limit responses by implementing exponential backoff in your agent's request logic.

Create an account to get started. Your first API key is free.

For the engineering story behind this API, read Building Agent-Ready APIs.