{
  "openapi": "3.1.0",
  "info": {
    "title": "LottieFiles Docs API",
    "version": "1.0.0",
    "summary": "Search LottieFiles developer documentation and read pages as Markdown.",
    "description": "Public, read-only HTTP API for the LottieFiles developer documentation at docs.lottiefiles.com. Use it to search the docs and fetch any page as Markdown for grounding answers or generating code. The documentation endpoints need no authentication and allow cross-origin requests.\n\nThis document also describes the LottieFiles MCP server endpoint, which works with LottieFiles account data and requires OAuth 2.1. Connect to it with an MCP client rather than calling it directly.\n\nErrors use RFC 9457 problem details (`application/problem+json`) with a stable `code` member.",
    "contact": {
      "name": "LottieFiles Developer Portal",
      "url": "https://docs.lottiefiles.com/en/developers"
    }
  },
  "externalDocs": {
    "description": "LottieFiles Developer Portal",
    "url": "https://docs.lottiefiles.com/en/developers"
  },
  "servers": [
    {
      "url": "https://docs.lottiefiles.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Documentation",
      "description": "Search and read the LottieFiles developer documentation. Public and read-only."
    },
    {
      "name": "MCP",
      "description": "The hosted LottieFiles MCP server for AI assistants. Requires OAuth.",
      "externalDocs": {
        "url": "https://docs.lottiefiles.com/en/platform/mcp"
      }
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchDocs",
        "summary": "Search the documentation",
        "description": "Full-text search across LottieFiles documentation pages, ranked by relevance with title matches weighted highest. Returns page titles, descriptions, and URLs; fetch a result's full content with getDocPage or its markdownUrl. When a non-English locale has no matches, results fall back to English.",
        "tags": ["Documentation"],
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search terms, for example `dotlottie react player` or `state machine events`.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "example": "dotlottie react player"
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "Documentation locale to search.",
            "schema": {
              "type": "string",
              "enum": ["en", "zh", "ko"],
              "default": "en"
            }
          },
          {
            "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 pages, most relevant first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/page": {
      "get": {
        "operationId": "getDocPage",
        "summary": "Get a documentation page as Markdown",
        "description": "Returns one documentation page with its metadata and full Markdown content. Accepts a site path such as `/en/platform/mcp`, a path without a locale (served in English), or a full docs.lottiefiles.com URL. Pages without a translation fall back to English.",
        "tags": ["Documentation"],
        "security": [],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "Documentation page path or URL, for example `/en/runtimes/overview/quick-start`.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "/en/platform/mcp"
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "headers": {
              "Content-Language": {
                "description": "Locale the page was served in.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "Get the llms.txt documentation index",
        "description": "Curated Markdown index of the documentation for language models: what the docs cover, when to use them, and links to each section's Markdown.",
        "tags": ["Documentation"],
        "security": [],
        "responses": {
          "200": {
            "description": "The llms.txt index.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "servers": [
        {
          "url": "https://mcp.lottiefiles.com",
          "description": "LottieFiles MCP server"
        }
      ],
      "post": {
        "operationId": "sendMcpMessage",
        "summary": "Send a message to the LottieFiles MCP server",
        "description": "Model Context Protocol endpoint (Streamable HTTP transport, JSON-RPC 2.0) for working with LottieFiles workspaces, projects, and animations. Use an MCP client, which handles session setup, OAuth, and token refresh. Each request runs with the permissions of the LottieFiles account that approved access. The server accepts up to 60 requests per second.",
        "tags": ["MCP"],
        "externalDocs": {
          "url": "https://docs.lottiefiles.com/en/platform/mcp/tools"
        },
        "security": [
          {
            "lottiefilesOAuth": ["mcp:full"]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response, either as a single JSON body or as a server-sent event stream.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Missing, expired, or revoked access token. The WWW-Authenticate header points to the OAuth protected resource metadata."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "lottiefilesOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code flow with PKCE (S256). Clients register dynamically or with a client ID metadata document. Access tokens expire after 10 minutes and refresh tokens rotate. Protected resource metadata: https://mcp.lottiefiles.com/.well-known/oauth-protected-resource",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://mcp.lottiefiles.com/authorize",
            "tokenUrl": "https://mcp.lottiefiles.com/token",
            "refreshUrl": "https://mcp.lottiefiles.com/token",
            "scopes": {
              "mcp:full": "Act as the LottieFiles account that approved access: read, create, modify, and delete its workspaces, projects, and animations. This is currently the only scope."
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "A query parameter is missing or invalid. The `param` member names it.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "NotFound": {
        "description": "No documentation page exists at the requested path.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "required": ["query", "locale", "total", "results"],
        "properties": {
          "query": {
            "type": "string",
            "description": "The normalized search terms."
          },
          "locale": {
            "type": "string",
            "description": "Locale the results come from. English when the requested locale had no matches."
          },
          "total": {
            "type": "integer",
            "description": "Number of matching pages, which can exceed the number returned."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": ["title", "description", "section", "locale", "url", "markdownUrl", "score"],
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "Page summary. Empty when the page has none."
          },
          "section": {
            "type": "string",
            "description": "Top-level documentation section, for example `runtimes` or `platform`. Empty for the locale home page."
          },
          "locale": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Page URL for people."
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri",
            "description": "Page content as Markdown."
          },
          "score": {
            "type": "number",
            "description": "Relevance score. Higher is more relevant; only comparable within one response."
          }
        }
      },
      "Page": {
        "type": "object",
        "required": [
          "title",
          "description",
          "locale",
          "url",
          "markdownUrl",
          "updatedAt",
          "markdown"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "description": {
            "type": ["string", "null"]
          },
          "locale": {
            "type": "string",
            "description": "Locale the page was served in."
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          },
          "updatedAt": {
            "type": ["string", "null"],
            "description": "When the page content last changed, if known."
          },
          "markdown": {
            "type": "string",
            "description": "Full page content as Markdown (MDX components appear as JSX tags)."
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details.",
        "required": ["type", "title", "status", "code", "detail"],
        "properties": {
          "type": {
            "type": "string",
            "description": "Problem type URI. `about:blank` means the HTTP status describes the problem."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code.",
            "enum": [
              "invalid_query",
              "invalid_locale",
              "invalid_limit",
              "invalid_path",
              "page_not_found",
              "endpoint_not_found"
            ]
          },
          "detail": {
            "type": "string",
            "description": "What went wrong and how to fix the request."
          },
          "param": {
            "type": "string",
            "description": "The query parameter that caused the problem."
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": ["string", "integer"]
          },
          "method": {
            "type": "string",
            "description": "MCP method, for example `initialize`, `tools/list`, or `tools/call`."
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": ["string", "integer", "null"]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {}
            }
          }
        }
      }
    }
  }
}