# COCÓ Builder API by Good Stories -- Full Reference

> Complete API specification for AI agent integration. This document covers
> the **public API** endpoints. Additional internal endpoints (intelligence
> feeds, content management, meeting analysis, verification, and pattern
> search) are available but not documented here. See /docs for the full
> endpoint reference.

## Table of Contents

1. Overview
2. Base URL & Versioning
3. Authentication
4. Rate Limiting
5. Error Handling
6. Request/Response Schemas (Pydantic Models)
7. Endpoints (Full Detail)
   - GET /health
   - POST /v1/audit
   - POST /v1/summarize
   - POST /v1/rewrite
   - POST /v1/extract
   - POST /v1/search
   - GET /v1/usage/stats
8. Integration Patterns & Chaining
9. Common Workflows
10. Pricing Tiers

---

## 1. Overview

The COCÓ Builder API by Good Stories is a micro-SaaS HTTP API that provides six core
capabilities:

- **SEO Auditing** -- Deterministic on-page analysis (no AI, fast and consistent)
- **Text Summarization** -- AI-powered summarization in multiple styles
- **Content Rewriting** -- AI-powered tone transformation
- **Structured Data Extraction** -- AI-powered schema-based extraction from free text
- **Semantic Search** -- Vector similarity search over the knowledge base (pgvector + sentence-transformers)
- **Usage Analytics** -- API usage statistics per key and period

Content AI endpoints are powered by Anthropic Claude (model: claude-haiku-4-5-20251001).
Semantic search uses sentence-transformers/all-MiniLM-L6-v2 via HuggingFace Inference API.
The API accepts and returns JSON over HTTPS. CORS is enabled for all origins.

---

## 2. Base URL & Versioning

| Environment | Base URL                          |
|-------------|-----------------------------------|
| Production  | https://coco.goodstories.world    |

All authenticated endpoints are prefixed with `/v1/`. The current API version
is `1.0.0`.

---

## 3. Authentication

All `/v1/*` endpoints require an API key sent as an HTTP header:

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

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

The API key is validated on every request. If the key is missing, invalid, or
rate-limited, the API returns an appropriate HTTP error (see Error Handling).

---

## 4. Rate Limiting

Rate limits are enforced per API key on a daily basis. Counters reset at
midnight UTC each day.

| Tier     | Daily Limit | Behavior when exceeded                    |
|----------|-------------|-------------------------------------------|
| Free     | 10          | HTTP 429 returned                         |
| Pro      | 100         | HTTP 429 returned                         |
| Business | Unlimited   | No rate limiting (internal limit = -1)    |

When rate-limited, the response body contains:
```json
{
  "detail": "Daily rate limit reached (10 requests). Upgrade your plan at https://goodstories.world/pricing"
}
```

The `requests_today` counter is tracked per key and resets automatically when
the calendar day changes (UTC). There is no per-minute or per-second throttle --
only daily totals.

---

## 5. Error Handling

All errors are returned as JSON with a single `detail` field:

```json
{
  "detail": "Human-readable error message"
}
```

### HTTP Status Codes

| Code | Meaning                  | When it occurs                                          |
|------|--------------------------|---------------------------------------------------------|
| 200  | Success                  | Request completed successfully                          |
| 401  | Unauthorized             | Missing `X-API-Key` header                              |
| 403  | Forbidden                | Invalid API key (key not found in registry)             |
| 422  | Unprocessable Entity     | Validation error (bad input) or URL fetch failure       |
| 429  | Too Many Requests        | Daily rate limit exceeded for this API key              |
| 502  | Bad Gateway              | Upstream AI service (Claude) returned unparseable data  |
| 503  | Service Unavailable      | Anthropic API key not configured on the server          |

### Validation Errors (422)

FastAPI returns detailed validation errors for malformed requests:

```json
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "text"],
      "msg": "Field required",
      "input": {}
    }
  ]
}
```

### URL Fetch Errors (422 from /v1/audit)

When the audit endpoint cannot reach or fetch the target URL:

