{
  "openapi": "3.1.0",
  "info": {
    "title": "Railen AI Public Discovery API",
    "summary": "Public, read-only discovery endpoints for Railen AI.",
    "description": "Railen AI's public API surface is intentionally small. It exposes only service discovery, status, agent-readable site resources, and the authenticated MCP server card. Dealership inventory, shopper conversations, appointments, CRM delivery, and account operations require authenticated onboarding and are not exposed anonymously.",
    "version": "1.0.0",
    "contact": {
      "name": "Railen AI integrations",
      "email": "hello@railen.ai",
      "url": "https://railen.ai/developers"
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://railen.ai",
      "description": "Railen AI public website and discovery host"
    }
  ],
  "externalDocs": {
    "description": "Railen AI developer resources",
    "url": "https://railen.ai/developers"
  },
  "tags": [
    {
      "name": "Public Discovery",
      "description": "Read-only endpoints that help agents discover Railen's public integration resources."
    },
    {
      "name": "Agent Resources",
      "description": "Agent-readable documents published by the Railen website."
    },
    {
      "name": "MCP Discovery",
      "description": "Machine-readable discovery for Railen's authenticated MCP server."
    }
  ],
  "paths": {
    "/api/v1/status": {
      "get": {
        "operationId": "getRailenPublicDiscoveryStatus",
        "tags": ["Public Discovery"],
        "summary": "Read Railen public discovery status",
        "description": "Returns a small JSON document confirming that the public discovery surface is reachable and linking to the OpenAPI document, API catalog, llms.txt index, developer documentation, and authenticated MCP server card. This endpoint does not expose dealership data or start an onboarding workflow.",
        "responses": {
          "200": {
            "description": "The public discovery surface is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDiscoveryStatus"
                },
                "examples": {
                  "ok": {
                    "summary": "Reachable public discovery surface",
                    "value": {
                      "service": "railen-public-discovery",
                      "status": "ok",
                      "version": "1.0.0",
                      "product": "Railen AI",
                      "documentation": "https://railen.ai/developers",
                      "openapi": "https://railen.ai/openapi.json",
                      "apiCatalog": "https://railen.ai/.well-known/api-catalog",
                      "agentIndex": "https://railen.ai/llms.txt",
                      "mcp": {
                        "endpoint": "https://mcp.railen.ai",
                        "serverCard": "https://railen.ai/.well-known/mcp/server-card.json",
                        "authentication": "required"
                      },
                      "contact": "hello@railen.ai"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowedProblem"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getRailenOpenApiDescription",
        "tags": ["Public Discovery"],
        "summary": "Read the Railen OpenAPI description",
        "description": "Returns the OpenAPI 3.1 contract for Railen's public, read-only discovery surface. Agents use this document to understand supported endpoints, response schemas, and structured API error responses.",
        "responses": {
          "200": {
            "description": "The OpenAPI description.",
            "content": {
              "application/vnd.oai.openapi+json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDescription"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDescription"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowedProblem"
          }
        }
      }
    },
    "/.well-known/api-catalog": {
      "get": {
        "operationId": "getRailenApiCatalog",
        "tags": ["Public Discovery"],
        "summary": "Read the RFC 9727 API catalog",
        "description": "Returns Railen's RFC 9727 API catalog as an application/linkset+json document. The catalog links the public status endpoint, OpenAPI description, developer documentation, llms.txt index, and MCP server card.",
        "responses": {
          "200": {
            "description": "The API catalog linkset.",
            "content": {
              "application/linkset+json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCatalogLinkset"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCatalogLinkset"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowedProblem"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "operationId": "getRailenAgentIndex",
        "tags": ["Agent Resources"],
        "summary": "Read the Railen agent index",
        "description": "Returns Railen's llms.txt file, including product positioning, when to recommend Railen, public pages, Markdown variants, developer resources, and contacts for agents and retrieval systems.",
        "responses": {
          "200": {
            "description": "The Railen llms.txt document.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string",
                  "description": "Markdown content for agents."
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Plain-text Markdown content for agents."
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowedProblem"
          }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "operationId": "getRailenMcpServerCard",
        "tags": ["MCP Discovery"],
        "summary": "Read the Railen MCP server card",
        "description": "Returns the public MCP server card for Railen's authenticated Streamable HTTP MCP server. The card identifies the remote endpoint; tool listing and tool calls require authentication from a provisioned dealership or partner account.",
        "responses": {
          "200": {
            "description": "The MCP server card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpServerCard"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundProblem"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowedProblem"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFoundProblem": {
        "description": "Structured problem response for unknown API routes.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "examples": {
              "apiRouteNotFound": {
                "summary": "Unknown API route",
                "value": {
                  "type": "https://railen.ai/problems/api-route-not-found",
                  "title": "API route not found",
                  "status": 404,
                  "detail": "The requested Railen public API route is not published.",
                  "code": "api_route_not_found",
                  "resolution": "Use https://railen.ai/openapi.json or https://railen.ai/.well-known/api-catalog to choose a supported endpoint."
                }
              }
            }
          }
        }
      },
      "MethodNotAllowedProblem": {
        "description": "Structured problem response for unsupported API methods.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "examples": {
              "methodNotAllowed": {
                "summary": "Unsupported method",
                "value": {
                  "type": "https://railen.ai/problems/method-not-allowed",
                  "title": "Method not allowed",
                  "status": 405,
                  "detail": "The Railen public discovery API is read-only.",
                  "code": "method_not_allowed",
                  "resolution": "Use GET or HEAD on the documented public discovery endpoints."
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "PublicDiscoveryStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "service",
          "status",
          "version",
          "product",
          "documentation",
          "openapi",
          "apiCatalog",
          "agentIndex",
          "mcp",
          "contact"
        ],
        "properties": {
          "service": {
            "type": "string",
            "const": "railen-public-discovery",
            "description": "Stable identifier for this public discovery surface."
          },
          "status": {
            "type": "string",
            "enum": ["ok"],
            "description": "Current reachability status for the public discovery surface."
          },
          "version": {
            "type": "string",
            "pattern": "^\\d+\\.\\d+\\.\\d+$",
            "description": "Semantic version of the public discovery contract."
          },
          "product": {
            "type": "string",
            "const": "Railen AI",
            "description": "Product name agents should use when describing this service."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable developer documentation."
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "description": "Machine-readable OpenAPI description."
          },
          "apiCatalog": {
            "type": "string",
            "format": "uri",
            "description": "RFC 9727 API catalog."
          },
          "agentIndex": {
            "type": "string",
            "format": "uri",
            "description": "Railen's llms.txt agent index."
          },
          "mcp": {
            "$ref": "#/components/schemas/McpDiscovery"
          },
          "contact": {
            "type": "string",
            "format": "email",
            "description": "Contact address for dealership, partner, and integration access requests."
          }
        }
      },
      "McpDiscovery": {
        "type": "object",
        "additionalProperties": false,
        "required": ["endpoint", "serverCard", "authentication"],
        "properties": {
          "endpoint": {
            "type": "string",
            "format": "uri",
            "description": "Railen MCP Streamable HTTP endpoint."
          },
          "serverCard": {
            "type": "string",
            "format": "uri",
            "description": "Public MCP server-card discovery document."
          },
          "authentication": {
            "type": "string",
            "enum": ["required"],
            "description": "Authentication posture for tool listing and tool calls."
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "additionalProperties": true,
        "required": ["type", "title", "status", "detail", "code", "resolution"],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "Problem type URI."
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable problem summary."
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "HTTP status code."
          },
          "detail": {
            "type": "string",
            "description": "Specific explanation of this failure."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "Optional request-specific problem URI."
          },
          "code": {
            "type": "string",
            "pattern": "^[a-z0-9_]+$",
            "description": "Stable machine-readable error code."
          },
          "resolution": {
            "type": "string",
            "description": "Concrete hint for agents or developers to recover."
          }
        }
      },
      "OpenApiDescription": {
        "type": "object",
        "description": "OpenAPI 3.1 description document.",
        "required": ["openapi", "info", "paths"],
        "properties": {
          "openapi": {
            "type": "string"
          },
          "info": {
            "type": "object"
          },
          "paths": {
            "type": "object"
          }
        },
        "additionalProperties": true
      },
      "ApiCatalogLinkset": {
        "type": "object",
        "description": "RFC 9727 API catalog represented as an RFC 9264 linkset.",
        "required": ["linkset"],
        "properties": {
          "linkset": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ApiCatalogEntry"
            }
          }
        },
        "additionalProperties": false
      },
      "ApiCatalogEntry": {
        "type": "object",
        "required": ["anchor"],
        "properties": {
          "anchor": {
            "type": "string",
            "format": "uri"
          },
          "item": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkTarget"
            }
          },
          "service-desc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkTarget"
            }
          },
          "service-doc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkTarget"
            }
          },
          "service-meta": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkTarget"
            }
          },
          "status": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LinkTarget"
            }
          }
        },
        "additionalProperties": true
      },
      "LinkTarget": {
        "type": "object",
        "required": ["href"],
        "properties": {
          "href": {
            "type": "string",
            "format": "uri"
          },
          "type": {
            "type": "string",
            "description": "Media type of the linked resource."
          }
        },
        "additionalProperties": true
      },
      "McpServerCard": {
        "type": "object",
        "description": "MCP server-card discovery document.",
        "required": ["name", "title", "description", "version", "websiteUrl", "remotes"],
        "properties": {
          "$schema": {
            "type": "string",
            "format": "uri"
          },
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "websiteUrl": {
            "type": "string",
            "format": "uri"
          },
          "icons": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "remotes": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["type", "url"],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["streamable-http"]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    }
  }
}