Marketplace API¶

Version: 1.0 Base Path: /marketplace Last Updated: 2026-01-27

Overview¶

REST API for the Superpower Marketplace. Enables browsing, installing, and managing community-created superpowers.

Authentication¶

Public endpoints: No authentication required
User endpoints: Bearer token via Authorization: Bearer <token> header
Admin endpoints: API key via X-Admin-Key header

Public Endpoints¶

Browse Superpowers¶

Browse public, approved superpowers with filtering and sorting.

GET /marketplace/superpowers

Query Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | category | string | null | Filter by category | | search | string | null | Search in name/description | | sort_by | enum | "popular" | Sort order: "popular", "newest", "featured" | | page | int | 1 | Page number (1-indexed) | | limit | int | 20 | Items per page (max 100) |

Response: 200 OK

{
  "superpowers": [
    {
      "id": "custom_budget_tracker_abc123",
      "name": "Budget Tracker",
      "description": "Track your spending from Gmail receipts",
      "category": "finance",
      "icon": "dollar-sign",
      "install_count": 150,
      "is_featured": true,
      "required_scopes": ["gmail"],
      "creator_name": "John",
      "created_at": "2026-01-15T10:30:00Z",
      "average_rating": 4.2,
      "total_ratings": 28,
      "is_installed": false
    }
  ],
  "total": 42,
  "page": 1,
  "total_pages": 3,
  "categories": [
    {"id": "finance", "name": "Finance", "count": 12},
    {"id": "productivity", "name": "Productivity", "count": 8}
  ]
}

Note: If authenticated, the is_installed field indicates whether the current user has installed each superpower. If not authenticated, is_installed is always false.

Get Superpower Details¶

Get detailed information about a specific superpower.

GET /marketplace/superpowers/{app_id}

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Response: 200 OK

{
  "id": "custom_budget_tracker_abc123",
  "name": "Budget Tracker",
  "description": "Track your spending from Gmail receipts",
  "category": "finance",
  "icon": "dollar-sign",
  "tags": ["money", "receipts", "spending"],
  "install_count": 150,
  "is_featured": true,
  "required_scopes": ["gmail"],
  "creator_name": "John",
  "created_at": "2026-01-15T10:30:00Z",
  "version": "1.0",
  "event_types": ["receipt_analyzed", "budget_updated"],
  "capabilities": ["Analyzes Gmail receipts", "Tracks monthly spending"],
  "is_installed": true
}

Note: If authenticated, the is_installed field indicates whether the current user has installed this superpower. If not authenticated, is_installed is always false.

Errors: - 404 Not Found: Superpower not found or not public

Get Categories¶

List all categories with counts.

GET /marketplace/categories

Response: 200 OK

[
  {"id": "finance", "name": "Finance", "count": 12},
  {"id": "productivity", "name": "Productivity", "count": 8},
  {"id": "health", "name": "Health", "count": 5}
]

Get Featured¶

Get featured superpowers.

GET /marketplace/featured

Query Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | int | 10 | Max items (1-50) |

Response: 200 OK

[
  {
    "id": "custom_budget_tracker_abc123",
    "name": "Budget Tracker",
    "description": "Track your spending from Gmail receipts",
    "category": "finance",
    "icon": "dollar-sign",
    "install_count": 150,
    "is_featured": true,
    "required_scopes": ["gmail"],
    "creator_name": "John",
    "created_at": "2026-01-15T10:30:00Z"
  }
]

User Endpoints¶

Get Installed Superpowers¶

Get all superpowers installed by the current user.

GET /marketplace/installed

Authentication: Required

Response: 200 OK

{
  "superpowers": [
    {
      "id": "custom_budget_tracker_abc123",
      "name": "Budget Tracker",
      "description": "Track your spending from Gmail receipts",
      "category": "finance",
      "icon": "dollar-sign",
      "install_count": 150,
      "is_featured": true,
      "required_scopes": ["gmail"],
      "creator_name": "John",
      "installed_at": "2026-01-20T14:30:00Z"
    }
  ],
  "total": 1
}

