# RocketLauncher AI public API (PLANNED, read-only)
#
# This is the documented contract for a read-only public API surface that backs
# the RocketLauncher MCP server (mcp.rocketlauncher.ai). It describes the five
# read-only tools exposed to AI agents. No write endpoints exist at launch.
# Treat this as the planned spec: the endpoints are documented here first so
# agents and the MCP layer share one contract.
openapi: 3.1.0
info:
  title: RocketLauncher AI Public API
  version: 0.1.0
  summary: Read-only API for querying the RocketLauncher GoHighLevel knowledge base.
  description: >
    A read-only public API over the RocketLauncher knowledge base. It lets AI
    agents search GoHighLevel API recipes, look up glossary terms, list
    use-case playbooks by vertical, read the changelog, and look up a feature.
    There are no write endpoints at launch. This spec is the planned contract
    that the RocketLauncher MCP server mirrors as read-only tools.
  contact:
    name: RocketLauncher AI
    url: https://rocketlauncher.ai/agents
  license:
    name: RocketLauncher Terms
    url: https://rocketlauncher.ai/terms
servers:
  - url: https://api.rocketlauncher.ai
    description: Planned read-only API host.
tags:
  - name: read-only
    description: All endpoints are read-only at launch. No write tools exist yet.
paths:
  /v1/recipes/search:
    get:
      operationId: search_recipes
      summary: Search GoHighLevel API recipes.
      description: Full-text search across the API and recipe pages. Read-only.
      tags:
        - read-only
      parameters:
        - name: q
          in: query
          required: true
          description: Search query, for example "create contact" or "webhook signature".
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        "200":
          description: Matching recipes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Recipe"
  /v1/glossary/{slug}:
    get:
      operationId: get_glossary_term
      summary: Get one GoHighLevel glossary term.
      description: Return the definition and explanation for a single glossary term. Read-only.
      tags:
        - read-only
      parameters:
        - name: slug
          in: path
          required: true
          description: The glossary term slug, for example "snapshot" or "saas-mode".
          schema:
            type: string
      responses:
        "200":
          description: The glossary term.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlossaryTerm"
        "404":
          description: No term with that slug.
  /v1/use-cases:
    get:
      operationId: list_use_cases_by_vertical
      summary: List use-case playbooks, optionally filtered by vertical.
      description: Return use-case playbooks. Pass a vertical to filter. Read-only.
      tags:
        - read-only
      parameters:
        - name: vertical
          in: query
          required: false
          description: Industry slug to filter by, for example "dentists" or "real-estate".
          schema:
            type: string
      responses:
        "200":
          description: Matching use-case playbooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/UseCase"
  /v1/changelog:
    get:
      operationId: get_changelog_since
      summary: Get changelog entries since a date.
      description: Return GoHighLevel changelog entries published on or after a date. Read-only.
      tags:
        - read-only
      parameters:
        - name: since
          in: query
          required: false
          description: ISO 8601 date. Only entries on or after this date are returned.
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Changelog entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/ChangelogEntry"
  /v1/features/{slug}:
    get:
      operationId: lookup_ghl_feature
      summary: Look up one GoHighLevel feature.
      description: Return the reference entry for a GoHighLevel feature, including plan availability. Read-only.
      tags:
        - read-only
      parameters:
        - name: slug
          in: path
          required: true
          description: The feature slug, for example "voice-ai" or "saas-mode".
          schema:
            type: string
      responses:
        "200":
          description: The feature reference entry.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Feature"
        "404":
          description: No feature with that slug.
components:
  schemas:
    Recipe:
      type: object
      properties:
        title:
          type: string
        slug:
          type: string
        url:
          type: string
          format: uri
        summary:
          type: string
    GlossaryTerm:
      type: object
      properties:
        term:
          type: string
        slug:
          type: string
        definition:
          type: string
        url:
          type: string
          format: uri
    UseCase:
      type: object
      properties:
        title:
          type: string
        slug:
          type: string
        vertical:
          type: string
        url:
          type: string
          format: uri
        summary:
          type: string
    ChangelogEntry:
      type: object
      properties:
        title:
          type: string
        date:
          type: string
          format: date
        url:
          type: string
          format: uri
        summary:
          type: string
    Feature:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
        planAvailability:
          type: string
        url:
          type: string
          format: uri
        summary:
          type: string