openapi: 3.1.0
info:
  title: Seea Design API
  version: 0.5.3
  description: License-aware component registry and design-agent gateway for Seea.
servers:
  - url: https://design.seea.io
paths:
  /health:
    get:
      summary: Service health
      security: []
      responses:
        "200":
          description: Ready
  /v1/meta:
    get:
      summary: Read public service capabilities
      security: []
      responses:
        "200":
          description: Service metadata
  /v1/sources:
    get:
      summary: List researched design sources and their integration policies
      security: []
      parameters:
        - in: query
          name: policy
          schema:
            type: string
            enum: [redistributable, internal-byol, upstream-mcp-only, tool-only]
      responses:
        "200":
          description: Sanitized source list
        "401":
          description: Unauthorized when the public catalog is disabled
  /v1/components:
    get:
      summary: Search Seea-owned registry components
      security: []
      parameters:
        - in: query
          name: q
          schema: { type: string }
        - in: query
          name: tag
          schema: { type: string }
        - in: query
          name: category
          description: Canonical category id, name, or supported alias such as navbar.
          schema: { type: string }
        - in: query
          name: group
          schema: { type: string }
        - in: query
          name: tier
          schema: { type: string, enum: [free, pro] }
        - in: query
          name: format
          schema: { type: string, enum: [component, block, template] }
        - in: query
          name: sort
          schema: { type: string, enum: [featured, newest, popular, name] }
      responses:
        "200":
          description: Matching component metadata
  /v1/categories:
    get:
      summary: List marketplace category groups with live component counts
      security: []
      responses:
        "200": { description: Category group tree }
  /v1/categories/{categoryId}/components:
    get:
      summary: List components in one canonical agent category
      security: []
      parameters:
        - in: path
          name: categoryId
          required: true
          schema: { type: string }
        - in: query
          name: tier
          schema: { type: string, enum: [free, pro] }
        - in: query
          name: format
          schema: { type: string, enum: [component, block, template] }
      responses:
        "200": { description: Components in the category }
        "404": { description: Category not found }
  /v1/components/{componentId}:
    get:
      summary: Get public component metadata
      security: []
      parameters:
        - $ref: "#/components/parameters/componentId"
      responses:
        "200": { description: Component metadata }
        "404": { description: Component not found }
  /registry.json:
    get:
      summary: Read the protected shadcn-compatible registry index
      security:
        - registryKey: []
        - bearerAuth: []
      responses:
        "200": { description: Registry index }
        "401": { description: Unauthorized }
        "503": { description: Registry credential has not been provisioned }
  /r/{componentId}.json:
    get:
      summary: Resolve a protected Seea registry item and its source files
      security:
        - registryKey: []
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/componentId"
      responses:
        "200": { description: Registry item with source files }
        "401": { description: Unauthorized }
        "404": { description: Item is absent or not redistributable }
        "503": { description: Registry credential has not been provisioned }
  /v1/install/plan:
    post:
      summary: Create a license-aware installation plan
      security:
        - registryKey: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                componentId: { type: string }
                sourceId: { type: string }
      responses:
        "200": { description: Policy-enforced installation plan }
        "400": { description: Invalid request }
        "401": { description: Unauthorized }
        "503": { description: Registry credential has not been provisioned }
  /internal/v1/capabilities:
    get:
      summary: Read service-to-service capabilities
      security:
        - serviceToken: []
        - bearerAuth: []
      responses:
        "200": { description: Internal capabilities }
        "401": { description: Unauthorized }
        "503": { description: Service credential has not been provisioned }
components:
  parameters:
    componentId:
      in: path
      name: componentId
      required: true
      schema:
        type: string
        pattern: "^[a-z0-9-]+$"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    registryKey:
      type: apiKey
      in: header
      name: x-seea-api-key
    serviceToken:
      type: apiKey
      in: header
      name: x-seea-service-token
