Bestboy API

Create, manage, and share wishlists programmatically. Built for AI agents, integrations, and developers.

Home OpenAPI Spec LLMs.txt MCP Server Card

Quick Links

OpenAPI 3.1 Spec Full API specification in JSON format MCP Server Endpoint JSON-RPC 2.0 endpoint for AI agents MCP Server Card Discovery manifest for MCP clients MCP Manifest Machine-readable MCP configuration AI Plugin Manifest ChatGPT plugin discovery format LLMs.txt Human-readable docs for AI agents

MCP Server

Bestboy exposes a Model Context Protocol (MCP) server for AI agent integration. The server implements JSON-RPC 2.0 over HTTP POST and supports both public and authenticated tool calls.

Endpoint

POST https://bestboy.app/api/mcp
Content-Type: application/json

Protocol

The MCP server implements the 2024-11-05 protocol version with these JSON-RPC methods:

Authentication

Authenticated tools require a Supabase JWT passed as a Bearer token. Public tools (reading shared wishlists, reserving wishes) need no token. 

POST /api/mcp
Authorization: Bearer {supabase_jwt_token}
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_my_wishlists",
    "arguments": {}
  }
}

How to get a token

POST https://tcwbpxdiutixaoxwqtpo.supabase.co/auth/v1/token?grant_type=password
Content-Type: application/json
apikey: {SUPABASE_ANON_KEY}

{
  "email": "user@example.com",
  "password": "your_password"
}

// Response includes access_token to use as Bearer token

Available Tools

list_my_wishlists Authenticated

List all wishlists owned by the authenticated user.

Arguments: none

create_wishlist Authenticated

Create a new wishlist.

Arguments: name (required, string), description (optional, string)

add_wish Authenticated

Add a wish item, optionally attaching it to a list.

Arguments: name (required), link, price, emoji, description, listId

share_wishlist Authenticated

Get the shareable URL for a wishlist.

Arguments: listId (required, UUID)

get_shared_wishlist Public

Fetch a publicly shared wishlist and its wishes by share token. No authentication required.

Arguments: shareToken (required, string)

reserve_wish Public

Anonymously reserve a wish on a shared wishlist.

Arguments: wishId (required, UUID), sessionId (optional)

Examples

Initialize the MCP connection

curl -X POST https://bestboy.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }'

List available tools

curl -X POST https://bestboy.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Get a shared wishlist (no auth needed)

curl -X POST https://bestboy.app/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_shared_wishlist",
      "arguments": {
        "shareToken": "abc123xyz"
      }
    }
  }'

Create a wishlist (authenticated)

curl -X POST https://bestboy.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "create_wishlist",
      "arguments": {
        "name": "Birthday 2026",
        "description": "Things I want for my birthday"
      }
    }
  }'

REST API (PostgREST)

For direct database access, you can also use the Supabase PostgREST API. All requests require the apikey header with the anon key and Authorization: Bearer with a user JWT.

See the OpenAPI specification for full endpoint documentation.

Tables

Discovery

AI agents and clients can discover the API through multiple mechanisms:

HTTP Link headers are also returned on every response with references to all discovery endpoints.