Agent-Native Content API — Token-Efficient, Batch-Optimized, Agent-Identity-Aware

[Weegy]

The Opportunity

A new GitHub repository called markdown-site (592 ⭐ in weeks) just trended with the tagline: "An open-source publishing framework built for AI agents and humans."

This signals a major architectural shift: the next generation of CMS users are AI agents, not humans.

Today, every CMS — including Numen — is designed for humans to call APIs. The content request → API call pattern assumes a human is making the call. But the future is agents making calls: coding agents, marketing agents, research agents, social media agents, and more.

An Agent-Native Content API is an API layer specifically optimized for LLM / agent consumption:

• Structured JSON-LD responses with full semantic context
• Bulk operations designed for agent batch workflows
• Token-efficient responses (agents pay per token — waste matters)
• Webhook subscriptions that agents can register/deregister dynamically
• Content "diff" endpoints (what changed since timestamp X?)
• Agent identity via API keys with scoped permissions per agent role
• Rate limiting with agent-aware quotas (agents can burst harder than humans)

---

Why This Is Different From REST API

Our existing REST API serves humans and their frontend apps. An agent-native API layer serves:

1. External coding agents — Cursor, Windsurf, Claude Code updating content/docs
2. Marketing agents — Automated social posting, email drafting, A/B test management
3. Analytics agents — Ingesting performance data, updating content based on signals
4. Integration agents — Syncing Numen content to external systems (HubSpot, Contentful, etc.)
5. Future Numen agents — Our own pipeline workers consuming Numen content

---

Key Design Principles

1. Token-Efficient Responses

Agents pay per token. Today's REST API returns full HTML/markdown bodies even when the agent only needs metadata. The agent-native API should support:

• ?fields=title,slug,summary,published_at — field projection
• ?format=json-ld — semantic structured data
• ?format=markdown — for writing agents that need raw text
• ?summarize=true — AI-compressed summaries (using Numen's own pipeline)

2. Bulk Operations

Agents work in batches. Instead of 100 individual API calls:

• POST /api/agent/batch — bulk read/create/update in one request
• POST /api/agent/pipeline/batch — trigger multiple pipeline runs

3. Agent Identity & Scoped Permissions

Each agent gets its own API key with role-based scopes:

• content:read — read-only, for research agents
• content:write — create/update, for generation agents
• pipeline:run — trigger AI pipeline
• publish — publish/unpublish (requires explicit grant)
• admin — full access (for Numen's own internal agents)

Audit log shows which agent made every change.

4. Real-Time Agent Subscriptions

Agents register webhooks dynamically via API:

• POST /api/agent/subscribe — register webhook for content events
• DELETE /api/agent/subscribe/{id} — deregister
• Auto-expiry on agent key deletion

5. Content Diff Endpoint

GET /api/agent/diff?since=2026-03-17T00:00:00Z — returns only changed content since timestamp. Agents can efficiently sync without polling all content.

---

Competitor Context

CMS	Agent-Native Features
Payload	MCP plugin (very new), standard REST
Directus	Standard REST + GraphQL, no agent optimization
Strapi	Standard REST + GraphQL
Contentful	Standard REST + GraphQL, no agent layer
Ghost	Standard REST, minimal
markdown-site (new)	Explicitly "built for AI agents" — but no pipeline

Numen opportunity: Be the first CMS with a pipeline-aware, agent-native API. Not just token-efficient reads, but an API that understands the difference between a human editor and an autonomous agent.

---

Implementation Scope

Phase 1 (M): Agent identity layer + scoped API keys + audit log
Phase 2 (M): Token-efficient field projection + JSON-LD format + markdown format
Phase 3 (S): Bulk operations endpoint
Phase 4 (S): Dynamic webhook subscriptions + content diff endpoint
Phase 5 (M): Agent-facing dashboard — "Your agents" view, usage metrics, scoped key management

---

Acceptance Criteria

• Agent API keys with role-based scopes (content:read, content:write, pipeline:run, publish)
• Field projection: ?fields=title,slug,summary returns only requested fields
• Format options: ?format=json-ld and ?format=markdown
• POST /api/agent/batch supports up to 100 operations per request
• Dynamic webhook subscriptions via API (create/delete/list)
• Content diff endpoint: /api/agent/diff?since=ISO_TIMESTAMP
• Audit log records agent identity on every mutation
• Agent management UI in admin dashboard
• Docs: "Building with Numen's Agent API" guide