HTTP API Reference

Canonical reference for Sage HTTP APIs across the Worker and Web App.

• Worker: https://api.sageprotocol.io/* (Cloudflare Worker — packages/ipfs-worker/)
• Web App: https://app.sageprotocol.io/api/* (Next.js — packages/sage-web-app/)

---

Worker APIs (api.sageprotocol.io)

Health

GET /health

---

IPFS Content & Pinning

Public (no auth):

Method	Path	Description
GET	/ipfs/content/{cid}	Fetch content by CID
GET	/ipfs/pin/costs	Get pin pricing
GET	/ipfs/pin/status/{cid}	Check pin status
GET	/ipfs/pin/{cid}	Get pin info
GET	/ipfs/pins	List pins

Authenticated:

Method	Path	Description
POST	/ipfs/upload	Upload content
POST	/ipfs/pin	Pin content
DELETE	/ipfs/pin/{cid}	Unpin content
POST	/ipfs/pin/extend	Extend pin duration
POST	/ipfs/warm	Warm IPFS caches

---

Marketplace (Claude Code)

Method	Path	Description
GET	/marketplace.json	Marketplace manifest
GET	/marketplace	Marketplace index
GET	/marketplace/plugins	List plugins
GET	/marketplace/plugins/{name}	Plugin details
GET	/marketplace/search?q={query}	Search plugins
GET	/marketplace/library/{subdao}	Library for a DAO
GET	/marketplace/library/{subdao}/marketplace.json	DAO marketplace manifest
GET	/marketplace/library/{subdao}/download	Download library
POST	/marketplace/register	Register a plugin

---

Prompt Discovery (Canonical)

Method	Path	Description
GET	/prompts/search?q={query}	Search prompts
GET	/prompts/trending?window={window}	Trending prompts
GET	/prompts/similar/{cid}	Similar prompts
GET	/prompts/by-tag/{tag}	Prompts by tag
GET	/prompts/tags	All tags
GET	/prompts/skills	Skills listing
GET	/prompts/stats	Index statistics
GET	/prompts/categories	All categories
GET	/prompts/{cid}	Prompt by CID
POST	/prompts/match	Match prompts to preferences

