API Reference

Complete REST API documentation for Product Shadow. Build custom integrations in under 10 minutes.

Before You Start

What You Need

• API Token: Generate one at /app/connect
• Test with curl first: Verify your token works before building integrations
• Read rate limits: Understand your plan's limits to avoid 429 errors

Rate Limits by Plan

Plan	Uploads/Hour	Requests/Hour
Free	20	100
Pro	100	500
Power	Unlimited	Unlimited

Rate Limit Headers

All responses include rate limit headers:

• X-RateLimit-Limit - Your limit
• X-RateLimit-Remaining - Requests left
• X-RateLimit-Reset - When limit resets (Unix timestamp)

Quick Start

1. Get Your API Token

Not Authenticated

# Sign up first at https://productshadow.app/signup

Authenticated

# Get your token at https://productshadow.app/app/connect
# Token format: ps_live_abc123...

2. Test Your Token

curl -H "X-API-Key: ps_live_YOUR_TOKEN" \
  https://api.productshadow.app/api/v1/account

3. Upload Your First Document

curl -X POST https://api.productshadow.app/api/v1/documents \
  -H "X-API-Key: ps_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Document",
    "content": "# Hello World\nThis is a test.",
    "content_type": "text/markdown",
    "context_level": 2,
    "metadata": {
      "project": "API Testing",
      "source": "curl"
    }
  }'

Decision Trees

Content Type Decision

Meeting notes from Otter.ai?
  → text/markdown, context_level=2

Product strategy doc?
  → text/markdown, context_level=1

Customer feedback snippet?
  → text/plain, context_level=3

Code snippet or spec?
  → text/markdown, context_level=2

Context Level Hierarchy

Level 1 (10x weight): Foundational
- Company vision, strategy docs
- PM frameworks, decision criteria
- Changes quarterly

Level 2 (5x weight): Tactical
- Active projects, roadmaps
- Meeting notes, sprint planning
- Changes weekly

Level 3 (1x weight): Reference
- Customer feedback, bug reports
- Quick decisions, ad-hoc notes
- Changes daily

API Endpoints

Explore the complete API:

• Upload Document - POST /api/v1/documents
• List Documents - GET /api/v1/documents
• List Tokens - GET /api/v1/tokens
• Revoke Token - DELETE /api/v1/tokens/{id}
• Account Info - GET /api/v1/account

Next Steps

• Authentication Guide - Detailed auth docs
• Common Mistakes - Avoid these pitfalls
• Integration Examples - Otter.ai, Notion, webhooks