# Good Stories AI Tools API

> AI-powered tools for content, SEO, and data -- one API call away.

## Overview

The Good Stories AI Tools API provides four endpoints for content operations: SEO auditing, text summarization, content rewriting, and structured data extraction. It is designed for developers, AI agents, and automation pipelines that need reliable, JSON-in/JSON-out content intelligence over HTTP. All AI-powered endpoints use Anthropic Claude under the hood.

## Base URL

- Production: https://api.goodstoriesllc.com
- Local development: http://localhost: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.

## Endpoints

### GET /health

Returns service health status. No authentication required.

**Example request:**
```bash
curl https://api.goodstoriesllc.com/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://api.goodstoriesllc.com/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://api.goodstoriesllc.com/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://api.goodstoriesllc.com/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://api.goodstoriesllc.com/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"
  }
}
```

## 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://api.goodstoriesllc.com/health

# 3. Run your first SEO audit
curl -X POST https://api.goodstoriesllc.com/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://api.goodstoriesllc.com/v1/summarize \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"text": "Your article text here...", "style": "executive"}'
```

## Links

- Interactive Docs: /docs
- ReDoc Reference: /redoc
- Full API Reference (for agents): /llms-full.txt