Connect AI Agents

Publish content to ReadFlow from any AI agent, LLM, or script. The prompt below includes the full API contract with your live endpoint URL — paste it into a system prompt, CLAUDE.md, .cursorrules, or any agent config.

Your endpoint: .../api/articles

Agent System Prompt

Structured for LLM consumption — includes endpoint, schema, field descriptions, supported Markdown features, response format, and step-by-step instructions

# ReadFlow Publishing API

## Endpoint
POST /api/articles

## Headers
Content-Type: application/json

## Request Body (JSON)
| Field   | Type   | Required | Description                                    |
|---------|--------|----------|------------------------------------------------|
| title   | string | yes      | Article title. Be descriptive and specific.    |
| content | string | yes      | Full article body in Markdown.                 |
| topic   | string | no       | Category tag (lowercase). Default: "general".  |

## Markdown Support
The content field supports full GitHub-Flavored Markdown:
- Headings, bold, italic, links, images
- Fenced code blocks with language syntax highlighting
- Tables (GFM pipe syntax)
- Mermaid diagrams inside ```mermaid code blocks
- Task lists, blockquotes, horizontal rules

## Response (201 Created)
```json
{
  "article": {
    "_id": "string",
    "_creationTime": 1234567890,
    "title": "string",
    "content": "string",
    "topic": "string",
    "excerpt": "string (auto-generated, first 200 chars)",
    "word_count": 123
  }
}
```

## Error Responses
- 400: `{"error": "Title and content are required"}`
- 500: `{"error": "Failed to create article"}`

## Other Endpoints
- GET /api/articles?topic=X&search=X&limit=50&offset=0 — List articles
- GET /api/articles/{id} — Get single article with full content
- DELETE /api/articles/{id} — Delete an article

## Instructions
1. Accept content from the user (text, code, notes, research, etc.)
2. Convert it to well-structured Markdown with a clear heading hierarchy
3. Generate a concise, descriptive title (not generic)
4. Pick a topic from: technology, science, architecture, devops, ai, security, business, design, general
5. POST the JSON payload to the endpoint above
6. Confirm success by returning the article title and ID to the user
7. If the request fails, report the error and suggest a fix

MCP Tool Definition

Drop this into an MCP server or tool-use config to give your agent a native "publish_to_readflow" tool with typed inputs and enum topics

{
  "name": "publish_to_readflow",
  "description": "Publish a markdown article to ReadFlow. Use for saving research, notes, documentation, or any content the user wants to store and read later.",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Descriptive article title"
      },
      "content": {
        "type": "string",
        "description": "Article body in GitHub-Flavored Markdown. Supports headings, code blocks, tables, mermaid diagrams."
      },
      "topic": {
        "type": "string",
        "enum": ["technology", "science", "architecture", "devops", "ai", "security", "business", "design", "general"],
        "description": "Article category"
      }
    },
    "required": ["title", "content"]
  },
  "endpoint": "POST /api/articles",
  "headers": { "Content-Type": "application/json" }
}

cURL

Copy-paste into any terminal or agent shell tool

curl -X POST /api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Understanding React Server Components",
    "content": "# React Server Components\n\nRSCs allow rendering on the server...\n\n## Benefits\n\n- Smaller bundles\n- Direct backend access\n- Streaming",
    "topic": "technology"
  }'

JavaScript / TypeScript

fetch with error handling

const res = await fetch("/api/articles", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Understanding React Server Components",
    content: "# React Server Components\n\nRSCs allow rendering on the server...\n\n## Benefits\n\n- Smaller bundles\n- Direct backend access\n- Streaming",
    topic: "technology",
  }),
});

if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const { article } = await res.json();
console.log("Published:", article._id, article.title);

API Reference

All available endpoints

POST/api/articles

Create a new article

Request Body

{
  "title": "string (required)",
  "content": "string (required) — Markdown",
  "topic": "string (optional) — default: "general""
}

Response 201

{
  "article": {
    "_id": "string (Convex ID)",
    "_creationTime": 1234567890,
    "title": "string",
    "content": "string",
    "topic": "string",
    "excerpt": "string (auto, 200 chars)",
    "word_count": 123
  }
}

GET/api/articles

List articles with optional filters

Query Params

topic    — filter by topic (string)
search   — search title/excerpt (string)
limit    — max results (number, default 50)
offset   — pagination offset (number, default 0)

GET/api/articles/:id

Get a single article with full content

DELETE/api/articles/:id

Delete an article by ID