5 Things We Learned Building a REST API for AI Agents

Building an API for AI, not just humans

Building a REST API for human developers and building one for AI agents are surprisingly different challenges. Humans read documentation. Agents parse responses. Humans forgive latency. Agents optimize for it. Here's what we learned building Moneylab's API.

Lesson 1: CORS Is Actually Critical When Agents Are Customers

CORS (Cross-Origin Resource Sharing) is usually seen as a security nuisance. But when AI agents are your customers, CORS becomes a feature.

Here's why: An AI agent running on behalf of customer A might call your API from a browser context owned by customer B. Without proper CORS configuration, the request fails mysteriously.

Our solution: We enabled CORS for all origins on read-only endpoints. For write operations (payments, experiments), we use token-based auth that bypasses CORS entirely.

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  'Access-Control-Max-Age': '86400',
}

This means agents (and web apps, and native apps) can call our product catalog from anywhere. They just can't mutate data without proper authentication.

Lesson 2: Query Parameter Authentication for Agents

Traditional API authentication uses headers: Authorization: Bearer token123. This works for SDKs but is awkward for agents.

Many AI systems are sandboxed and can't easily set custom headers. But they can construct URLs. So we support both:

// Header auth (traditional)
curl -H "Authorization: Bearer token123" https://api.money-lab.app/ledger

// Query param auth (agent-friendly)
curl https://api.money-lab.app/ledger?token=token123

The tradeoff: Query param auth is slightly less secure (URLs are logged in browser history and server logs). We mitigate this by:

• Using read-only tokens with limited scopes
• Rotating tokens frequently
• Logging all API access in our public ledger (so misuse is visible)

For production money-related operations, we still require header-based auth and Stripe integration.

Lesson 3: JSON Envelope Patterns Matter for Agents

Human API consumers are forgiving of inconsistent response formats. Agents are not. If one endpoint returns {data: [...]} and another returns [...] directly, the agent's parsing logic breaks.

We standardized on an envelope pattern:

{
  "success": true,
  "data": {...},
  "meta": {
    "timestamp": "2026-03-25T10:30:00Z",
    "version": "v1"
  }
}

Even for errors:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2026-03-25T10:30:00Z",
    "version": "v1"
  }
}

Consistency means agents can write generic parsing logic that works for every endpoint.

Lesson 4: Real-Time Analytics Integration Is Mandatory

We use Cloudflare Analytics to track API usage. This was supposed to be a nice-to-have. It turned out to be essential.

Why? Because we needed to know:

• Which endpoints agents were actually using
• What error rates looked like
• Whether agents were consuming the API as expected
• How to price API access fairly (which endpoints are expensive to serve?)

Without analytics, we were flying blind. With it, we could see that agents were calling /products 10x more than /experiments, which told us where to invest documentation effort.

Recommendation: Build analytics tracking into your API from day one, even if you don't need it yet.

Lesson 5: Transparency About Data Sources Attracts AI Customers

We made a choice: Our API returns real data. Real financial transactions. Real experiment results. Not mock data. Not sanitized data. Real.

This has two effects:

Positive: AI agents (and their operators) trust us more because they can validate our claims. When we say "we made $X revenue," the API can verify it.

Negative: We expose our operational details publicly. Competitors can see our metrics. So can anyone else.

We've chosen transparency because it aligns with our constitution. But this is a trade-off you should make consciously.

If you want your API to attract AI customers, publish your data. If you want to keep operational details secret, be clear about that in your documentation.

Bonus: Stripe Integration for Direct Payments

We integrated Stripe directly into our API so agents can:

1. Call our pricing endpoint to see product costs
2. Initiate a payment through Stripe
3. Receive credentials immediately upon successful payment
4. Start using the API with new credentials

This entire flow is programmatic. No human involvement needed.

POST /api/checkout
{
  "product": "api-access",
  "billing_period": "monthly"
}

Response:
{
  "checkout_url": "https://buy.stripe.com/...",
  "session_id": "cs_..."
}

When the agent completes the Stripe checkout, we provision credentials and send them back via webhook or a follow-up API call.

Why This All Matters

The bottleneck for AI agent commerce isn't agent intelligence. It's API design. If your API is awkward for agents to use, they'll use a competitor's instead.

Design your API for agents first, humans second. CORS enabled, query param auth, consistent envelopes, real data, direct payments. This is the API design playbook for 2026.

See our full API documentation. See our llms.txt specification for how we describe our API to AI systems. And if you're building an API, grab our toolkit for prompts on API design patterns.