API Reference | Documentation

Get started

Build and run your company from your AI assistant. One API call, no browser.

Get started

Describe your business in plain language and Founden builds the full product (website, app, admin) in the cloud and returns a live link. Connect it to any AI assistant over MCP, or call the API directly. One API key, no browser to keep open.

One API key (omk_). The same key works across every O-mega product. No browser to keep open: builds run in the cloud and deploy automatically.

Step 1: Get your API key

Create a key in Founden's Settings, under Founden API. It starts with omk_.

Step 2: Connect your assistant, or start a build from your code

MCP (Claude, Cursor and other MCP clients)

{
  "mcpServers": {
    "founden": {
      "command": "npx",
      "args": [
        "-y",
        "founden-mcp"
      ],
      "env": {
        "FOUNDEN_API_KEY": "omk_your_key"
      }
    }
  }
}

Python

pip install founden

from founden import Founden

client = Founden("omk_your_key")
build = client.build("Build a booking site for my dental clinic with online payments")
for event in client.stream(build.execution_id):
    print(event["event"], event["data"])

TypeScript

npm install founden

import { Founden } from "founden";

const client = new Founden("omk_your_key");
const build = await client.build("Build a booking site for my dental clinic with online payments");
for await (const ev of client.stream(build.data!.execution_id as string)) {
  console.log(ev.event, ev.data);
}

curl

curl -X POST https://founden.ai/v1/builds \
  -H "Authorization: Bearer omk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a booking site for my dental clinic with online payments"}'

All four use the same key and the same credits.

Authentication

API key authentication and rate limits

Authentication

The Founden API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Authorization: Bearer omk_your_key_here

API keys are created in Founden's Settings, under Founden API. A key drives your Founden account from your own apps and AI assistants and is tied to your account and credit balance. Keys can be revoked there at any time.

Rate limits

Default: 60 requests per minute per key. Rate limit headers are included in every response:

X-RateLimit-Remaining: 58
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1713400060
X-Credits-Used: 2

Credit costs

Per-capability credit pricing

Credit costs

A credit is a fixed amount of compute. Starting a build or sending it a message charges nothing up front (credits_used 0): the build is charged as it runs, for the compute it actually uses, so there is no fixed price per build (a build your desktop app picks up runs on your own Claude, ChatGPT or Google AI plan instead and spends desktop credits for what its AI use really costs). Reading status, streaming progress and stopping a build are free.

/v1/builds

Metered

Start a Founden build from a plain-language prompt

/v1/builds/{execution_id}

0 credits

Get build status and the live preview URL

/v1/builds/{execution_id}/message

Metered

Send a follow-up instruction to a running build

/v1/builds/{execution_id}/stop

0 credits

Stop a running build

Credits are returned in the credits_used field and the X-Credits-Used response header.

Errors

Error handling and status codes

Errors

All errors follow RFC 7807 (Problem Details for HTTP APIs) with additional fields for agent consumption.

{
  "success": false,
  "error": {
    "type": "https://api.o-mega.ai/errors/rate-limited",
    "title": "Rate limit exceeded",
    "status": 429,
    "detail": "You have exceeded 60 requests per minute",
    "is_retriable": true,
    "retry_after_seconds": 42,
    "alternative_action": "Reduce request frequency or contact support",
    "error_category": "transient"
  },
  "credits_used": 0
}

Error categories

Transient

Temporary issue. Safe to retry after retry_after_seconds.

Permanent

Request is invalid. Do not retry with the same parameters.

Authentication

API key is missing, invalid, or revoked.

Billing

Insufficient credits. Upgrade plan or enable overage.

Content_access

The target content could not be accessed (blocked, CAPTCHA, etc).

HTTP status codes

200

Success. The request completed and data is in the response.

400

Bad request. Missing or invalid parameters.

401

Unauthorized. API key is missing or invalid.

402

Insufficient credits. Upgrade or enable overage.

