{
  "openapi": "3.1.0",
  "info": {
    "title": "Creator OS Public API",
    "version": "2026-04-18",
    "summary": "Discovery-oriented OpenAPI description for Creator OS public and authenticated endpoints.",
    "description": "Creator OS APIs power public showcase data, authenticated subscription actions, MCP token management, and MCP auth exchange."
  },
  "servers": [
    {
      "url": "https://nokaflklgqogjltawxda.supabase.co/functions/v1",
      "description": "Creator OS functions API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/public-showcase": {
      "get": {
        "summary": "List public showcase items",
        "description": "Returns public showcase thumbnails and creator metadata for the marketing site.",
        "security": [],
        "responses": {
          "200": {
            "description": "Showcase payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ShowcaseItem"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "cached": {
                      "type": "boolean"
                    }
                  },
                  "required": ["items", "total", "offset", "cached"]
                }
              }
            }
          }
        }
      }
    },
    "/create-checkout": {
      "post": {
        "summary": "Create a subscription checkout session",
        "description": "Creates a Stripe Checkout session for an authenticated Creator OS user.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "priceId": {
                    "type": "string",
                    "description": "Stripe price identifier for the selected plan."
                  }
                },
                "required": ["priceId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "required": ["url"]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/check-subscription": {
      "post": {
        "summary": "Read the current subscription state",
        "description": "Returns the authenticated user's current Creator OS billing state.",
        "responses": {
          "200": {
            "description": "Subscription state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionState"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/mcp-token-manage": {
      "post": {
        "summary": "Manage Creator OS MCP tokens",
        "description": "Lists, creates, reveals, revokes, and deletes MCP tokens for the authenticated user.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["list", "create", "reveal", "revoke", "delete"]
                  }
                },
                "required": ["action"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token management response"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/mcp-usage": {
      "post": {
        "summary": "Read MCP usage summaries",
        "description": "Returns per-token and aggregate MCP usage data for the authenticated user.",
        "responses": {
          "200": {
            "description": "Usage summary"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/external-mcp-manage": {
      "post": {
        "summary": "Manage external streamable HTTP MCP servers",
        "description": "Discovers, stores, refreshes, enables, and removes external MCP servers connected to Creator OS.",
        "responses": {
          "200": {
            "description": "External MCP server response"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/mcp-auth-exchange": {
      "post": {
        "summary": "Exchange an MCP token for a short-lived session",
        "description": "Accepts a Creator OS MCP token and returns a short-lived auth exchange payload for the MCP package.",
        "responses": {
          "200": {
            "description": "Exchange payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token_id": {
                      "type": "string"
                    },
                    "token_name": {
                      "type": ["string", "null"]
                    },
                    "user_id": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string",
                      "format": "email"
                    },
                    "token_hash": {
                      "type": "string"
                    },
                    "verification_type": {
                      "type": "string"
                    }
                  },
                  "required": ["token_id", "user_id", "email", "token_hash", "verification_type"]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT or MCP token"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid bearer token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": ["error"]
      },
      "ShowcaseItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": ["string", "null"]
          },
          "image_url": {
            "type": "string",
            "format": "uri"
          },
          "format": {
            "type": ["string", "null"]
          },
          "language": {
            "type": ["string", "null"]
          },
          "user_id": {
            "type": "string"
          },
          "creator_name": {
            "type": "string"
          },
          "creator_username": {
            "type": ["string", "null"]
          },
          "creator_verified": {
            "type": "boolean"
          }
        },
        "required": ["id", "image_url", "user_id", "creator_name", "creator_verified"]
      },
      "SubscriptionState": {
        "type": "object",
        "properties": {
          "subscribed": {
            "type": "boolean"
          },
          "product_id": {
            "type": ["string", "null"]
          },
          "price_id": {
            "type": ["string", "null"]
          },
          "subscription_end": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "cancel_at_period_end": {
            "type": ["boolean", "null"]
          },
          "status": {
            "type": ["string", "null"]
          },
          "source": {
            "type": ["string", "null"]
          },
          "plan": {
            "type": ["string", "null"]
          }
        },
        "required": ["subscribed"]
      }
    }
  }
}