Modal Modal Web Endpoints (Representative) API

openapi: 3.0.3
info:
  title: Modal Web Endpoints (Representative) Modal Web Endpoints (Representative) Modal Web Endpoints (Representative) Modal Web Endpoints (Representative) API
  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.
tags:
- name: Modal Web Endpoints (Representative)
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.
      tags:
      - Modal Web Endpoints (Representative)
    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.
      tags:
      - Modal Web Endpoints (Representative)
  /{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.
      tags:
      - Modal Web Endpoints (Representative)
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