{
  "openapi": "3.1.0",
  "info": {
    "title": "Fred public API",
    "version": "0.2.0",
    "summary": "Agent-facing discovery and capability endpoints for Fred.",
    "description": "Fred is the agent surface of Fireflies.ai. This document covers the endpoints that are reachable without a session — discovery, capability and health — plus the authenticated MCP transport. Meeting data itself lives behind the Fireflies GraphQL API, described under `servers` and linked from `externalDocs`.",
    "termsOfService": "https://fireflies.ai/terms-of-service",
    "contact": {
      "name": "Fireflies support",
      "email": "support@fireflies.ai",
      "url": "https://pr-1710-askfred.fireflies.dev/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://fireflies.ai/terms-of-service"
    }
  },
  "externalDocs": {
    "description": "Fireflies GraphQL API reference (meetings, transcripts, summaries)",
    "url": "https://docs.fireflies.ai/graphql-api/query/introduction"
  },
  "servers": [
    {
      "url": "https://pr-1710-askfred.fireflies.dev",
      "description": "Fred application origin"
    },
    {
      "url": "https://api.fireflies.ai",
      "description": "Fireflies platform API (GraphQL, authenticated)"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Endpoints that describe Fred to an agent."
    },
    {
      "name": "Operations",
      "description": "Service health."
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol transport."
    }
  ],
  "paths": {
    "/api/public/capabilities": {
      "get": {
        "operationId": "getFredCapabilities",
        "tags": [
          "Discovery"
        ],
        "summary": "Describe what Fred can do and when to call it",
        "description": "Returns a structured capability manifest: the jobs Fred is the right tool for, the data it can reach, its refusal boundaries, and the authenticated surfaces to use for real work. Requires no authentication.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "description": "Media type to negotiate. This resource is served as JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Capability manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CapabilityManifest"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getFredHealth",
        "tags": [
          "Operations"
        ],
        "summary": "Service health",
        "description": "Liveness and dependency health for this Fred deployment. Returns 200 when healthy and 503 when a required dependency is unreachable. Requires no authentication.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "description": "Media type to negotiate. This resource is served as JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          },
          "503": {
            "description": "Service is unhealthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getFredLlmsTxt",
        "tags": [
          "Discovery"
        ],
        "summary": "Agent instructions in markdown",
        "description": "Human- and agent-readable description of Fred, including explicit when-to-use and when-not-to-use guidance. Served as text/markdown.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "description": "Media type to negotiate. This resource is always markdown.",
            "schema": {
              "type": "string",
              "default": "text/markdown"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown instruction file",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "No markdown representation is published for this path",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/markdown": {
      "get": {
        "operationId": "getFredPageAsMarkdown",
        "tags": [
          "Discovery"
        ],
        "summary": "Markdown representation of a public page",
        "description": "Returns the markdown variant of a public page. Reached either directly, or by requesting the page itself with `Accept: text/markdown` (acceptmarkdown.com), which negotiates here.",
        "security": [],
        "parameters": [
          {
            "in": "query",
            "name": "path",
            "required": true,
            "description": "Pathname of the public page to render as markdown.",
            "schema": {
              "type": "string",
              "enum": [
                "/",
                "/about",
                "/contact",
                "/privacy",
                "/developers"
              ],
              "default": "/"
            }
          },
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "description": "Media type to negotiate.",
            "schema": {
              "type": "string",
              "default": "text/markdown"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownDocument"
                }
              }
            }
          },
          "404": {
            "description": "No markdown representation is published for this path",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/mcp": {
      "get": {
        "operationId": "getFredMcpManifest",
        "tags": [
          "MCP"
        ],
        "summary": "MCP server manifest",
        "description": "Describes Fred’s Model Context Protocol server: transport, endpoint and authentication scheme. Discovery is public; the transport itself is authenticated.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "required": false,
            "description": "Media type to negotiate. This resource is served as JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MCP manifest",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpManifest"
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "callFredMcp",
        "tags": [
          "MCP"
        ],
        "summary": "MCP Streamable HTTP transport",
        "description": "JSON-RPC 2.0 over Streamable HTTP. Exposes Fred’s knowledge-base tools to MCP clients. Requires service credentials plus an `x-user-id` header identifying the user whose data is in scope.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Fireflies API key. Issued per user from the Fireflies dashboard; inherits that user’s access."
      }
    },
    "schemas": {
      "CapabilityManifest": {
        "type": "object",
        "required": [
          "product",
          "operator",
          "useFor",
          "doNotUseFor",
          "dataScope",
          "surfaces"
        ],
        "properties": {
          "product": {
            "type": "string",
            "description": "Product name.",
            "examples": [
              "Fred"
            ]
          },
          "operator": {
            "type": "string",
            "description": "Legal operator of the service."
          },
          "description": {
            "type": "string",
            "description": "One-line summary of the product."
          },
          "useFor": {
            "type": "array",
            "description": "Concrete jobs Fred is the correct tool for.",
            "items": {
              "type": "string"
            }
          },
          "doNotUseFor": {
            "type": "array",
            "description": "Requests Fred will refuse or answer poorly.",
            "items": {
              "type": "string"
            }
          },
          "dataScope": {
            "type": "string",
            "description": "What data Fred can reach, and on whose behalf."
          },
          "surfaces": {
            "type": "array",
            "description": "Programmatic entry points, most capable first.",
            "items": {
              "$ref": "#/components/schemas/Surface"
            }
          }
        }
      },
      "Surface": {
        "type": "object",
        "required": [
          "name",
          "url",
          "auth"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Human label for the surface."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute endpoint URL."
          },
          "protocol": {
            "type": "string",
            "enum": [
              "graphql",
              "mcp",
              "rest"
            ],
            "description": "Wire protocol."
          },
          "auth": {
            "type": "string",
            "enum": [
              "none",
              "bearer",
              "basic"
            ],
            "description": "Authentication required to call it."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "Reference documentation."
          }
        }
      },
      "McpManifest": {
        "type": "object",
        "required": [
          "schema_version",
          "name",
          "servers"
        ],
        "properties": {
          "schema_version": {
            "type": "string",
            "description": "MCP schema revision this manifest follows."
          },
          "name": {
            "type": "string",
            "description": "Server identifier."
          },
          "display_name": {
            "type": "string",
            "description": "Human label for the server."
          },
          "description": {
            "type": "string",
            "description": "What the server exposes."
          },
          "vendor": {
            "type": "string",
            "description": "Publishing organisation."
          },
          "homepage": {
            "type": "string",
            "format": "uri"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "privacy_policy": {
            "type": "string",
            "format": "uri"
          },
          "contact": {
            "type": "string",
            "description": "Support email."
          },
          "servers": {
            "type": "array",
            "description": "Transports this manifest advertises.",
            "items": {
              "$ref": "#/components/schemas/McpServerEntry"
            }
          }
        }
      },
      "McpServerEntry": {
        "type": "object",
        "required": [
          "name",
          "transport",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Server identifier."
          },
          "version": {
            "type": "string",
            "description": "Server version."
          },
          "transport": {
            "type": "string",
            "enum": [
              "streamable-http",
              "sse",
              "stdio"
            ],
            "description": "MCP transport in use."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute transport endpoint."
          },
          "authentication": {
            "$ref": "#/components/schemas/McpAuthentication"
          }
        }
      },
      "McpAuthentication": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "none",
              "basic",
              "bearer",
              "oauth2"
            ],
            "description": "Authentication scheme required by the transport."
          },
          "description": {
            "type": "string",
            "description": "How to obtain credentials."
          }
        }
      },
      "MarkdownDocument": {
        "type": "string",
        "description": "CommonMark document describing the requested resource."
      },
      "HealthStatus": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy",
              "unhealthy"
            ],
            "description": "Aggregate health of this deployment."
          },
          "responseTime": {
            "type": "integer",
            "description": "Check duration in milliseconds."
          },
          "checks": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Per-dependency status."
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "method": {
            "type": "string",
            "description": "MCP method, e.g. `tools/list`."
          },
          "params": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "$ref": "#/components/schemas/JsonRpcError"
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "JSON-RPC error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message."
          },
          "data": {
            "description": "Optional structured detail."
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem document returned by failing endpoints.",
        "required": [
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "detail": {
            "type": "string",
            "description": "Explanation specific to this occurrence."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "resolution": {
            "type": "string",
            "description": "What the caller should do next."
          }
        }
      }
    }
  }
}