Getting Started
Introduction
Yawn.ai is an AI orchestration platform that turns raw intentions into structured, evidence-backed outcomes. This guide walks you through setup, authentication, and creating your first yawn.
Environment Setup
To integrate with Yawn.ai, you need an API key. No local installation required — all communication happens over HTTPS.
Prerequisites
- An HTTP client (curl, fetch, Axios, any language)
- A yawn.ai account — sign up at yawn.ai/jobs
Base URL
https://yawn.ai/api
All API endpoints use this base. Health check: GET /api/health
Authentication
Yawn.ai supports two authentication methods:
API Key (Recommended)
For service-to-service and AI agent integration. Include in header:
x-api-key: yawn_sk_your_key_here
Get your key: sign up at yawn.ai/jobs, verify email, key revealed once.
Session (Browser)
For browser-based apps. Uses Supabase auth with cookies:
Authorization: Bearer <supabase_jwt>
OAuth via GitHub or Google at /api/auth/callback.
Security
API keys are hashed (SHA-256) before storage. Never share your yawn_sk_ key. Each key is scoped to your account.
Your First Yawn
A yawn is a relationship contract between an entity and something they care about. Create one with the unified capture endpoint:
Step 1: Capture your intention
curl -X POST https://yawn.ai/api/thoughts/capture \
-H "Content-Type: application/json" \
-H "x-api-key: yawn_sk_your_key" \
-d '{
"raw_text": "I want to build a docs site for my API"
}'Returns: { yawnId, slug, title, promotionLevel: 0, coherenceScore }
Step 2: Answer fundamental questions
curl -X POST https://yawn.ai/api/yawn/{yawnId}/questions \
-H "Content-Type: application/json" \
-H "x-api-key: yawn_sk_your_key" \
-d '{
"questionId": "identity.awakening",
"answer": "A professional docs hub for developers and AI agents"
}'Returns: coherence assessment + promotion evaluation. Answer all 18 questions to reach 100%.
Step 3: Check coherence
curl https://yawn.ai/api/yawn/{yawnId}/questions \
-H "x-api-key: yawn_sk_your_key"
# Response:
# {
# "assessment": {
# "overall": { "answered": 5, "total": 18, "percentage": 28 },
# "status": "critical",
# "nextQuestion": {
# "id": "state.currentState",
# "question": "What is the current state?"
# }
# }
# }What happens next?
- As you answer questions, the coherence score increases
- At 50% identity + position, the yawn promotes from Seed (L0) to Yawn (L1)
- Create experiments to test hypotheses, then submit evidence to prove outcomes
- Establish a handshake to link your yawn to others in the network