# AGENTS.md — Paranor Agent API
This document describes how AI agents should interact with Paranor's Agent API.
## Discovery
- **Agent API Index:** https://api.paranor.app/api/agent
- **Agent Card (A2A):** https://api.paranor.app/.well-known/agent-card.json
- **Meta-only widget snippets:** https://api.paranor.app/api/agent/widget
- **MCP Server:** https://api.paranor.app/api/mcp
- **llms.txt:** https://api.paranor.app/llms.txt
- **Canonical docs/status:** https://docs.paranor.app and https://status.paranor.app
- **Nexus:** https://api.paranor.app/api/nexus/creators — multi-creator discovery (search by topic, tag, keyword); https://api.paranor.app/nexus for human directory
- **Learn — For AI agents:** https://api.paranor.app/learn/for-agents — FAQs and pipeline (Dot → Contexter → Index → Cataloger → Nexus). Project docs: AI_AGENT_INSTRUCTION_BOOK for instruction-book style guidance.
- **Learn — Workers:** https://api.paranor.app/learn/workers — Pay-for-Work: OpenClaw skill (paranor-task-pool) and UmbrelOS compute workers; earn sats, incentives, setup. Task API: /api/tasks/available, /api/tasks/claim, /api/tasks/submit.
## Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| /api/agent/profile | GET | Creator profile, bio, topics, links; optional indexUpdatedAt, stats.totalApiCalls30d, stats.agentOriginCalls30d |
| /api/agent/booking | GET | Topics, sample questions, booking links |
| /api/agent/media-kit | GET | Approved copy, blurbs, stats |
| /api/agent/speaking | GET | Bio, topics, past talks |
| /api/agent/content-index | GET | Unified content list (paginated) |
| /api/agent/content-index/bundle | GET | NDJSON bundle alias for content-index batch retrieval |
| /api/agent/articles | GET | Dots list (paginated) |
| /api/agent/show-prep | GET | Deterministic show prep briefing payload (showUrl required) |
| /api/agent/transcribe | POST | Transcribe remote audio/video URL (sourceUrl); L402-gated when enabled |
| /api/agent/articles/{id} | GET | Single article with summary, citations |
| /api/agent/timeline-entries | GET | Event timeline |
| /api/agent/episodes | GET | Podcast/RSS episodes |
| /api/agent/stream-videos | GET | Stream and video entries |
| /api/article/{id}/markdown | GET | Article markdown export |
| /api/guest-kit | POST | Generate guest kit (body: showUrl, showDescription?) |
| /api/agent/register-agent-tier | POST | Register for free Agent tier slice (body: name, purpose) |
| /api/agent/work-offer | POST | Request a micro-task for access (body: resourceId) |
| /api/agent/work-submit | POST | Submit task result for access token (body: taskId, submission) |
Pagination: `?limit=N&offset=M` on content-index, articles, episodes, stream-videos.
## Authentication
Discovery endpoints (profile, booking, media-kit, speaking, timeline-entries, episodes, stream-videos) are always free. No auth required.
## Rate Limits
- Cron ingest: 10 requests/min per IP
- Guest kit: 20 requests/hour per IP
- L402 payment-request: 30 requests/min per IP
- Backoff strategy: on 429 read Retry-After; otherwise use exponential backoff with jitter.
## MCP
Paranor exposes an MCP-compatible server at https://api.paranor.app/api/mcp.
- **Descriptor:** GET https://api.paranor.app/api/mcp
- **Tool execution:** POST https://api.paranor.app/api/mcp/call with `{ tool, arguments }`
- **Method check:** GET https://api.paranor.app/api/mcp/call returns 405 Method Not Allowed (use POST for execution)
Tools: get_profile, get_content_index, get_booking, get_media_kit, get_speaking, get_articles, get_article, get_timeline_entries, get_episodes, get_stream_videos, generate_guest_kit.