openapi: 3.0.3
info:
  title: SparkLaunch Public Discovery API
  version: "1.0.0"
  description: Read-only public-content search, latest-doc, and static-guide metadata discovery for SparkLaunch.
servers:
  - url: https://sparklaun.ch
paths:
  /api/public:
    get:
      operationId: getSparkLaunchPublicApiIndex
      summary: Get the public discovery API index
      description: Lists the implemented read-only SparkLaunch public discovery endpoints and the canonical public OpenAPI URL.
      responses:
        "200":
          description: Public discovery API index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicApiIndexResponse"
  /api/public/search:
    get:
      operationId: searchPublicSparkLaunchContent
      summary: Search public SparkLaunch content
      description: Searches published guides, published blog posts, and curated public SparkLaunch pages. This endpoint returns public content only.
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
          description: Non-empty public search query.
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
          description: Maximum number of results. Values are clamped to 20.
      responses:
        "200":
          description: Public search results.
          content:
            application/json:
              schema:
                type: object
                required:
                  - query
                  - items
                properties:
                  query:
                    type: string
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PublicDiscoveryItem"
        "400":
          description: The search query is empty.
  /api/public/docs/latest:
    get:
      operationId: getLatestPublicSparkLaunchDocs
      summary: Get latest public SparkLaunch docs
      description: Returns newest published public guides and blog posts, with static public fallback entries when database content is unavailable.
      parameters:
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            default: 10
            maximum: 20
            minimum: 1
          description: Maximum number of results. Values are clamped to 20.
        - in: query
          name: type
          required: false
          schema:
            type: string
            enum:
              - all
              - guide
              - blog
            default: all
          description: Public doc type filter.
      responses:
        "200":
          description: Latest public docs.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/PublicDiscoveryItem"
  /api/public/guides/static-metadata:
    get:
      operationId: getPublishedStaticGuideMetadata
      summary: Get published static guide metadata
      description: Returns published metadata for registered code-owned SparkLaunch guide pages. This endpoint returns public listing metadata only, not editable guide body content.
      responses:
        "200":
          description: Published static guide metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/GuideSummary"
        "500":
          description: Public guide metadata could not be loaded.
  /api/public/guides/static-metadata/{slug}:
    get:
      operationId: getPublishedStaticGuideMetadataBySlug
      summary: Get published static guide metadata by slug
      description: Returns published metadata for one registered code-owned SparkLaunch guide page. Unpublished or unregistered slugs return a not-found response.
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Static guide slug.
      responses:
        "200":
          description: Published static guide metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuideSummary"
        "404":
          description: Static guide metadata was not found or is unpublished.
        "500":
          description: Public guide metadata could not be loaded.
components:
  schemas:
    PublicApiIndexResponse:
      type: object
      required:
        - service
        - version
        - openapi_url
        - endpoints
      properties:
        service:
          type: string
        version:
          type: string
        openapi_url:
          type: string
          format: uri
        endpoints:
          type: array
          items:
            $ref: "#/components/schemas/PublicApiEndpoint"
    PublicApiEndpoint:
      type: object
      required:
        - method
        - path
        - description
      properties:
        method:
          type: string
          enum:
            - GET
        path:
          type: string
        description:
          type: string
    PublicDiscoveryItem:
      type: object
      required:
        - type
        - title
        - url
        - source
        - tags
      properties:
        type:
          type: string
          enum:
            - guide
            - blog
            - page
            - compare
        title:
          type: string
        url:
          type: string
          format: uri
        summary:
          type: string
          nullable: true
        source:
          type: string
          enum:
            - guide
            - blog
            - static-public-index
            - static-fallback
        updated_at:
          type: string
          nullable: true
          description: ISO 8601 timestamp or public static update timestamp.
        tags:
          type: array
          items:
            type: string
    GuideSummary:
      type: object
      required:
        - id
        - title
        - slug
        - category
        - difficulty
        - author_id
        - author_name
        - published
        - featured
        - order_index
        - created_at
        - guide_type
        - editable_content
      properties:
        id:
          type: integer
          description: Stable negative ID for code-owned static guides.
        title:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        category:
          type: string
        difficulty:
          type: string
        estimated_time:
          type: string
          nullable: true
        author_id:
          type: integer
        author_name:
          type: string
        published:
          type: boolean
        featured:
          type: boolean
        order_index:
          type: integer
        tags:
          type: array
          nullable: true
          items:
            type: string
        created_at:
          type: string
        published_at:
          type: string
          nullable: true
        guide_type:
          type: string
          enum:
            - static
        path:
          type: string
          nullable: true
        editable_content:
          type: boolean