```json
{
  "detail": "Failed to fetch URL (HTTP 404)."
}
```
or:
```json
{
  "detail": "Could not reach URL: [connection error details]"
}
```

---

## 6. Request/Response Schemas (Pydantic Models)

### Enums

#### SummarizeStyle
```
"executive" | "academic" | "casual"
```

#### RewriteTone
```
"professional" | "friendly" | "persuasive" | "academic"
```

### Request Models

#### AuditRequest
```json
{
  "url": "string (required) -- Fully-qualified URL to audit (e.g. https://example.com)"
}
```
| Field | Type   | Required | Constraints       | Description                    |
|-------|--------|----------|-------------------|--------------------------------|
| url   | string | Yes      | Must be a URL     | Page URL to audit              |

#### SummarizeRequest
```json
{
  "text": "string (required) -- The text content to summarize",
  "style": "string (required) -- One of: executive, academic, casual"
}
```
| Field | Type            | Required | Constraints    | Description                         |
|-------|-----------------|----------|----------------|-------------------------------------|
| text  | string          | Yes      | min_length=1   | Text to summarize                   |
| style | SummarizeStyle  | Yes      | enum value     | executive, academic, or casual      |

#### RewriteRequest
```json
{
  "text": "string (required) -- The text content to rewrite",
  "tone": "string (required) -- One of: professional, friendly, persuasive, academic"
}
```
| Field | Type         | Required | Constraints    | Description                                |
|-------|--------------|----------|----------------|--------------------------------------------|
| text  | string       | Yes      | min_length=1   | Text to rewrite                            |
| tone  | RewriteTone  | Yes      | enum value     | professional, friendly, persuasive, academic |

#### ExtractRequest
```json
{
  "text": "string (required) -- Source text to extract from",
  "schema": "object (required) -- JSON object defining fields to extract"
}
```
| Field  | Type   | Required | Constraints    | Description                                              |
|--------|--------|----------|----------------|----------------------------------------------------------|
| text   | string | Yes      | min_length=1   | Source text containing the data                          |
| schema | object | Yes      | dict[str, Any] | Schema defining fields to extract and their types        |

Note: The JSON field is `schema` but internally it maps to `schema_definition`
via Pydantic alias. Always send `schema` in your request body.

#### SearchRequest
```json
{
  "query": "string (required) -- Natural language search query",
  "category": "string (optional) -- Filter by category",
  "limit": "integer (optional) -- Max results, default 10"
}
```
| Field    | Type    | Required | Constraints         | Description                                                           |
|----------|---------|----------|---------------------|-----------------------------------------------------------------------|
| query    | string  | Yes      | min_length=1        | Natural language search query                                         |
| category | string  | No       | null allowed        | Filter: soul, user, daily, projects, meetings, archive, intel         |
| limit    | integer | No       | 1-50, default 10    | Maximum number of results                                             |

### Response Models

#### HealthResponse
```json
{
  "status": "string -- Always 'ok'",
  "version": "string -- API version (e.g. '1.0.0')",
  "timestamp": "string -- ISO 8601 UTC timestamp"
}
```

#### AuditFinding
```json
{
  "category": "string -- e.g. 'Title Tag', 'Meta Description', 'Heading Structure', 'Content Length'",
  "score": "integer -- 0 to 100",
  "details": "string -- What was found",
  "recommendation": "string -- What to improve"
}
```
| Field          | Type    | Constraints | Description                     |
|----------------|---------|-------------|---------------------------------|
| category       | string  | --          | Audit category name             |
| score          | integer | 0-100       | Score for this category         |
| details        | string  | --          | Findings description            |
| recommendation | string  | --          | Actionable improvement advice   |

#### AuditResponse
```json
{
  "url": "string -- The audited URL",
  "overall_score": "integer -- 0 to 100 (average of all finding scores)",
  "findings": "array of AuditFinding -- Always 4 items",
  "fetched_at": "string -- ISO 8601 UTC timestamp"
}
```

The `findings` array always contains exactly 4 items in this order:
1. Title Tag
2. Meta Description
3. Heading Structure
4. Content Length

