Agent-ready APIs need runtime schemas - TypeScript types are useful for builders, but agents need public JSON Schema and field descriptions.
Auth must be scoped and predictable - API keys need clear prefixes, account scoping, and permissions that limit what an agent can do.
Discovery files matter - llms.txt and SKILL.md give agents flat instructions they can read without navigating a docs app.

AI coding agents are now the primary way many developers interact with APIs. Claude Code, Cursor, v0, and bolt.new generate code that calls your services every day. If your API isn't designed for agent consumption, these tools will hallucinate, make mistakes, and produce broken integrations.

This is a new design constraint that most API teams haven't considered. We spent the last month rebuilding Chromosome's v1 API to be "agent-ready." We didn't just add a few docs. We changed how we define schemas, how we handle auth, and how we expose our capabilities to the world.

The 4-Layer Model

We identified four layers that make an API agent-consumable. Each layer builds on the previous one to create a clear path for both humans and AI.

Typed Schemas: The foundation of truth.
Structured Documentation: Machine-readable context.
Clean Auth: Predictable and scoped security.
Discoverability: Standardized entry points for AI.

Layer 1: Zod as Source of Truth

We migrated from standard TypeScript interfaces to Zod schemas for all request and response objects. TypeScript interfaces are great for build-time safety, but they disappear at runtime. Agents need that metadata during the generation phase.

The key insight was using .describe() on every field. This metadata becomes part of the JSON Schema that agents use to understand what a field actually does.

Consider this standard interface:

interface CreateWidgetRequest {
  name: string;
  description: string;
  targetIcp: string;
}

An agent might guess what targetIcp means, but it's a coin flip. Here is how we define it now:

const CreateWidgetSchema = z.object({
  name: z
    .string()
    .describe('The internal name of the widget for your dashboard.'),
  description: z
    .string()
    .describe(
      'A detailed description of your product. The AI agent uses this to answer visitor questions.'
    ),
  targetIcp: z
    .string()
    .describe(
      'A description of your ideal customer profile. Helps the AI qualify leads.'
    ),
});

We follow a strict rule: .describe() must be the last call in the chain. This ensures the description is attached to the final, validated type. We then use zod-to-json-schema to generate a public schema endpoint that agents can fetch to understand our API surface without reading a single word of prose.

Layer 2: API Key Design

We adopted a Stripe-inspired pattern for our API keys. Every key uses a prefix like chrm_live_ or chrm_test_. This helps agents identify keys in environment variables and prevents them from accidentally using a production key in a test environment.

We use SHA-256 hashing for storage. We chose this over bcrypt because API key verification happens on every request. SHA-256 provides the right balance of security and performance for high-frequency API calls.

The most important part for agents is scoped permissions. The API key's scope defines the agent's capability surface. If an agent only has a read:projects key, it can't accidentally delete your entire configuration. This gives developers the confidence to let agents work on their behalf.

Layer 3: Structured Documentation

Agents don't browse documentation sites like humans do. They don't care about your sidebar navigation, your search UI, or your dark mode toggle. They need flat, structured text.

We implemented llms.txt, which is becoming the robots.txt for the AI era. It's a simple text file at the root of our domain that points to a full, unformatted version of our docs.

We also adopted the SKILL.md pattern. This is a single file that explains how to use the API in a way that an agent can ingest as a "skill." It includes common patterns, error handling strategies, and copy-pasteable examples. When an agent reads this, it doesn't just know the endpoints; it knows the best practices for using them.

What We Chose Not to Build

We intentionally deferred building an MCP server, an npm SDK, or a custom CLI.

Our insight was simple: a clean REST API with excellent, machine-readable documentation is more valuable than a half-baked wrapper. An MCP server is just a wrapper around your API. If you get the API right first, the wrappers become trivial to build later. By focusing on the core API, we ensured that any tool, whether it's a custom script or a sophisticated agent, can use Chromosome effectively.

Results

The results have been immediate. Agents can now create and configure Chromosome widgets without human intervention. They don't get stuck on ambiguous field names or complex auth flows. They just work.

If you're building a product that developers use, making it agent-consumable is worth the investment. It's the difference between your API being a tool they use and a tool they let their agents use for them.

If you're building a product that developers use, making it agent-consumable is worth the investment. Read the Agent Developer Guide to see what this looks like from the consumer side.

Create an account to try the API yourself.

Why not start with an SDK?

An SDK helps one runtime. A clean REST API plus JSON Schema helps any agent or framework that can make HTTP requests.

Why use Zod for API schemas?

Zod keeps validation close to the product code and can produce JSON Schema for agents. That makes the API contract visible at runtime.

Is llms.txt enough by itself?

No. llms.txt is an entrypoint. It works best with a full docs file, a skill file, scoped auth, and schemas that agents can validate against.