Errors: - 401 Unauthorized: Not authenticated

Install Superpower¶

Install a superpower from the marketplace.

POST /marketplace/superpowers/{app_id}/install

Authentication: Required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Response: 200 OK

{
  "success": true,
  "message": "Superpower installed successfully",
  "install_id": "uuid-of-installation"
}

Errors: - 400 Bad Request: Already installed or app not available - 401 Unauthorized: Not authenticated - 404 Not Found: Superpower not found

Uninstall Superpower¶

Uninstall a superpower.

DELETE /marketplace/superpowers/{app_id}/install

Authentication: Required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Response: 200 OK

{
  "success": true,
  "message": "Superpower uninstalled successfully"
}

Errors: - 400 Bad Request: Not installed or already uninstalled - 401 Unauthorized: Not authenticated

Creator Endpoints¶

Submit for Review¶

Submit a custom app for marketplace review.

POST /marketplace/submissions

Authentication: Required Rate Limit: 5 requests/hour

Request Body:

{
  "app_id": "custom_my_app_abc123"
}

Response: 200 OK

{
  "success": true,
  "message": "App submitted for review",
  "submitted_at": "2026-01-27T10:30:00Z"
}

Errors: - 400 Bad Request: - App not found - Not owner of app - App not active - Already submitted/approved - Missing required metadata - Phone not verified - 401 Unauthorized: Not authenticated - 429 Too Many Requests: Rate limit exceeded

Get My Submissions¶

Get all marketplace submissions for the current user.

GET /marketplace/submissions/my

Authentication: Required

Response: 200 OK

{
  "submissions": [
    {
      "app_id": "custom_my_app_abc123",
      "name": "My App",
      "description": "Does cool stuff",
      "category": "productivity",
      "icon": "zap",
      "status": "pending_review",
      "visibility": "private",
      "submitted_at": "2026-01-27T10:30:00Z",
      "reviewed_at": null,
      "rejection_reason": null,
      "install_count": 0
    }
  ],
  "total": 1
}

Status Values: - pending_review: Awaiting admin review - approved: Published to marketplace - rejected: Rejected by admin - suspended: Suspended by admin

Withdraw Submission¶

Withdraw a pending submission.

DELETE /marketplace/submissions/{app_id}

Authentication: Required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Response: 200 OK

{
  "success": true,
  "message": "Submission withdrawn"
}

Errors: - 400 Bad Request: Not pending or not owner - 401 Unauthorized: Not authenticated

Admin Endpoints¶

Get Pending Queue¶

Get pending review queue.

GET /marketplace/admin/pending

Authentication: X-Admin-Key header required

Response: 200 OK

{
  "items": [
    {
      "app_id": "custom_my_app_abc123",
      "name": "My App",
      "description": "Does cool stuff",
      "category": "productivity",
      "icon": "zap",
      "creator_name": "John",
      "creator_phone": "+15551234567",
      "submitted_at": "2026-01-27T10:30:00Z",
      "required_scopes": ["calendar"]
    }
  ],
  "total": 5
}

Review Submission¶

Approve or reject a pending submission.

POST /marketplace/admin/review/{app_id}

Authentication: X-Admin-Key header required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Request Body:

{
  "decision": "approve",
  "review_notes": "Internal notes (optional)",
  "rejection_reason": "Required if rejecting (shown to creator)"
}

Decision Values: approve, reject

Response: 200 OK

{
  "success": true,
  "message": "App approved and published to marketplace",
  "app_id": "custom_my_app_abc123",
  "new_status": "approved"
}

Errors: - 400 Bad Request: Not pending review, or rejection without reason - 401 Unauthorized: Invalid admin key

Toggle Featured¶

Toggle featured status of an approved app.

PUT /marketplace/admin/feature/{app_id}