#### SummarizeResponse
```json
{
  "style": "string -- The style used (executive, academic, casual)",
  "condensed": "string -- Single-paragraph summary",
  "key_points": "array of string -- 3-5 bullet points",
  "takeaways": "array of string -- 1-3 actionable takeaways"
}
```

#### RewriteResponse
```json
{
  "tone": "string -- The tone used (professional, friendly, persuasive, academic)",
  "rewritten_text": "string -- The rewritten content"
}
```

#### ExtractResponse
```json
{
  "extracted": "object -- JSON object matching the requested schema"
}
```
Fields that cannot be found in the source text are returned as `null`.

#### SearchResult
```json
{
  "file_path": "string -- Path to the matched document",
  "category": "string -- Document category",
  "title": "string -- Document title",
  "tags": "array of string -- Associated tags",
  "summary": "string -- Document summary",
  "similarity": "float -- Cosine similarity score (0 to 1, higher = more similar)"
}
```

#### SearchResponse
```json
{
  "query": "string -- The original search query",
  "results": "array of SearchResult -- Ranked by similarity (descending)",
  "count": "integer -- Number of results returned"
}
```

#### UsageStatsResponse
```json
{
  "period": "string -- The requested period (today, week, month, all)",
  "total_requests": "integer -- Total API calls in the period",
  "by_endpoint": "object -- Breakdown of calls per endpoint path",
  "generated_at": "string -- ISO 8601 UTC timestamp"
}
```

#### ErrorResponse
```json
{
  "detail": "string -- Human-readable error message"
}
```

---

## 7. Endpoints (Full Detail)

### GET /health

**Tags:** Public
**Auth:** None
**Rate-limited:** No

Returns service health status.

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

**Response (200):**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-02-22T12:00:00.000000+00:00"
}
```

---

### POST /v1/audit

**Tags:** SEO
**Auth:** X-API-Key header (required)
**Rate-limited:** Yes (counts toward daily limit)

Performs an on-page SEO audit of the given URL. The server fetches the page
using `httpx` with a 15-second timeout, `User-Agent: GoodStoriesBot/1.0`, and
follows redirects. It then analyzes four categories using BeautifulSoup.

**Scoring Criteria:**

Title Tag:
- No title: score 0
- Under 30 chars: score 50
- 30-60 chars: score 100
- Over 60 chars: score 60

Meta Description:
- No meta description: score 0
- Under 120 chars: score 50
- 120-160 chars: score 100
- Over 160 chars: score 60

Heading Structure:
- Starts at 100, loses 40 for missing H1, 20 for multiple H1s, 20 for missing H2s
- Minimum score: 0

Content Length (word count of body text):
- 1000+ words: score 100
- 500-999 words: score 70
- 200-499 words: score 40
- Under 200 words: score 15

Overall score = rounded average of all four category scores.

**Example 1: Basic audit**
```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"}'
```

Response (200):
```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"
}
```

**Example 2: URL that cannot be reached**
```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://thisdomaindoesnotexist.example"}'
```

Response (422):
```json
{
  "detail": "Could not reach URL: [connection error details]"
}
```

**Example 3: URL returns HTTP error**
```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://httpstat.us/404"}'
```

Response (422):
```json
{
  "detail": "Failed to fetch URL (HTTP 404)."
}
```

---

### POST /v1/summarize

**Tags:** AI Content
**Auth:** X-API-Key header (required)
**Rate-limited:** Yes (counts toward daily limit)

Summarizes the provided text using Anthropic Claude. The AI is instructed to
return JSON with three fields: `condensed`, `key_points`, and `takeaways`.

**Example 1: Executive summary**
```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. However, implementation challenges remain, including data quality concerns, talent shortages, and integration complexity with legacy systems.",
    "style": "executive"
  }'
