# COCÓ Builder API by Good Stories

> Public builder endpoints for workflows, tools, and AI integrations under COCÓ.

## Scope

This document covers the **public API** endpoints available to external developers and AI agents. Additional internal endpoints (intelligence feeds, content management, meeting analysis, verification, and pattern search) exist but are not covered here. For the full endpoint reference, see /docs.

## Overview

The public COCÓ Builder API by Good Stories provides endpoints for content operations and knowledge search: SEO auditing, text summarization, content rewriting, structured data extraction, semantic search, pattern search, and usage analytics. It is designed for developers, AI agents, and automation pipelines that need reliable, JSON-in/JSON-out content intelligence over HTTP. AI-powered endpoints use Anthropic Claude for content tasks and sentence-transformers for semantic search.

## Base URL

- Production: https://coco.goodstories.world
- Local development: run the API locally on port 8800

## Authentication

All `/v1/*` endpoints require an API key passed via the `X-API-Key` HTTP header.

```
X-API-Key: your-api-key-here
```

Public endpoints (`GET /health`, `GET /`) do not require authentication.

## Machine Payments Protocol (MPP)

This API supports MPP (v1.0). AI agents can pay per call without an API key.

**Flow:**

1. Request any `/v1/*` endpoint without auth → receive HTTP 402 with pricing
2. `POST /v1/mpp/checkout` with `{"endpoint": "/v1/audit", "amount_cents": 100}` → get Stripe PaymentIntent
3. Confirm the PaymentIntent via Stripe API
4. Resend original request with headers: `X-MPP-Method: stripe` + `X-MPP-Credential: pi_xxx`

**Sessions (recommended for multiple calls):**

1. `POST /v1/mpp/sessions` with `{"funded_cents": 500}` → get session token + PaymentIntent
2. Confirm PI via Stripe
3. Use `X-MPP-Session: mpp_sess_xxx` header on all subsequent requests (balance deducted per call)
4. `GET /v1/mpp/sessions/{id}` to check remaining balance

**Pricing:** /v1/audit $0.05, /v1/summarize $0.08, /v1/content/generate $0.15, /v1/video/generate $0.50
**Minimum single payment:** $1.00 (covers Stripe processing fees)
**Discovery:** `GET /.well-known/mpp.json`

## Endpoints

### GET /health

Returns service health status. No authentication required.

**Example request:**
```bash
curl https://coco.goodstories.world/health
```

**Example response:**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-02-22T12:00:00.000000+00:00"
}
```

---

### POST /v1/audit

Perform an on-page SEO audit of any publicly accessible URL. Fetches the page and analyzes title tags, meta descriptions, heading structure, and content length. Returns individual category scores (0-100) and an overall score.

This endpoint does NOT use AI -- it performs deterministic HTML analysis, so it is fast and consistent.

**Parameters:**

| Field | Type   | Required | Description                          |
|-------|--------|----------|--------------------------------------|
| url   | string | Yes      | Fully-qualified URL to audit         |

**Example request:**
```bash
curl -X POST https://coco.goodstories.world/v1/audit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"url": "https://example.com"}'
```

**Example response:**
```json
{
  "url": "https://example.com",
  "overall_score": 53,
  "findings": [
    {
      "category": "Title Tag",
      "score": 50,
      "details": "Title \"Example Domain\" (14 chars) is too short.",
      "recommendation": "Expand your title to 30-60 characters for better click-through rates."
    },
    {
      "category": "Meta Description",
      "score": 0,
      "details": "No meta description found.",
      "recommendation": "Add a meta description of 120-160 characters summarizing the page."
    },
    {
      "category": "Heading Structure",
      "score": 80,
      "details": "H1: 1, H2: 0, H3: 0. No <h2> tags found.",
      "recommendation": "Add <h2> sub-headings to structure your content."
    },
    {
      "category": "Content Length",
      "score": 15,
      "details": "Page has only 28 words -- very thin content.",
      "recommendation": "This page needs significantly more content to rank well."
    }
  ],
  "fetched_at": "2026-02-22T12:00:00.000000+00:00"
}
```

---

### POST /v1/summarize

Summarize any text content in one of three styles. Returns a condensed paragraph, key points, and actionable takeaways. Powered by Anthropic Claude.

**Parameters:**

| Field | Type   | Required | Description                                        |
|-------|--------|----------|----------------------------------------------------|
| text  | string | Yes      | The text content to summarize (min 1 character)    |
| style | string | Yes      | One of: `executive`, `academic`, `casual`          |

**Example request:**
```bash
curl -X POST https://coco.goodstories.world/v1/summarize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "text": "Artificial intelligence has transformed the way businesses operate. From automating customer service to predicting market trends, AI tools are becoming essential. Companies that adopt AI early see significant competitive advantages in efficiency, cost reduction, and customer satisfaction.",
    "style": "executive"
  }'
