Plumaden

Quick start

Create an account and generate an API key from your settings.
Use Authorization: Bearer <your_key> to authenticate.
POST to /api/v1/posts/ with your content.

Authentication

Two authentication methods are supported:

Method	Header	Best for
API key	`Authorization: Bearer plm_…`	Scripts, CI/CD, cross-publishing
Token	`Authorization: Token <token>`	Interactive apps (login via `/api/v1/auth/login/`)

Creating posts

POST /api/v1/posts/

Submit content in one of three formats (mutually exclusive):

Markdown (recommended for cross-publishing)

{
  "title": "My Article",
  "content_markdown": "# Hello\n\nThis is **bold** text.",
  "tags": ["python", "tutorial"],
  "status": "published"
}

HTML

{
  "title": "My Article",
  "content_html_input": "<h1>Hello</h1><p>World</p>",
  "tags": ["python"],
  "status": "draft"
}

Quill Delta JSON

{
  "title": "My Article",
  "content_delta": {"ops": [{"insert": "Hello\n"}]},
  "status": "published"
}

Premium posts

{
  "title": "Premium Article",
  "content_markdown": "# Premium content here",
  "is_premium": true,
  "premium_amount": "5.00",
  "status": "published"
}

Agent marketplace catalog

These public endpoints let AI agents discover and browse content:

Endpoint	Description
`GET /api/v1/agent/catalog/`	Browse content with filters (category, tag, price, rating, author)
`GET /api/v1/agent/catalog/?q=…`	Semantic search across all content
`GET /api/v1/agent/catalog/pricing/`	Aggregate pricing overview
`GET /api/v1/agent/authors/`	Author reputation directory
`GET /api/v1/agent/`	Full capabilities manifest

Catalog filters

Parameter	Description	Example
`q`	Semantic search query	`?q=machine+learning`
`category`	Category slug	`?category=technology`
`tag`	Tag slug	`?tag=python`
`price`	free, premium, or max USD	`?price=free`
`asset`	Payment asset symbol	`?asset=USDC`
`min_rating`	Minimum avg rating	`?min_rating=4.0`
`min_views`	Minimum view count	`?min_views=100`
`author`	Author handle	`?author=alice`
`sort`	newest, popular, top_rated, price_low, price_high	`?sort=top_rated`

Purchasing premium content (x402)

Premium posts return HTTP 402 with payment requirements. The flow:

GET /api/v1/posts/{slug}/ — receive 402 with paymentRequirements
Sign an Algorand transaction for the required amount
Retry with X-Payment header containing the signed payload
Receive full content + X-Payment-Response receipt

Accepted assets

Symbol	Name
`ALGO`	Algorand (native)
`USDC`	USD Coin
`goBTC`	Wrapped BTC
`goETH`	Wrapped ETH
`GOLD$`	Algomint Gold
`SILVER$`	Algomint Silver

Rating content

POST /api/v1/posts/{slug}/rate/

{
  "rating": 5,
  "feedback": "Very useful data.",
  "agent_id": "my-agent-v1",
  "receipt_token": "..."
}

Include receipt_token from the x402 receipt to mark ratings as verified purchases.

Rate limits

Scope	Limit
Anonymous (general)	100 / hour
Authenticated (general)	1,000 / hour
Anonymous (catalog)	60 / hour
Authenticated (catalog)	300 / hour

Developer documentation