```

Response (200):
```json
{
  "style": "executive",
  "condensed": "AI adoption is driving competitive advantage through automation and predictive capabilities, but organizations must navigate data quality, talent, and legacy integration challenges to realize full value.",
  "key_points": [
    "AI is transforming core business operations",
    "Early adopters gain efficiency, cost, and satisfaction advantages",
    "Implementation barriers include data quality and talent gaps",
    "Legacy system integration remains a key challenge"
  ],
  "takeaways": [
    "Develop an AI adoption roadmap prioritizing high-impact use cases",
    "Invest in data infrastructure and AI talent acquisition"
  ]
}
```

**Example 2: Casual summary**
```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": "The James Webb Space Telescope has captured unprecedented images of distant galaxies, revealing star formation in its earliest stages. Scientists say these observations challenge existing models of galaxy evolution and could reshape our understanding of the early universe.",
    "style": "casual"
  }'
```

Response (200):
```json
{
  "style": "casual",
  "condensed": "The James Webb Telescope just took some mind-blowing photos of super distant galaxies, showing how stars were born way back in the early universe. Scientists are pretty excited because it might change what we thought we knew about how galaxies form.",
  "key_points": [
    "Webb telescope captured amazing images of distant galaxies",
    "The photos show early-stage star formation",
    "Current models of galaxy evolution might need updating"
  ],
  "takeaways": [
    "Keep an eye on Webb telescope discoveries -- they are rewriting astronomy"
  ]
}
```

**Example 3: Academic summary**
```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": "A randomized controlled trial of 500 participants demonstrated that daily mindfulness meditation for 8 weeks significantly reduced cortisol levels (p<0.01) and self-reported anxiety scores (p<0.001) compared to the control group.",
    "style": "academic"
  }'
```

Response (200):
```json
{
  "style": "academic",
  "condensed": "An RCT (n=500) found that an 8-week daily mindfulness meditation intervention produced statistically significant reductions in cortisol levels (p<0.01) and self-reported anxiety scores (p<0.001) relative to controls.",
  "key_points": [
    "Study design: randomized controlled trial with 500 participants",
    "Intervention: daily mindfulness meditation over 8 weeks",
    "Significant cortisol reduction (p<0.01)",
    "Significant anxiety score reduction (p<0.001)"
  ],
  "takeaways": [
    "Mindfulness meditation shows robust evidence for stress and anxiety reduction",
    "Consider incorporating mindfulness protocols in clinical anxiety management"
  ]
}
```

---

### POST /v1/rewrite

**Tags:** AI Content
**Auth:** X-API-Key header (required)
**Rate-limited:** Yes (counts toward daily limit)

Rewrites the provided text in the specified tone using Anthropic Claude.
The AI preserves the original meaning and key information.

**Example 1: Professional tone**
```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"
  }'
```

Response (200):
```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."
}
```

**Example 2: Friendly tone**
```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": "The quarterly financial report indicates a 15% decline in revenue attributed to market contraction and supply chain disruptions.",
    "tone": "friendly"
  }'
```

Response (200):
```json
{
  "tone": "friendly",
  "rewritten_text": "Hey there! So our latest quarterly numbers show revenue dipped about 15% -- mostly because the market tightened up and we hit some supply chain bumps. Nothing we can't work through together!"
}
```

**Example 3: Persuasive tone**
```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 software has project management features and costs $29 per month.",
    "tone": "persuasive"
  }'
```

Response (200):
```json
{
  "tone": "persuasive",
  "rewritten_text": "Imagine managing every project with effortless precision -- that is exactly what our software delivers. For just $29 a month, you get a complete project management powerhouse that pays for itself in the time you save."
}
```

**Example 4: Academic tone**
```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": "Eating too much sugar is bad for you and can make you gain weight.",
    "tone": "academic"
  }'
```

Response (200):
```json
{
  "tone": "academic",
  "rewritten_text": "Excessive dietary sugar consumption has been consistently associated with adverse health outcomes, including increased adiposity and elevated risk of metabolic syndrome, as documented in numerous epidemiological studies."
}
```

---

### POST /v1/extract

**Tags:** AI Content
**Auth:** X-API-Key header (required)
**Rate-limited:** Yes (counts toward daily limit)

Extracts structured data from unstructured text using Anthropic Claude. You
define the desired output schema as a JSON object where keys are field names
and values describe the expected types. The AI returns a JSON object matching
your schema, with `null` for any fields it cannot find.

**Example 1: Contact information extraction**
```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"
    }
  }'