Legacy endpoints (/discover/*) are deprecated.

---

Trends (Usage/Analytics)

Method	Path	Description
GET	/trends/top	Top trending
GET	/trends/signals/{cid}	Usage signals for a CID
GET	/trends/history/{cid}	Usage history
GET	/trends/stats	Aggregate stats
POST	/trends/usage	Record usage event
POST	/trends/install	Record install event
GET	/trends/library/{subdao}/{libraryId}/stats	Library stats
GET	/trends/library/{subdao}/{libraryId}/daily	Library daily metrics
GET	/trends/dao/{subdao}/overview	DAO overview
GET	/trends/library/top	Top libraries
POST	/trends/library/usage	Record library usage
POST	/trends/sync	Sync trends

---

Library Listing

Method	Path	Description
GET	/libraries	List libraries
GET	/libraries/{id}	Library details
GET	/libraries/{id}/prompts	Library prompts

---

Git Smart-HTTP

Method	Path	Description
GET	/git/dao/{subdao}/{libraryId}/info/refs?service=git-upload-pack	DAO git refs
POST	/git/dao/{subdao}/{libraryId}/git-upload-pack	DAO git fetch
GET	/git/personal/{libraryId}/info/refs?service=git-upload-pack	Personal git refs
POST	/git/personal/{libraryId}/git-upload-pack	Personal git fetch
GET	/git/skill/{cid}/info/refs?service=git-upload-pack	Skill git refs
POST	/git/skill/{cid}/git-upload-pack	Skill git fetch

---

A2A (Agent-to-Agent)

Method	Path	Description
GET	/a2a/dao/{subdao}/agent.json	Agent card for DAO
POST	/a2a/dao/{subdao}	Agent communication

---

Reputation

Public:

Method	Path	Description
GET	/reputation/author/{address}	Author metrics (revenue, purchases, consumers)
GET	/reputation/leaderboard	Top authors by revenue
GET	/reputation/stats	Global reputation statistics
GET	/reputation/achievements/{address}	Achievement badges

Admin (auth required):

Method	Path	Description
POST	/admin/reputation/retry-mints	Retry failed badge mints
GET	/admin/reputation/unattributed	Unattributed purchases
POST	/admin/reputation/compact	Compact old daily metrics

---

Web App APIs (app.sageprotocol.io/api/*)

Discovery Proxy

GET /api/discover

Proxies to the Worker discovery endpoints.

Parameter	Type	Required	Description
endpoint	string	Yes	Target endpoint: search, tags, categories, trending, skills, by-tag, libraries, library, stats
q	string	For search, skills	Search query
category	string	No	Category filter
tag	string	For by-tag	Tag filter
subdao	string	For library	SubDAO address
limit	number	No	Max results (default: 20)
offset	number	No	Pagination offset

Example responses:

Search (endpoint=search):

{
  "results": [
    { "key": "code-reviewer", "name": "Code Reviewer", "description": "...", "subdao": "0x...", "cid": "bafybeig...", "tags": ["development"], "score": 0.95 }
  ],
  "total": 42
}

Tags (endpoint=tags):

{ "tags": [{ "tag": "development", "count": 156 }] }

Stats (endpoint=stats):

{ "totalPrompts": 1234, "totalLibraries": 89, "totalSkills": 45, "lastIndexed": "2025-01-15T10:30:00Z" }

---

Premium Prompts

GET /api/premium/prompts/search

Parameter	Type	Required	Description
q	string	Yes	Search query
first	number	No	Max results (default: 50, max: 100)
subdao	string	No	Filter by SubDAO
tags	string	No	Comma-separated tags (AND)
minPrice	string	No	Min price in wei
maxPrice	string	No	Max price in wei

POST variant accepts the same parameters in the request body.

---

Manifests

GET /api/ipfs/manifest/{cid}

Fetch a library manifest by CID.

Response: Manifest JSON (schema: docs/schemas/manifest.v3.schema.json)

Error Status	Body	Condition
400	Invalid CID	CID format not recognized
415	Not valid JSON	Content is not JSON
502	Gateway fetch failed	IPFS gateway error

POST /api/ipfs/manifest

Batch-fetch manifests.

Request body:

{ "cids": ["bafybeig...", "bafybeih..."] }

Response:

{
  "results": [
    { "cid": "bafybeig...", "ok": true, "data": { "version": "3.0.0" } },
    { "cid": "bafybeih...", "ok": false, "error": "gateway_404" }
  ]
}

---

Subgraph Queries

POST /api/subgraph/libraries

Parameter	Type	Required	Description
first	number	No	Max results (default: 50)
owner	string	No	Filter by SubDAO address
id	string	No	Filter by library ID

GET /api/subgraph/prompts-by-key

Parameter	Type	Required	Description
key	string	Yes	Prompt key (can be registry/key format)
registry	string	No	Registry/SubDAO address
subdao	string	No	Alias for registry
first	number	No	Max results

POST variant accepts the same parameters.

POST /api/subgraph/latest-prompts

Parameter	Type	Required	Description
first	number	No	Max results

POST /api/subgraph/prompts

List prompts. Accepts first parameter.

POST /api/subgraph/subdaos

List all SubDAOs.

POST /api/subgraph/proposals

List proposals.

POST /api/subgraph/library-prompts

Parameter	Type	Required	Description
subdao	string	Yes	SubDAO address
first	number	No	Max results

POST /api/subgraph/registry-prompts

Parameter	Type	Required	Description
registry	string	Yes	Registry address
subdao	string	No	SubDAO address

POST /api/subgraph/members

Parameter	Type	Required	Description
subdao	string	Yes	SubDAO address

---

Governance

Method	Path	Parameters	Description
GET	/api/governance/list	subdao	List proposals
GET	/api/governance/detail	id, subdao	Proposal detail

---

Profile

Method	Path	Auth	Description
GET	/api/profile/{address}	No	Get user profile
GET	/api/profile/favorites	Yes (Privy)	Get favorites
GET	/api/profile/runs	Yes (Privy)	Get run history

---

Utility

Method	Path	Description
GET	/api/config/public	Public config (contract addresses, network info)
GET	/api/reputation?address={address}	Reputation check

---

Error Format

All APIs return:

{ "ok": false, "error": "Error message", "items": [] }

Status	Description
200	Success (check ok field)
400	Missing or invalid parameters
500	Internal server error
502	Upstream service error (IPFS, subgraph)
503	Service unavailable

---

Caching

Endpoint Pattern	Cache Duration
/api/discover/*	60 seconds
/api/ipfs/manifest/*	5 minutes
Subgraph queries	No cache (real-time)

---

Authentication

Read endpoints are public. Write operations and profile endpoints require Privy authentication.

---

See Also

• Manifest schema: docs/schemas/manifest.v3.schema.json
• SDK Overview
• Worker Materialization
• Canonical route list: packages/ipfs-worker/src/router.ts