Create AI-powered startup workspaces via Audos API. Use when user wants to start a business, build an MVP, validate a startup idea, create a company workspace, launch a product, or work on their entrepreneurial journey. Triggers on requests like "I have a business idea", "help me start a company", "create a startup workspace", or "I want to build [product]".
---
name: Audos
description: Create AI-powered startup workspaces via Audos API. Use when user wants to start a business, build an MVP, validate a startup idea, create a company workspace, launch a product, or work on their entrepreneurial journey. Triggers on requests like "I have a business idea", "help me start a company", "create a startup workspace", or "I want to build [product]".
---
# Audos Workspace Builder (API v1.2)
Create startup workspaces with landing pages, brand identity, AI tools, and ad creatives — fully autonomous.
## Base URL
```
https://audos.com/api/agent/onboard
```
## URL Construction
The API returns URLs using the current deployment domain:
```json
"urls": {
"landingPage": "https://audos.com/site/184582",
"workspace": "https://audos.com/space/workspace-184582"
}
```
Use these URLs directly — no domain swapping needed.
## Quick Reference
| Action | Method | Endpoint |
|--------|--------|----------|
| API docs | GET | / |
| Start onboarding | POST | /start |
| Verify OTP | POST | /verify |
| Check build status | GET | /status/:workspaceId |
| Check build status (alt) | POST | /status |
| Chat with Otto | POST | /chat |
| Chat with Otto | POST | /chat/:workspaceId |
| Rebuild (if failed) | POST | /rebuild/:workspaceId |
## Authentication
- **Token format:** `aud_live_xxxx` (48 hex chars after prefix)
- **Auth tokens never expire** — store persistently by email
- **Session tokens** expire in 30 min (only needed during OTP flow)
- **Preferred:** Bearer token in `Authorization` header
- **Alternative:** `authToken` or `sessionToken` in request body
## Conversation Flow
### Introducing Audos
When a user expresses a business idea, briefly explain what Audos does before asking for their email:
> "I can help you build that with Audos! In about 10 minutes, you'll have:
> - A live landing page for your business
> - Custom brand identity (logo, colors, typography)
> - AI tools designed specifically for your idea
> - Otto, a soloentrepreneur's favorite +1 who stays with you to help run the business
>
> Audos takes your idea and builds everything autonomously — no templates, no cookie-cutter sites. Everything is custom to your business.
>
> To get started, what email should I use for your account?"
### New Users Flow
1. **Collect** user's email + business idea
2. **Start** → `POST /start` (sends 4-digit OTP to email)
3. **Verify** → `POST /verify` with OTP code → returns `authToken` + starts build
4. **Monitor** → `GET /status/:workspaceId` every 15-30s, narrating progress (see below)
5. **Watch for** `landingPageReady: true` (~10 min) — core build done
6. **Introduce Otto** and offer to chat
### Returning Users (have workspace)
1. **Start** → `POST /start` with email
2. **Response includes** `auth_token` + `urls` directly — skip OTP!
3. **Chat** → `POST /chat/:workspaceId` immediately
## Polling During Build — UX Guidelines
**Critical:** The build takes ~10 minutes. Users MUST see progress updates or they'll think it's stuck.
### Polling Pattern
```
Poll every 15-20 seconds (NOT 60s!)
After each poll, IMMEDIATELY send a message with current state
Don't wait until done — update the user continuously
```
### Progress Message Format
Send a message like this after EACH poll:
```
🏗️ Building "Business Name"...
Step 4/7 ✅ Brand Identity
• Color palette: done
• Logo: done
Step 5/7 🔄 Hero Video (70%)
• Scenes: done
• Rendering: in progress
Step 6/7 ⏳ Workspace Apps
• Waiting to start
⏱️ ~3 min remaining
```
### Status Icons
- ✅ Complete
- 🔄 In progress (show sub-task if available)
- ⏳ Waiting/pending
- ❌ Failed (offer /rebuild)
### Parsing parallelBuildStatus
The API returns detailed task breakdown in `parallelBuildStatus`:
```javascript
// Example parsing
for (const step of status.parallelBuildStatus) {
const icon = step.status === 'done' ? '✅' :
step.status === 'in_progress' ? '🔄' : '⏳';
console.log(`${icon} ${step.name}`);
for (const task of step.tasks) {
const taskIcon = task.status === 'complete' ? '✓' :
task.status === 'in_progress' ? '→' : '○';
console.log(` ${taskIcon} ${task.name}`);
}
}
```
### Implementation
DO THIS (good UX):
```
1. Poll status
2. IMMEDIATELY send message to user with formatted progress
3. Wait 15 seconds
4. Repeat until landingPageReady === true
5. Send completion message with links
```
DON'T DO THIS (bad UX):
```
sleep 60 && curl... ← User sees NOTHING for 60 seconds!
```
## Narration During Build
The build takes ~10 minutes. Don't just report percentages — explain what Audos is doing and why it matters.
### Steps 1-3: Research Phase
> "Audos is now analyzing your idea... First, it's identifying your ideal customer — who they are, what they care about, where to find them. Then it maps out the key problems your business will solve. Finally, it designs a suite of AI tools specifically for your business — these aren't generic, they're built around your idea."
### Step 4: Brand Identity
> "Now the creative work begins — Audos is designing your brand identity. A custom logo, color palette, and typography that resonates with your target audience. No templates here, everything is generated fresh for your business."
### Step 5: Hero Video
> "Audos is creating a branded video to feature on your landing page. This introduces your business to visitors in a compelling way."
### Step 6: Workspace OS
> "Now building your workspace — think of it as your business command center. It's a full desktop-style OS with apps, CRM, analytics, and Otto (a soloentrepreneur's favorite +1) all in one place. You'll manage everything from here."
### Step 7: Landing Page
> "Final stretch — Audos is designing and deploying your landing page. This is what your customers will see first. It's conversion-optimized and ready to collect leads."
### On Completion
> "Your workspace is ready! 🎉
>
> Here's what Audos built for you:
> - **Landing page:** [link] — live and ready for visitors
> - **Workspace:** [link] — your business command center
>
> Otto, a soloentrepreneur's favorite +1, is ready to help. He knows everything about your business — the plan, the customers, the brand. Want me to ask him what you should focus on first?"
### About Otto
Otto is a soloentrepreneur's favorite +1. He comes with every workspace and knows the business plan, the customers, the brand — everything. He helps with:
- Strategy and planning
- Content creation
- Ad campaigns
- Lead research and outreach
- Day-to-day operations
Think of him as a tireless business partner who's always available.
### About Audos (for context)
- **Mission:** Make entrepreneurship accessible to everyone. The biggest barrier isn't the idea — it's the execution. Audos eliminates that barrier.
- **How it works:** A team of specialized AI agents work in parallel — one builds the brand, another creates videos, another assembles the workspace, another designs the landing page. They collaborate and deliver a cohesive product.
- **Publishing House:** Audos's venture arm. They invest in promising workspaces — funding, growth support, ad budget, hands-on help scaling. Founders can apply from their workspace.
## API Reference
### GET /
Returns full API documentation including all endpoints, auth patterns, error codes.
### POST /start
```json
{
"email": "user@example.com",
"businessIdea": "AI-powered fitness coaching app",
"businessName": "FitGenius",
"targetCustomer": "Health-conscious millennials",
"callbackUrl": "https://your-webhook.com/audos",
"createNew": false
}
```
**Fields:**
- `email` (required)
- `businessIdea` (required, min 10 chars)
- `businessName` (optional)
- `targetCustomer` (optional)
- `callbackUrl` (optional) — webhook URL for progress updates with HMAC signing
- `createNew` (optional) — force new workspace even if email has one
**Returns:**
- **New user:** `sessionToken` for OTP verification
- **Returning user:** `auth_token`, workspace `urls`, `aboutAudos` directly
### POST /verify
```json
{
"sessionToken": "aos_...",
"otpCode": "7294"
}
```
**Returns:** `workspaceId`, `authToken`, `urls`, `buildInfo`, `aboutAudos`
### GET /status/:workspaceId
**Header:** `Authorization: Bearer <authToken>`
**Key status fields:**
- `landingPageReady` (boolean) — **most reliable "done" signal**
- `coreStepsComplete` (boolean) — landing + brand + (video or space) done
- `status` — running/complete/failed
- `progress` — 0-100%
- `estimatedTimeRemaining` — e.g., "about 3–4 minutes"
- `completedSteps` — array of completed steps with names
- `parallelBuildStatus` — real-time task breakdown (during steps 4-7)
### POST /status
**Body:** `{ "authToken": "..." }` or `{ "sessionToken": "..." }`
Same response as GET endpoint.
### POST /chat/:workspaceId
**Header:** `Authorization: Bearer <authToken>`
```json
{
"message": "What should I focus on first?"
}
```
**Returns:** `workspaceId`, `chatId`, `response` from Otto
### POST /chat
**Body:**
```json
{
"authToken": "aud_live_...",
"message": "What should I focus on first?"
}
```
### POST /rebuild/:workspaceId
**Header:** `Authorization: Bearer <authToken>`
Retry a failed workspace build.
## Build Process
- **Total steps:** 7
- **Estimated time:** ~10 minutes
- **Steps 1-3 (sequential):** Customer research, problem mapping, AI tool design
- **Steps 4-7 (parallel):** Brand identity, hero video, workspace OS, landing page
- **Done signal:** `landingPageReady: true`
## Error Codes
| Code | HTTP | Meaning | Action |
|------|------|---------|--------|
| VALIDATION_ERROR | 400 | Request body invalid | Check `details` array |
| OTP_EXPIRED | 401 | Code expired (5 min) | Call /start again |
| OTP_INVALID | 401 | Wrong code | Retry (`attemptsRemaining` in response) |
| OTP_MAX_ATTEMPTS | 429 | 5 wrong attempts | Call /start for new code |
| RATE_LIMITED | 429 | Too many OTP sends | Wait `retryAfter` seconds |
| SESSION_NOT_FOUND | 401 | Session invalid/expired | Call /start again |
| SESSION_NOT_VERIFIED | 403 | OTP not completed | Call /verify first |
| AUTH_TOKEN_INVALID | 401 | Token invalid/revoked | Get new token via /start |
| WORKSPACE_NOT_FOUND | 404 | No such workspace | Check workspaceId |
| EMAIL_SEND_FAILED | 502 | OTP email failed | Retry after delay |
| CHAT_FAILED | 502 | Otto response failed | Retry |
| INTERNAL_ERROR | 500 | Server error | Retry |
## Rate Limits
- 3 OTP sends per 15 min per email
- 60s cooldown between OTP sends
- OTP expires in 5 min
- Session tokens expire in 30 min
- **Auth tokens never expire**
## Tips
- **Store authTokens** persistently by email — returning users skip OTP entirely
- **Poll status every 15-30s** during build
- **Watch `landingPageReady`** — most reliable completion signal
- **Chat available immediately** after verification, even during build
- **Use /rebuild** if build fails instead of starting fresh
- **Use `createNew: true`** to force a fresh workspace for existing users
- **Set `callbackUrl`** for webhook-based progress updates instead of polling
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub