# Wordflows AI — Complete Agent Integration Documentation

> Wordflows is a content brain and voice intelligence platform. It captures an organization's complete identity — brand, voice, strategy, knowledge — and serves it as structured markdown that AI agents inject directly into their prompts for contextually accurate content creation.

## What problem does Wordflows solve?

AI agents writing content for a business lack persistent organizational context. Every session starts from zero. The agent doesn't know the brand voice, content strategy, existing published posts, offers to promote, or writing style rules. Wordflows solves this by storing all organizational context and serving it through a step-aware API.

## How does the Agent Context API work?

The API returns structured markdown — not JSON data models. Agents inject the response directly into their system prompts or user messages. Each endpoint returns only the context relevant to a specific content creation phase, minimizing token waste.

Authentication uses an `X-API-Key` header. Keys are created from the Wordflows dashboard and scoped to the user — one key gives access to all organizations the user belongs to. Each context endpoint requires an `organization_id` query parameter.

Base URL: `https://wordflowsai.com/api/agent`

---

## API Reference

### GET /api/agent/orgs

Returns all organizations the authenticated user has access to.

**When to use:** First call — the agent needs to know which organizations are available and their IDs.

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  https://wordflowsai.com/api/agent/orgs
```

```json
[
  {"id": 42, "name": "Acme Corp", "website_url": "https://acme.com", "industry": "technology"},
  {"id": 99, "name": "My Blog", "website_url": "https://myblog.com", "industry": "media"}
]
```

---

### GET /api/agent/context/discovery?organization_id=X

Returns context for topic discovery and content planning.

**When to use:** The agent is deciding what to write about.

**What it returns:**
- Organization identity (name, tagline, industry, website)
- Content strategy and guidelines
- Content pillars and target audience
- Competitive positioning and differentiators
- Audience personas
- Existing blog posts with titles and URLs (for deduplication)
- Learned organizational preferences

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/discovery?organization_id=42"
```

```json
{
  "step": "discovery",
  "organization_id": 42,
  "markdown": "## Organization\nName: Acme Corp\nIndustry: technology\n\n## Content Strategy\nFocus on developer education...\n\n## Existing Blog Posts\n- How to Build REST APIs [https://acme.com/blog/rest-apis]\n- GraphQL vs REST [https://acme.com/blog/graphql-vs-rest]"
}
```

---

### GET /api/agent/context/brief?organization_id=X

Returns context for defining a specific content piece.

**When to use:** The agent is creating a content brief — defining title, audience, tone, keywords, and CTAs for one piece.

**What it returns:**
- Organization identity
- Full brand guide (tone, personality, voice description, messaging, positioning)
- Style guide summary (writing style, formats, SEO preferences)
- Active offers with descriptions and URLs
- Active CTAs with placement and frequency rules
- Blog post inventory for internal linking opportunities

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/brief?organization_id=42"
```

---

### GET /api/agent/context/outline?organization_id=X

Returns context for structuring content.

**When to use:** The agent is creating an outline — defining headings, section flow, and structural patterns.

**What it returns:**
- Heading structure guidelines (H1/H2/H3 conventions)
- Introduction and conclusion guidelines
- Preferred content formats and lengths
- Paragraph and sentence structure preferences
- Content pillars and tone direction
- Brand personality traits

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/outline?organization_id=42"
```

---

### GET /api/agent/context/section?organization_id=X

Returns context for writing individual content sections.

**When to use:** The agent is generating the actual text of a section. This is the most token-heavy endpoint — it includes full voice writing instructions.

**Query parameters:**
- `topic` (optional) — When provided, retrieves relevant knowledge base content by topic similarity