422

Unprocessable. The request was valid but the operation failed (e.g. scrape blocked).

429

Rate limited. Retry after the specified interval.

502

Provider error. All upstream providers failed.

Response format

Unified response envelope

Response format

Every response uses the same format. This makes it easy for agents to parse responses uniformly.

{
  "success": boolean,
  "data": { ... } | null,
  "error": { ... } | null,
  "metadata": {
    "response_time_ms": number,
    "request_id": "string"
  },
  "credits_used": number
}

Metadata fields

response_time_ms

number

Total wall-clock time for the request in milliseconds.

request_id

string

Unique request identifier for debugging and support.

SDKs

Official packages for every integration method

SDKs

Every package uses the same API key and hits the same backend. Pick whichever fits your stack.

MCP Server

$ npx founden-mcp

For Claude, Cursor and other MCP clients. Your assistant starts, follows and steers builds from chat.

Python SDK

$ pip install founden

Sync and async clients: build, stream, status, message and stop.

TypeScript SDK

$ npm install founden

The same calls for Node.js and any TypeScript project.

REST API

Works with any language or framework. Use curl or any HTTP client with a Bearer token.

Machine-readable formats

For auto-generating clients or configuring agent frameworks:

OpenAPI spec

/v1/openapi.json?product=founden

Filtered OpenAPI 3.1 spec with only the Founden endpoints.

Tool definitions

/v1/tools?product=founden&format=openai

Pre-built tool schemas for OpenAI, Claude, and MCP. Formats: openai, claude, mcp, raw.

llms.txt

/llms.txt

AI-readable documentation index for agent discovery.

Streaming

Live build progress via SSE

Streaming

Every build streams its progress as Server-Sent Events (SSE). Connect to the stream after starting a build.

GET /v1/builds/{execution_id}/stream
Authorization: Bearer omk_your_key

Event types

Build_step

A step of the build. Fields: step, status, and step-specific details (e.g. sandbox_init, preview_url).

Build_complete

The agent finished building. Fields: result with preview_url and sandbox_id. Deploy may still be finishing.

Build_done

All work complete (build + deploy). Fields: vercel_url (the live site), github_repo, surface_changed.

Orphaned_build

The agent worked but the changes did not reach the live site (built outside the published app). Fields: execution_id, message.

Build_error

The build failed. Fields: error.

/v1/builds

Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.

POST/v1/builds

Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.

Start a Founden build from a plain-language prompt

Parameters

prompt

Required

string

What to build or change, in plain language.

company_id

string

Target an existing company you own. Omit to use (or create) your default company.

Example response

