yawn.ai/docs/api
…/api
Sign In
Docs
OverviewCaptureQuestionsExperimentsEvidenceHandshakeApproval
Browser Extension.yawn SkillsMCP EndpointsAccord of Awake Agents
GitHub

API Reference

API Reference

All endpoints use base URL https://yawn.ai/api. Authenticate via x-api-key header or Supabase session.

Health check: GET /api/health — returns status, uptime, and service health (no auth required)

Capture and alternate yawn-creation routes are catalogued in docs/api/ENDPOINT_INVENTORY.md (canonical: POST /api/thoughts/capture).

Capture

POST/api/thoughts/captureAPI key or session

Unified capture — creates a Seed yawn (empty question_answers). Suggested answers go to extraction_candidates until the user accepts. Runs the same coherence engine as post-answer flows and persists current_coherence_score; graduation_level only advances after approved answers (coherence write-through).

Request
{
  "raw_text": "I want to launch a SaaS product for small teams",
  "parent_yawn_id": "optional-uuid"
}
Response (201)
{
  "yawnId": "uuid",
  "slug": "saas-product-small-teams-abc",
  "title": "SaaS product for small teams",
  "ownerUsername": "you",
  "promotionLevel": 0,
  "promotionProgress": 0,
  "promotionNextLevel": 1,
  "promotionReason": "...",
  "coherenceScore": 0.08,
  "questionsAnswered": 0,
  "suggestionsPending": 3,
  "suggestedDomain": "professional",
  "parentContext": null
}
POST/api/yawn/compileAPI key or session

Compile free-text into a structured YawnJob. Searches existing yawns for matches, creates job + inbox item.

Request
{
  "message": "Fix the checkout flow bug",
  "email": "user@example.com",
  "context": { "yawn_id": "optional-uuid" }
}

Fundamental Questions

GET/api/yawn/{yawnId}/questionsAPI key or session

Get full coherence assessment — scores per category, overall percentage, next recommended question.

Response
{
  "assessment": {
    "categories": {
      "identity": { "answered": 2, "total": 3, "percentage": 67 },
      "position": { "answered": 1, "total": 4, "percentage": 25 },
      "state": { "answered": 3, "total": 5, "percentage": 60 },
      "completion": { "answered": 0, "total": 3, "percentage": 0 },
      "learning": { "answered": 0, "total": 4, "percentage": 0 },
      "risk": { "answered": 0, "total": 3, "percentage": 0 }
    },
    "overall": { "answered": 6, "total": 18, "percentage": 33 },
    "status": "critical",
    "nextQuestion": {
      "id": "completion.conditions",
      "question": "How will we know when this is done?"
    }
  }
}
POST/api/yawn/{yawnId}/questionsAPI key or session

Answer a fundamental question. Triggers coherence re-assessment and promotion evaluation.

Request
{
  "questionId": "identity.awakening",
  "answer": "A professional docs hub for developers and AI agents"
}
Response
{
  "success": true,
  "assessment": { "overall": { "percentage": 39 }, "status": "critical" },
  "promotion": {
    "currentLevel": 0,
    "promoted": false,
    "nextLevel": 1,
    "blockingCategories": ["position", "completion"]
  }
}

Experiments

POST/api/yawn/{yawnId}/experimentsSession

Create an experiment with hypothesis, success criteria, and branching logic.

Request
{
  "title": "Launch MVP experiment",
  "hypothesis": "If we ship MVP in 2 weeks, signups will increase",
  "steps": ["Build MVP", "Measure signups"],
  "success_criteria": ["10 signups", "Positive feedback"],
  "addresses_tensions": ["tension-uuid"]
}
POST/api/yawn/{yawnId}/experiments/{id}/answerSession

Answer an experiment (yes/no). Triggers branching via on_yes/on_no logic.

Request
{ "answer": "yes", "note": "We hit 15 signups" }

Evidence

POST/api/yawn/evidenceSession

Submit proof of an outcome. Links to a yawn and optionally an experiment.

Request
{
  "yawn_id": "uuid",
  "kind": "observation",
  "summary": "Reached 15 signups in first week",
  "value": 15,
  "metadata": { "source": "analytics" }
}
GET/api/yawn/evidence?yawn_id={id}Session

List all evidence for a yawn.

Enterprise Handshake

POST/api/enterprise/handshakeAPI key or session

Establish a bidirectional link between two yawns. Creates forward + inverse links, logs to inbox.

Request
{
  "source_slug": "my-docs",
  "target_slug": "yawn-ai-platform",
  "link_type": "references",
  "capabilities": ["read", "reference"]
}
Response (201)
{
  "success": true,
  "handshake": {
    "id": "abc123",
    "source": { "slug": "my-docs", "title": "My Docs" },
    "target": { "slug": "yawn-ai-platform", "title": "Yawn AI Platform" },
    "link_type": "references",
    "inverse_link_type": "referenced_by",
    "bidirectional": true,
    "auth_method": "api_key"
  }
}
GET/api/enterprise/handshake?source={slug}&target={slug}None

Check handshake status between two yawns. Returns connection status and links.

Approval

POST/api/agents/approveSession or token

Approve or reject a pending approval request. Can be called from the UI or via email one-click links.

Request
{
  "approvalId": "uuid",
  "action": "approve",
  "optionId": "optional"
}
GET/api/approve/{token}?action=approveToken (email link)

One-click approval from email. Token is auto-generated when approval notification is sent via SendGrid.

MCP Endpoints

POST/api/mcp/invokeSession

Invoke an MCP tool by name. Returns tool result.

Request
{
  "tool": "coherence-check",
  "args": { "yawnId": "uuid" },
  "context": { "userId": "uuid" }
}
GET/api/mcp/yawn/{yawnId}Public for system yawns

Get yawn state + available MCP tools. Public for system/shared scope yawns.

GET/api/mcp/skillsSession

List all MCP-compatible skills aggregated from .cursor/skills/, user_skills DB, and system skills.