```

Response (200):
```json
{
  "extracted": {
    "name": "Jane Doe",
    "title": "CTO",
    "company": "TechFlow Inc",
    "email": "jane@techflow.io",
    "phone": "555-0142"
  }
}
```

**Example 2: Product information extraction**
```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": "The new MacBook Pro 16-inch starts at $2,499 and features the M4 Max chip with 36GB unified memory. Available in Space Black and Silver. Battery life rated at up to 22 hours.",
    "schema": {
      "product_name": "string",
      "price": "string",
      "processor": "string",
      "memory": "string",
      "colors": "array of strings",
      "battery_life": "string"
    }
  }'
```

Response (200):
```json
{
  "extracted": {
    "product_name": "MacBook Pro 16-inch",
    "price": "$2,499",
    "processor": "M4 Max",
    "memory": "36GB unified memory",
    "colors": ["Space Black", "Silver"],
    "battery_life": "up to 22 hours"
  }
}
```

**Example 3: Event details extraction**
```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": "Join us for the Annual Developer Summit on March 15-17, 2026 at the San Francisco Convention Center. Early bird tickets are $299 (regular $499). Keynote by Sarah Chen, VP of Engineering at CloudScale.",
    "schema": {
      "event_name": "string",
      "dates": "string",
      "location": "string",
      "early_bird_price": "string",
      "regular_price": "string",
      "keynote_speaker": "string",
      "keynote_speaker_title": "string",
      "keynote_speaker_company": "string"
    }
  }'
```

Response (200):
```json
{
  "extracted": {
    "event_name": "Annual Developer Summit",
    "dates": "March 15-17, 2026",
    "location": "San Francisco Convention Center",
    "early_bird_price": "$299",
    "regular_price": "$499",
    "keynote_speaker": "Sarah Chen",
    "keynote_speaker_title": "VP of Engineering",
    "keynote_speaker_company": "CloudScale"
  }
}
```

**Example 4: Handling missing fields**
```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": "Bob works at Acme.",
    "schema": {
      "name": "string",
      "company": "string",
      "email": "string",
      "phone": "string"
    }
  }'
```

Response (200):
```json
{
  "extracted": {
    "name": "Bob",
    "company": "Acme",
    "email": null,
    "phone": null
  }
}
```

---

### POST /v1/search

**Tags:** Search
**Auth:** X-API-Key header (required)
**Rate-limited:** Yes (counts toward daily limit)

Searches the memory index using semantic similarity. The query text is embedded
using sentence-transformers/all-MiniLM-L6-v2 (384 dimensions) via the HuggingFace
Inference API, then matched against pre-computed embeddings in the memory_index
table using pgvector cosine similarity.

Results are ranked by similarity score (highest first). Optionally filter by
category to narrow results to a specific knowledge domain.

**Available categories:** soul, user, daily, projects, meetings, archive, intel

**Example 1: General search**
```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", "limit": 5}'
```

Response (200):
```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
    },
    {
      "file_path": "projects/coco-api.md",
      "category": "projects",
      "title": "COCÓ API Service",
      "tags": ["api", "fastapi", "micro-saas"],
      "summary": "Production API with 4 AI-powered endpoints...",
      "similarity": 0.7156
    }
  ],
  "count": 2
}
```

**Example 2: Filtered by category**
```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": "supply chain optimization", "category": "intel", "limit": 3}'
```

Response (200):
```json
{
  "query": "supply chain optimization",
  "results": [],
  "count": 0
}
```

Note: Empty results indicate no matching entries above the similarity threshold
in the specified category.

---

### GET /v1/usage/stats

**Tags:** Analytics
**Auth:** X-API-Key header (required)
**Rate-limited:** No (does not count toward daily limit)

Returns API usage statistics for the authenticated key. Requires Supabase-backed
API keys to be enabled on the server (USE_SUPABASE_KEYS=true).

**Query Parameters:**

| Parameter | Type   | Required | Default | Description                          |
|-----------|--------|----------|---------|--------------------------------------|
| period    | string | No       | today   | One of: today, week, month, all      |

- `today` -- Usage since midnight UTC today
- `week` -- Usage since Monday midnight UTC of the current week
- `month` -- Usage since the 1st of the current month (midnight UTC)
- `all` -- All-time usage for this API key

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

Response (200):
```json
{
  "period": "today",
  "total_requests": 7,
  "by_endpoint": {
    "/v1/summarize": 3,
    "/v1/audit": 2,
    "/v1/search": 2
  },
  "generated_at": "2026-02-25T15:30:00.000000+00:00"
}
```

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

Response (200):
```json
{
  "period": "month",
  "total_requests": 142,
  "by_endpoint": {
    "/v1/summarize": 58,
    "/v1/search": 34,
    "/v1/audit": 28,
    "/v1/rewrite": 14,
    "/v1/extract": 8
  },
  "generated_at": "2026-02-25T15:30:00.000000+00:00"
}
```

---

## 8. Integration Patterns & Chaining

### Pattern 1: Audit Then Rewrite

Audit a page's SEO, then use the rewrite endpoint to improve weak meta
descriptions or titles.

```
Step 1: POST /v1/audit  {"url": "https://example.com"}
Step 2: Read findings[1] (Meta Description) -- if score < 100, take the
        current meta description text and POST /v1/rewrite with tone
        "persuasive" to generate an improved version.