Authentication: X-Admin-Key header required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Response: 200 OK

{
  "success": true,
  "message": "App featured",
  "is_featured": true
}

Errors: - 400 Bad Request: App not found or not approved - 401 Unauthorized: Invalid admin key

Suspend App¶

Suspend a published app from the marketplace.

PUT /marketplace/admin/suspend/{app_id}

Authentication: X-Admin-Key header required

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Query Parameters: | Parameter | Type | Description | |-----------|------|-------------| | reason | string | Optional suspension reason |

Response: 200 OK

{
  "success": true,
  "message": "App suspended",
  "new_status": "suspended"
}

Errors: - 400 Bad Request: Cannot suspend (not approved/pending) - 401 Unauthorized: Invalid admin key

Rating & Review Endpoints¶

Rate a Superpower¶

Submit or update a rating for an installed superpower.

POST /marketplace/superpowers/{app_id}/rate

Authentication: Required (must have app installed)

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Request Body:

{
  "rating": 4,
  "review_text": "Great for tracking my daily spending!"
}

Field	Type	Required	Description
rating	int	Yes	1-5 star rating
review_text	string	No	Optional text review

Response: 200 OK

{
  "success": true,
  "message": "Rating submitted"
}

Errors: - 400 Bad Request: Not installed, invalid rating (must be 1-5) - 401 Unauthorized: Not authenticated - 404 Not Found: Superpower not found

Get Superpower Ratings¶

Get ratings and reviews for a superpower.

GET /marketplace/superpowers/{app_id}/ratings

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Query Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | page | int | 1 | Page number | | limit | int | 20 | Items per page (max 50) |

Response: 200 OK

{
  "stats": {
    "average_rating": 4.2,
    "total_ratings": 28,
    "distribution": {"1": 1, "2": 2, "3": 3, "4": 10, "5": 12}
  },
  "ratings": [
    {
      "id": "uuid",
      "user_name": "John",
      "rating": 5,
      "review_text": "Love this superpower!",
      "created_at": "2026-02-10T14:30:00Z"
    }
  ],
  "total": 28,
  "page": 1,
  "total_pages": 2
}

Abuse Report Endpoints¶

Report a Superpower¶

Report a superpower for abuse or policy violations.

POST /marketplace/superpowers/{app_id}/report

Authentication: Required Rate Limit: 3 reports/hour

Path Parameters: | Parameter | Type | Description | |-----------|------|-------------| | app_id | string | Superpower ID |

Request Body:

{
  "reason": "spam",
  "description": "This app sends unsolicited promotional content"
}

Field	Type	Required	Description
reason	enum	Yes	`spam`, `malicious`, `inappropriate`, `copyright`, `other`
description	string	No	Additional details

Response: 200 OK

{
  "success": true,
  "message": "Report submitted"
}

Auto-suspension: If an app receives 3+ reports, it is automatically suspended from the marketplace.

Errors: - 400 Bad Request: Already reported by this user - 401 Unauthorized: Not authenticated - 404 Not Found: Superpower not found - 429 Too Many Requests: Rate limit exceeded

Get Abuse Reports (Admin)¶

Get pending abuse reports.

GET /marketplace/admin/reports

Authentication: X-Admin-Key header required

Query Parameters: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | status | string | "pending" | Filter: pending, reviewed, dismissed |

Response: 200 OK

{
  "reports": [
    {
      "id": "uuid",
      "miniapp_id": "custom_app_abc123",
      "miniapp_name": "Suspicious App",
      "reporter_name": "Jane",
      "reason": "spam",
      "description": "Sends promotional content",
      "status": "pending",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ],
  "total": 3
}

Error Response Format¶

All errors follow this format:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes: - 400 Bad Request: Invalid request or business rule violation - 401 Unauthorized: Missing or invalid authentication - 404 Not Found: Resource not found - 429 Too Many Requests: Rate limit exceeded - 500 Internal Server Error: Server error