{
  "success": true,
  "data": {
    "execution_id": "1e04e65f-6ded-4731-bc14-a1b307403bf3",
    "company_id": "6a1bc9a7bea382d028741c45",
    "status": "running",
    "stream_url": "/cloud-build/1e04e65f-6ded-4731-bc14-a1b307403bf3/stream"
  },
  "metadata": {
    "request_id": "req_xyz789"
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}

Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.

GET/v1/builds/{execution_id}

Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.

Get build status and the live preview URL

Parameters

execution_id

Required

string

The execution_id returned by build_company.

Example response

{
  "success": true,
  "data": {
    "execution_id": "1e04e65f...",
    "status": "completed",
    "preview_url": "https://your-company.vercel.app"
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}/message

Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site.

POST/v1/builds/{execution_id}/message

Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site.

Send a follow-up instruction to a running build

Parameters

execution_id

Required

string

The execution_id returned by build_company.

prompt

Required

string

Follow-up instruction for the running build agent.

Example response

{
  "success": true,
  "data": {
    "status": "accepted",
    "execution_id": "1e04e65f..."
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}/stop

Gracefully stop an in-progress build. Any work already committed is saved.

POST/v1/builds/{execution_id}/stop

Gracefully stop an in-progress build. Any work already committed is saved.

Stop a running build

Parameters

execution_id

Required

string

The execution_id returned by build_company.

Example response

{
  "success": true,
  "data": {
    "message": "Build stopped."
  },
  "credits_used": 0
}

Try it in the app

Get started

Build and run your company from your AI assistant. One API call, no browser.

Get started

One API key (omk_). The same key works across every O-mega product. No browser to keep open: builds run in the cloud and deploy automatically.

Step 1: Get your API key

Create a key in Founden's Settings, under Founden API. It starts with omk_.

Step 2: Connect your assistant, or start a build from your code

MCP (Claude, Cursor and other MCP clients)

{
  "mcpServers": {
    "founden": {
      "command": "npx",
      "args": [
        "-y",
        "founden-mcp"
      ],
      "env": {
        "FOUNDEN_API_KEY": "omk_your_key"
      }
    }
  }
}

Python

pip install founden

from founden import Founden

client = Founden("omk_your_key")
build = client.build("Build a booking site for my dental clinic with online payments")
for event in client.stream(build.execution_id):
    print(event["event"], event["data"])

TypeScript

npm install founden

import { Founden } from "founden";

const client = new Founden("omk_your_key");
const build = await client.build("Build a booking site for my dental clinic with online payments");
for await (const ev of client.stream(build.data!.execution_id as string)) {
  console.log(ev.event, ev.data);
}

curl

curl -X POST https://founden.ai/v1/builds \
  -H "Authorization: Bearer omk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a booking site for my dental clinic with online payments"}'

All four use the same key and the same credits.

Authentication

API key authentication and rate limits

Authentication

The Founden API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Authorization: Bearer omk_your_key_here

Rate limits

Default: 60 requests per minute per key. Rate limit headers are included in every response:

X-RateLimit-Remaining: 58
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1713400060
X-Credits-Used: 2

Credit costs

Per-capability credit pricing

Credit costs

/v1/builds

Metered

Start a Founden build from a plain-language prompt

/v1/builds/{execution_id}

0 credits

Get build status and the live preview URL

/v1/builds/{execution_id}/message

Metered

Send a follow-up instruction to a running build

/v1/builds/{execution_id}/stop

0 credits

Stop a running build

Credits are returned in the credits_used field and the X-Credits-Used response header.

Errors

Error handling and status codes

Errors

All errors follow RFC 7807 (Problem Details for HTTP APIs) with additional fields for agent consumption.

{
  "success": false,
  "error": {
    "type": "https://api.o-mega.ai/errors/rate-limited",
    "title": "Rate limit exceeded",
    "status": 429,
    "detail": "You have exceeded 60 requests per minute",
    "is_retriable": true,
    "retry_after_seconds": 42,
    "alternative_action": "Reduce request frequency or contact support",
    "error_category": "transient"
  },
  "credits_used": 0
}

Error categories

Transient

Temporary issue. Safe to retry after retry_after_seconds.

Permanent

Request is invalid. Do not retry with the same parameters.

Authentication

API key is missing, invalid, or revoked.

Billing

Insufficient credits. Upgrade plan or enable overage.

Content_access

The target content could not be accessed (blocked, CAPTCHA, etc).

HTTP status codes

200

Success. The request completed and data is in the response.

400

Bad request. Missing or invalid parameters.

401

Unauthorized. API key is missing or invalid.

402

Insufficient credits. Upgrade or enable overage.

422

Unprocessable. The request was valid but the operation failed (e.g. scrape blocked).

429

Rate limited. Retry after the specified interval.

502

Provider error. All upstream providers failed.

Response format

Unified response envelope

Response format

Every response uses the same format. This makes it easy for agents to parse responses uniformly.

{
  "success": boolean,
  "data": { ... } | null,
  "error": { ... } | null,
  "metadata": {
    "response_time_ms": number,
    "request_id": "string"
  },
  "credits_used": number
}

Metadata fields

response_time_ms

number

Total wall-clock time for the request in milliseconds.

request_id

string

Unique request identifier for debugging and support.

SDKs

Official packages for every integration method

SDKs

Every package uses the same API key and hits the same backend. Pick whichever fits your stack.

MCP Server

$ npx founden-mcp

For Claude, Cursor and other MCP clients. Your assistant starts, follows and steers builds from chat.

Python SDK

$ pip install founden

Sync and async clients: build, stream, status, message and stop.

TypeScript SDK

$ npm install founden

The same calls for Node.js and any TypeScript project.

REST API

Works with any language or framework. Use curl or any HTTP client with a Bearer token.

Machine-readable formats

For auto-generating clients or configuring agent frameworks:

OpenAPI spec

/v1/openapi.json?product=founden

Filtered OpenAPI 3.1 spec with only the Founden endpoints.

Tool definitions

/v1/tools?product=founden&format=openai

Pre-built tool schemas for OpenAI, Claude, and MCP. Formats: openai, claude, mcp, raw.

llms.txt

/llms.txt

AI-readable documentation index for agent discovery.

Streaming

Live build progress via SSE

Streaming

Every build streams its progress as Server-Sent Events (SSE). Connect to the stream after starting a build.

GET /v1/builds/{execution_id}/stream
Authorization: Bearer omk_your_key

Event types

Build_step

A step of the build. Fields: step, status, and step-specific details (e.g. sandbox_init, preview_url).

Build_complete

The agent finished building. Fields: result with preview_url and sandbox_id. Deploy may still be finishing.

Build_done

All work complete (build + deploy). Fields: vercel_url (the live site), github_repo, surface_changed.

Orphaned_build

The agent worked but the changes did not reach the live site (built outside the published app). Fields: execution_id, message.

Build_error

The build failed. Fields: error.

/v1/builds

Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.

POST/v1/builds

Describe the business or app you want. Founden builds the full product in the cloud and returns an execution_id plus a stream URL for live progress.

Start a Founden build from a plain-language prompt

Parameters

prompt

Required

string

What to build or change, in plain language.

company_id

string

Target an existing company you own. Omit to use (or create) your default company.

Example response

{
  "success": true,
  "data": {
    "execution_id": "1e04e65f-6ded-4731-bc14-a1b307403bf3",
    "company_id": "6a1bc9a7bea382d028741c45",
    "status": "running",
    "stream_url": "/cloud-build/1e04e65f-6ded-4731-bc14-a1b307403bf3/stream"
  },
  "metadata": {
    "request_id": "req_xyz789"
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}

Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.

GET/v1/builds/{execution_id}

Poll a build by execution_id. Returns the current status and, once ready, the live preview URL.

Get build status and the live preview URL

Parameters

execution_id

Required

string

The execution_id returned by build_company.

Example response

{
  "success": true,
  "data": {
    "execution_id": "1e04e65f...",
    "status": "completed",
    "preview_url": "https://your-company.vercel.app"
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}/message

Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site.

POST/v1/builds/{execution_id}/message

Keep iterating in plain language. 'Add online booking.' 'Change the colors.' The change ships to your live site.

Send a follow-up instruction to a running build

Parameters

execution_id

Required

string

The execution_id returned by build_company.

prompt

Required

string

Follow-up instruction for the running build agent.

Example response

{
  "success": true,
  "data": {
    "status": "accepted",
    "execution_id": "1e04e65f..."
  },
  "credits_used": 0
}

Try it in the app

/v1/builds/{execution_id}/stop

Gracefully stop an in-progress build. Any work already committed is saved.

POST/v1/builds/{execution_id}/stop

Gracefully stop an in-progress build. Any work already committed is saved.

Stop a running build

Parameters

execution_id

Required

string

The execution_id returned by build_company.

Example response

{
  "success": true,
  "data": {
    "message": "Build stopped."
  },
  "credits_used": 0
}

Try it in the app