openapi: 3.0.3
info:
  title: Modal Web Endpoints (Representative)
  description: >-
    REPRESENTATIVE SPECIFICATION - NOT A FIRST-PARTY MODAL REST API.

    Modal's primary developer interface is the Python SDK (plus JavaScript and
    Go SDKs) and the `modal` CLI, communicating with Modal's backend over gRPC.
    Modal does NOT publish a conventional first-party public REST API for
    defining or invoking infrastructure.

    The only genuine HTTPS surface is USER-DEPLOYED web endpoints: functions
    decorated with @modal.fastapi_endpoint (formerly @modal.web_endpoint),
    @modal.asgi_app, @modal.wsgi_app, or @modal.web_server are automatically
    served on *.modal.run. The URL host shape
    (https://<workspace>--<app>-<function>.modal.run) is fixed by Modal, but
    the routes, methods, and request/response schemas are entirely defined by
    the developer's own code. A running Sandbox can similarly expose a
    container port over an HTTPS network tunnel.

    This document illustrates the SHAPE of a typical user-deployed endpoint so
    the surface can be catalogued. It is representative only; the concrete
    contract varies per deployed function. Do not treat any path or schema
    below as an official Modal-owned endpoint.
  version: '1.0-representative'
  contact:
    name: Modal
    url: https://modal.com/docs/guide/webhooks
  license:
    name: Representative catalog artifact by API Evangelist
servers:
  - url: https://{workspace}--{app}-{function}.modal.run
    description: >-
      Representative host shape for a deployed Modal web endpoint. The concrete
      host is generated by Modal from the workspace, app, and function names.
    variables:
      workspace:
        default: your-workspace
        description: Modal workspace / username slug.
      app:
        default: your-app
        description: Deployed Modal App name.
      function:
        default: your-endpoint
        description: The decorated web-endpoint function name.
paths:
  /:
    get:
      operationId: invokeGetEndpoint
      summary: Invoke a GET web endpoint (representative)
      description: >-
        Representative GET handler for a function decorated with
        @modal.fastapi_endpoint(). Query parameters and response schema are
        defined by the developer's own function signature.
      parameters:
        - name: prompt
          in: query
          required: false
          description: Example developer-defined query parameter.
          schema:
            type: string
      responses:
        '200':
          description: Developer-defined success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepresentativeResponse'
        '500':
          description: Unhandled error in the user function.
    post:
      operationId: invokePostEndpoint
      summary: Invoke a POST web endpoint (representative)
      description: >-
        Representative POST handler for a function decorated with
        @modal.fastapi_endpoint(method="POST") or served via an ASGI/WSGI app.
        The request and response bodies are defined by the developer's own
        code (e.g. Pydantic models).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepresentativeRequest'
      responses:
        '200':
          description: Developer-defined success response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepresentativeResponse'
        '422':
          description: Validation error (when the endpoint uses FastAPI/Pydantic).
        '500':
          description: Unhandled error in the user function.
  /{proxy}:
    get:
      operationId: invokeAsgiRoute
      summary: Invoke an arbitrary route on an ASGI/WSGI app (representative)
      description: >-
        For @modal.asgi_app, @modal.wsgi_app, and @modal.web_server, the mounted
        application defines its own arbitrary routes. This catch-all path
        represents that any route/method combination the developer's framework
        exposes is reachable under the same *.modal.run host. This is not a
        Modal-owned route.
      parameters:
        - name: proxy
          in: path
          required: true
          description: Any path defined by the developer's mounted app.
          schema:
            type: string
      responses:
        '200':
          description: Developer-defined response for the matched route.
components:
  schemas:
    RepresentativeRequest:
      type: object
      description: >-
        Placeholder request body. The real schema is whatever the developer's
        function (or Pydantic model) declares.
      additionalProperties: true
      example:
        input: example value
    RepresentativeResponse:
      type: object
      description: >-
        Placeholder response body. The real schema is whatever the developer's
        function returns.
      additionalProperties: true
      example:
        result: example value