```

**Example response:**
```json
{
  "style": "executive",
  "condensed": "AI is rapidly becoming a core business tool, driving competitive advantages through automation, predictive analytics, and improved customer experiences for early adopters.",
  "key_points": [
    "AI is transforming business operations across industries",
    "Key applications include customer service automation and market prediction",
    "Early adopters gain competitive advantages",
    "Benefits span efficiency, cost reduction, and customer satisfaction"
  ],
  "takeaways": [
    "Prioritize AI adoption to maintain competitive positioning",
    "Focus on high-impact areas: customer service and market analytics"
  ]
}
```

---

### POST /v1/rewrite

Rewrite content in a specified tone while preserving the original meaning and key information. Powered by Anthropic Claude.

**Parameters:**

| Field | Type   | Required | Description                                              |
|-------|--------|----------|----------------------------------------------------------|
| text  | string | Yes      | The text content to rewrite (min 1 character)            |
| tone  | string | Yes      | One of: `professional`, `friendly`, `persuasive`, `academic` |

**Example request:**
```bash
curl -X POST https://coco.goodstories.world/v1/rewrite \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "text": "Our product is really good and you should buy it because it helps a lot with stuff.",
    "tone": "professional"
  }'
```

**Example response:**
```json
{
  "tone": "professional",
  "rewritten_text": "Our solution delivers measurable value across key operational areas. We invite you to explore how it can enhance your workflow and drive meaningful results for your organization."
}
```

---

### POST /v1/extract

Extract structured data from unstructured text. You define the schema (field names and types) and the AI pulls matching data from the text. Powered by Anthropic Claude.

**Parameters:**

| Field  | Type   | Required | Description                                                     |
|--------|--------|----------|-----------------------------------------------------------------|
| text   | string | Yes      | The source text to extract data from (min 1 character)          |
| schema | object | Yes      | JSON object describing fields to extract (e.g. `{"name": "string", "email": "string"}`) |

**Example request:**
```bash
curl -X POST https://coco.goodstories.world/v1/extract \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "text": "Hi, I am Jane Doe, CTO at TechFlow Inc. Reach me at jane@techflow.io or call 555-0142.",
    "schema": {
      "name": "string",
      "title": "string",
      "company": "string",
      "email": "string",
      "phone": "string"
    }
  }'
```

**Example response:**
```json
{
  "extracted": {
    "name": "Jane Doe",
    "title": "CTO",
    "company": "TechFlow Inc",
    "email": "jane@techflow.io",
    "phone": "555-0142"
  }
}
```

### POST /v1/search

Search the memory index using semantic similarity. Embeds the query with sentence-transformers/all-MiniLM-L6-v2, then finds the most similar entries using pgvector cosine similarity. Useful for AI agents that need to retrieve relevant knowledge, notes, or intelligence entries.

**Parameters:**

| Field    | Type   | Required | Description                                                           |
|----------|--------|----------|-----------------------------------------------------------------------|
| query    | string | Yes      | Natural language search query (min 1 character)                       |
| category | string | No       | Filter by category: soul, user, daily, projects, meetings, archive, intel |
| limit    | int    | No       | Max results to return (1-50, default 10)                              |

**Example request:**
```bash
curl -X POST https://coco.goodstories.world/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "query": "AI product launch strategy",
    "category": "intel",
    "limit": 5
  }'