```

### Pattern 2: Extract Then Summarize

Extract structured data from a document, then summarize the original text.

```
Step 1: POST /v1/extract  {"text": "...", "schema": {...}}
Step 2: POST /v1/summarize {"text": "...", "style": "executive"}
Step 3: Combine the structured data with the summary for a complete brief.
```

### Pattern 3: Summarize Then Rewrite

Summarize long content, then rewrite the summary in a different tone.

```
Step 1: POST /v1/summarize {"text": "long article...", "style": "executive"}
Step 2: POST /v1/rewrite {"text": response.condensed, "tone": "friendly"}
```

### Pattern 4: Batch SEO Audit

Audit multiple pages in sequence and aggregate scores.

```
For each URL in [url1, url2, url3]:
    POST /v1/audit {"url": current_url}
    Store overall_score and findings
Compute average overall_score across all pages.
Identify the lowest-scoring categories across the site.
```

### Pattern 5: Content Pipeline

Full content processing pipeline for a CMS integration.

```
Step 1: POST /v1/extract -- Pull metadata from raw content
Step 2: POST /v1/summarize -- Generate executive summary
Step 3: POST /v1/rewrite (tone: "professional") -- Polish for publication
Step 4: POST /v1/audit -- Verify the published page meets SEO standards
```

### Pattern 6: Search Then Summarize

Find relevant knowledge entries and summarize them for a briefing.

```
Step 1: POST /v1/search {"query": "competitor pricing strategies", "category": "intel"}
Step 2: Concatenate the summaries from top results
Step 3: POST /v1/summarize {"text": combined_summaries, "style": "executive"}
```

### Pattern 7: RAG (Retrieval-Augmented Generation)

Use semantic search as the retrieval step in a RAG pipeline.

```
Step 1: POST /v1/search {"query": user_question, "limit": 5}
Step 2: Feed the returned summaries as context to your LLM prompt
Step 3: Generate a grounded answer using the retrieved knowledge
```

---

## 9. Common Workflows

### Workflow: SEO Improvement for a Website

Goal: Audit a site and generate improved copy for any weak areas.

```python
import requests

API = "https://coco.goodstories.world"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here"
}

# Step 1: Audit the page
audit = requests.post(f"{API}/v1/audit", json={"url": "https://mysite.com"}, headers=HEADERS).json()

print(f"Overall SEO score: {audit['overall_score']}/100")