**What it returns:**
- Voice writing instructions tailored to the organization's unique style
- Style rules (grammar, punctuation, list style, jargon policy)
- Brand constraints (dos/don'ts, prohibited words, preferred terminology)
- Relevant knowledge base content (if topic provided)

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/section?organization_id=42&topic=kubernetes%20deployment"
```

```json
{
  "step": "section",
  "organization_id": 42,
  "markdown": "## Writing Voice (DNA)\n[Detailed voice instructions tailored to this organization's writing style...]\n\n## Style Rules\nGrammar: american_english\nOxford Comma: Yes\n\n## Brand Constraints\nDo: Use concrete examples, cite data\nDon't: Use jargon without defining it\nProhibited Words: synergy, leverage, delve\n\n## Knowledge Base Context\n### Reference 1 (Category: technical)\nOur Kubernetes deployment uses..."
}
```

---

### GET /api/agent/context/review?organization_id=X

Returns context for content quality and voice compliance checking.

**When to use:** The agent is reviewing generated content for voice adherence and AI tells.

**What it returns:**
- Full voice instructions for compliance checking
- Voice-specific writing patterns and building blocks
- Rules for detecting and removing AI-sounding content
- Quantitative baselines the author's writing must match
- Brand constraints (dos/don'ts, prohibited words)
- Common AI-tell phrases to flag and replace

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/review?organization_id=42"
```

---

### GET /api/agent/context/full?organization_id=X

Returns the complete unified context dump.

**When to use:** The agent wants all organizational context in a single call and will select relevant sections itself. Useful for general-purpose agents that handle the full content workflow.

**What it returns:** Everything from all other endpoints, deduplicated and organized.

```bash
curl -H "X-API-Key: wf_ak_your_key_here" \
  "https://wordflowsai.com/api/agent/context/full?organization_id=42"
```

---

## Response Format

All endpoints return the same JSON structure:

```json
{
  "step": "discovery | brief | outline | section | review | full",
  "organization_id": 42,
  "markdown": "## Section Header\nContent here..."
}
```

The `markdown` field contains structured markdown with `##` headers, bullet lists, and key-value formatting. It is designed for direct injection into LLM prompts.

---

## Authentication

### Creating an API key

API keys are managed from the Wordflows dashboard. Keys are scoped to a single organization.

**Endpoint:** `POST /organizations/api-keys` (requires JWT auth)

```json
{
  "name": "Production Agent"
}
```

**Response (shown once):**

```json
{
  "id": 1,
  "name": "Production Agent",
  "key_prefix": "wf_ak_ab12cd",
  "raw_key": "wf_ak_ab12cd34ef56gh78ij90kl12mn34op56qr",
  "message": "Store this key securely — it will not be shown again."
}
```

### Using the API key

Include the key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: wf_ak_ab12cd34ef56gh78ij90kl12mn34op56qr" \
  https://wordflowsai.com/api/agent/context/discovery
```

### Key management

- `GET /organizations/api-keys` — List keys (prefixes only)
- `DELETE /organizations/api-keys/{id}` — Revoke a key

---

## What is Voice DNA?

Voice DNA is a deep writing profile that captures exactly how a specific author or brand writes. It goes far beyond "tone" descriptions like "be professional and friendly."

### How Voice DNA is created

**From existing writing samples:** Upload blog posts, articles, or website content. Wordflows analyzes the writing and generates precise, actionable instructions that make any LLM write in that same style.

**From scratch (Voice Genesis):** Describe the voice you want. Wordflows builds a complete voice profile from your description — producing the same detailed writing instructions as if it had analyzed years of real writing samples.

### What makes Voice DNA different

- Content that sounds like the author actually wrote it — not "AI pretending to be professional"
- Catches and eliminates generic AI-sounding phrases automatically
- Preserves the writer's natural rhythm and pacing across any topic
- Maintains consistent voice whether writing a blog post, email, or landing page
- Works with any LLM — the instructions are model-agnostic structured markdown
- Built from deep writing analysis, not adjective checklists like "be confident and friendly"

### How agents use Voice DNA

The `/section` endpoint returns voice writing instructions in the `markdown` response. Inject this into your content generation prompt. The `/review` endpoint returns compliance-checking data for post-generation voice verification.

---

## What is the Content Brain?

The Content Brain is the unified organizational knowledge layer. It assembles:

- **Organization identity** — Name, tagline, industry, website, language
- **Content strategy** — Goals, guidelines, content pillars
- **Brand guide** — Tone, personality, messaging, positioning, audience personas, dos/don'ts, prohibited words
- **Style guide** — Writing style, grammar rules, heading structure, content length preferences, SEO settings
- **Offers** — Products, services, courses with descriptions, URLs, and pricing
- **CTAs** — Call-to-action text, placement rules, and frequency preferences
- **Blog inventory** — Existing posts with titles, URLs, and categories
- **Knowledge base** — Embedded content chunks from website pages and uploaded materials
- **Organizational memories** — Learned preferences from past conversations (corrections, facts, instructions)

The Agent Context API serves slices of this brain at each step of content creation.

---

## Integration Patterns

### Single-agent workflow

One agent handles the full content pipeline. Call `/full` once at the start and include the context in the system prompt.

```python
import httpx

headers = {"X-API-Key": "wf_ak_your_key_here"}
base = "https://wordflowsai.com/api/agent"

# First, get available organizations
orgs = httpx.get(f"{base}/orgs", headers=headers).json()
org_id = orgs[0]["id"]  # Pick the org you want

ctx = httpx.get(f"{base}/context/full", headers=headers, params={"organization_id": org_id}).json()["markdown"]

# Use ctx in your LLM system prompt
messages = [
    {"role": "system", "content": f"You are a content writer.\n\n{ctx}"},
    {"role": "user", "content": "Write a blog post about Kubernetes best practices"}
]
```

### Multi-step agent workflow

Different agents or pipeline stages call different endpoints. This minimizes token usage per step.

```python
import httpx

headers = {"X-API-Key": "wf_ak_your_key_here"}
base = "https://wordflowsai.com/api/agent"
org_id = 42  # From GET /orgs

# Step 1: Planning agent picks a topic
discovery_ctx = httpx.get(f"{base}/context/discovery", headers=headers, params={"organization_id": org_id}).json()["markdown"]

# Step 2: Brief agent defines the piece
brief_ctx = httpx.get(f"{base}/context/brief", headers=headers, params={"organization_id": org_id}).json()["markdown"]

# Step 3: Outline agent structures it
outline_ctx = httpx.get(f"{base}/context/outline", headers=headers, params={"organization_id": org_id}).json()["markdown"]

# Step 4: Writing agent generates each section
section_ctx = httpx.get(
    f"{base}/context/section",
    headers=headers,
    params={"organization_id": org_id, "topic": "kubernetes deployment"}
).json()["markdown"]

# Step 5: Review agent checks voice compliance
review_ctx = httpx.get(f"{base}/context/review", headers=headers, params={"organization_id": org_id}).json()["markdown"]
```

### Claude Code / Cursor / Windsurf integration

Add Wordflows context to your AI coding assistant's workflow when generating content programmatically:

```bash
# Fetch context and pipe to your agent
curl -s -H "X-API-Key: $WORDFLOWS_KEY" \
  "https://wordflowsai.com/api/agent/context/section?organization_id=42&topic=your-topic" | \
  jq -r '.markdown'
```

---

## Supported Use Cases

- **Blog content creation** — Full pipeline from topic discovery to voice-compliant drafts
- **Landing page copy** — Brand-aligned messaging with proper offers and CTAs
- **Email marketing** — Voice-consistent copy with audience-appropriate tone
- **Social media content** — Brand-aligned short-form content
- **Documentation** — Style-guide-compliant technical writing
- **Content auditing** — Review existing content against voice DNA baselines
- **Multi-agent content pipelines** — Specialized agents for each content creation phase
- **CMS integrations** — Feed context into WordPress, Ghost, or custom publishing flows

---

## Rate Limits

- 100 requests per minute per API key
- No per-day limits
- RAG chunk retrieval (the `topic` parameter on `/section`) adds ~200ms latency

---

## Getting Started

1. Sign up at [wordflowsai.com](https://wordflowsai.com)
2. Complete onboarding — add your website, brand guide, and style guide
3. Create a Voice DNA profile (from samples or from scratch via Voice Genesis)
4. Generate an API key from the dashboard
5. Call the Agent Context API from your agent or pipeline