```

**Example response:**
```json
{
  "query": "AI product launch strategy",
  "results": [
    {
      "file_path": "daily/2026-02-20-intel.md",
      "category": "intel",
      "title": "Claude Code projected to write 25-50% of GitHub code",
      "tags": ["anthropic", "ai-tools", "developer-tools"],
      "summary": "Claude Code adoption accelerating in developer workflows...",
      "similarity": 0.8234
    }
  ],
  "count": 1
}
```

---

### GET /v1/usage/stats

Get API usage statistics for the authenticated key. Requires Supabase-backed API keys to be enabled.

**Parameters (query string):**

| Field  | Type   | Required | Description                                  |
|--------|--------|----------|----------------------------------------------|
| period | string | No       | One of: `today`, `week`, `month`, `all` (default: `today`) |

**Example request:**
```bash
curl "https://coco.goodstories.world/v1/usage/stats?period=week" \
  -H "X-API-Key: your-api-key-here"
```

**Example response:**
```json
{
  "period": "week",
  "total_requests": 42,
  "by_endpoint": {
    "/v1/summarize": 18,
    "/v1/search": 12,
    "/v1/audit": 8,
    "/v1/rewrite": 4
  },
  "generated_at": "2026-02-25T12:00:00.000000+00:00"
}
```

---

## Story Patterns API

Search a database of narrative patterns extracted from news and longform articles.
Patterns are categorized by type: archetype, conflict, structure, hook, angle, tension, beat.

### POST /v1/patterns/search

Search for narrative patterns using semantic similarity and/or filters.

**Parameters (JSON body):**

| Field          | Type   | Required | Description                                              |
|----------------|--------|----------|----------------------------------------------------------|
| query          | string | No*      | Natural language semantic search query                   |
| category       | string | No*      | Filter: archetype, conflict, structure, hook, angle, tension, beat |
| name           | string | No*      | Filter by pattern name (partial match)                   |
| source         | string | No*      | Filter by article source (partial match)                 |
| min_confidence | int    | No       | Minimum confidence score 1-5 (default: 3)                |
| limit          | int    | No       | Max results 1-50 (default: 20)                           |
| threshold      | float  | No       | Min similarity score 0-1 (default: 0.3)                  |

*At least one of query, category, name, or source is required.

**Example request:**
```bash
curl -X POST "https://coco.goodstories.world/v1/patterns/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: demo-key-good-stories-2026" \
  -d '{"query": "underdog overcoming odds", "limit": 5}'
```

---

### GET /v1/patterns/stats

Get overview statistics for the Story Patterns database.

**Example request:**
```bash
curl "https://coco.goodstories.world/v1/patterns/stats" \
  -H "X-API-Key: demo-key-good-stories-2026"
```

---

### GET /v1/patterns/categories

List the 7 narrative pattern categories with descriptions and examples.

**Example request:**
```bash
curl "https://coco.goodstories.world/v1/patterns/categories" \
  -H "X-API-Key: demo-key-good-stories-2026"
```

---

### GET /v1/patterns/{id}

Fetch a single narrative pattern by UUID.

---

## Pricing

| Tier     | Price   | Daily Limit          |
|----------|---------|----------------------|
| Free     | $0/mo   | 10 API calls/day     |
| Pro      | $19/mo  | 100 API calls/day    |
| Business | $49/mo  | Unlimited API calls  |

All tiers have access to all endpoints. Rate limits reset daily at midnight UTC.

## Quick Start

```bash
# 1. Get your API key from the dashboard

# 2. Test the health endpoint (no auth needed)
curl https://coco.goodstories.world/health

# 3. Run your first SEO audit
curl -X POST https://coco.goodstories.world/v1/audit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"url": "https://example.com"}'

# 4. Summarize some text
curl -X POST https://coco.goodstories.world/v1/summarize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"text": "Your article text here...", "style": "executive"}'
```

## Links

- Docs (canonical): /docs
- Legacy docs route: /redoc (redirects to /docs)
- Full API Reference (for agents): /llms-full.txt