# Step 2: Check each finding
for finding in audit["findings"]:
    if finding["score"] < 70:
        print(f"Weak area: {finding['category']} (score: {finding['score']})")
        print(f"  Issue: {finding['details']}")
        print(f"  Fix: {finding['recommendation']}")

        # Step 3: If meta description is weak, generate a better one
        if finding["category"] == "Meta Description" and "too short" in finding["details"]:
            rewrite = requests.post(f"{API}/v1/rewrite", json={
                "text": finding["details"],
                "tone": "persuasive"
            }, headers=HEADERS).json()
            print(f"  Suggested rewrite: {rewrite['rewritten_text']}")
```

### Workflow: Content Ingestion and Structuring

Goal: Take raw unstructured text (e.g., from a PDF or email), extract key
fields, and produce a polished summary.

```python
import requests

API = "https://coco.goodstories.world"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here"
}

raw_text = """
Meeting Notes - Q1 Planning
Date: January 15, 2026
Attendees: Sarah Chen (VP Eng), Marcus Johnson (PM), Lisa Park (Design Lead)
Budget: $450,000 for Q1 initiatives
Key decision: Launch new onboarding flow by March 1
Action items: Marcus to draft PRD by Jan 22, Lisa to deliver mockups by Feb 1
"""

# Step 1: Extract structured data
extracted = requests.post(f"{API}/v1/extract", json={
    "text": raw_text,
    "schema": {
        "meeting_type": "string",
        "date": "string",
        "attendees": "array of objects with name and role",
        "budget": "string",
        "key_decisions": "array of strings",
        "action_items": "array of objects with owner, task, and deadline"
    }
}, headers=HEADERS).json()

print("Structured data:", extracted["extracted"])

# Step 2: Summarize for stakeholders
summary = requests.post(f"{API}/v1/summarize", json={
    "text": raw_text,
    "style": "executive"
}, headers=HEADERS).json()

print("Executive summary:", summary["condensed"])
print("Key points:", summary["key_points"])
```

### Workflow: Multi-Tone Content Generation

Goal: Take a single piece of content and produce versions for different
audiences.

```python
import requests

API = "https://coco.goodstories.world"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here"
}

original = "We are launching a new feature that lets users automate their reporting workflows, saving an average of 3 hours per week."

tones = ["professional", "friendly", "persuasive", "academic"]

for tone in tones:
    result = requests.post(f"{API}/v1/rewrite", json={
        "text": original,
        "tone": tone
    }, headers=HEADERS).json()
    print(f"\n[{tone.upper()}]")
    print(result["rewritten_text"])
```

---

## 10. Pricing Tiers

| Tier     | Price    | Daily API Calls | Support            |
|----------|----------|-----------------|---------------------|
| Free     | $0/mo    | 10              | Community           |
| Pro      | $19/mo   | 100             | Priority            |
| Business | $49/mo   | Unlimited       | Dedicated           |

All tiers have access to all six endpoints. There is no per-endpoint pricing
difference. Rate limits are per API key, not per endpoint.

Upgrade at: https://goodstories.world/pricing

---

## Appendix: Content-Type Requirements

All POST requests must include:
```
Content-Type: application/json
```

All responses are returned as:
```
Content-Type: application/json
```

The `/llms.txt` and `/llms-full.txt` endpoints return:
```
Content-Type: text/plain; charset=utf-8
```

---

## Appendix: HTTP Methods Summary

| Method | Path            | Auth Required | Description                    |
|--------|-----------------|---------------|--------------------------------|
| GET    | /               | No            | Landing page (HTML)            |
| GET    | /health         | No            | Service health check           |
| GET    | /docs           | No            | Canonical builder docs         |
| GET    | /llms.txt       | No            | LLM-friendly API summary       |
| GET    | /llms-full.txt  | No            | LLM-friendly full reference    |
| POST   | /v1/audit       | Yes           | SEO audit                      |
| POST   | /v1/summarize   | Yes           | Text summarization             |
| POST   | /v1/rewrite     | Yes           | Content rewriting              |
| POST   | /v1/extract     | Yes           | Structured data extraction     |
| POST   | /v1/search      | Yes           | Semantic similarity search     |
| GET    | /v1/usage/stats | Yes           | API usage analytics            |