fal

fal Serverless Platform API

Programmatic management of custom fal Serverless applications — list, inspect, deploy, scale, and monitor user-defined GPU functions deployed with `@fal.function`, `fal.App`, or BYO containers. Covers app metadata, secrets, file volumes, scaling parameters (`keep_alive`, `min_concurrency`), and execution analytics.

fal Serverless Platform API is one of 9 APIs that fal publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include AI, Serverless, GPU, Deployments, and Platform. The published artifact set on APIs.io includes API documentation, SDKs, an OpenAPI specification, and 1 Naftiko capability spec.

GitHub OpenAPI

Documentation

📖
Documentation
https://fal.ai/docs/private-serverless-models

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fal-ai/refs/heads/main/openapi/fal-serverless-platform-api-openapi.yml

SDKs

📦
SDK
https://github.com/fal-ai/fal

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/fal-ai/refs/heads/main/capabilities/serverless-apps.yaml

OpenAPI Specification

fal-serverless-platform-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: fal Serverless Platform API
  description: >
    Platform control-plane endpoints for managing fal Serverless applications —
    custom GPU functions and apps deployed using `@fal.function`, `fal.App`, or
    bring-your-own containers. Covers app metadata, scaling, secrets, files,
    and execution analytics. This API backs the `fal` CLI (`fal apps list`,
    `fal secrets`, `fal deploy`).
  version: 'v1'
  contact:
    name: fal Support
    url: https://fal.ai/support
  license:
    name: fal Terms of Service
    url: https://fal.ai/legal/terms-of-service

servers:
  - url: https://rest.alpha.fal.ai
    description: fal REST control-plane

security:
  - FalKeyAuth: []

tags:
  - name: Apps
    description: List and inspect deployed Serverless apps.
  - name: Secrets
    description: Manage per-org secrets injected into Serverless runs.
  - name: Files
    description: Manage files on persistent Serverless `/data` volumes.

paths:
  /serverless/apps:
    get:
      summary: List Serverless Apps
      description: Return every Serverless app deployed under the calling key's organization.
      operationId: listApps
      tags:
        - Apps
      responses:
        '200':
          description: Apps owned by the organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServerlessApp'
              examples:
                Apps:
                  $ref: '#/components/examples/AppsExample'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /serverless/apps/{app_id}:
    get:
      summary: Get Serverless App
      description: Retrieve metadata, endpoint URL, and current scaling parameters for an app.
      operationId: getApp
      tags:
        - Apps
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: App detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerlessApp'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /serverless/secrets:
    get:
      summary: List Serverless Secrets
      description: Return secret names available to all Serverless apps in the calling org. Values are never returned.
      operationId: listSecrets
      tags:
        - Secrets
      responses:
        '200':
          description: Secret names.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Set Serverless Secret
      description: Create or replace a named secret injected as an env var into Serverless runs.
      operationId: setSecret
      tags:
        - Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretWrite'
      responses:
        '200':
          description: Secret saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /serverless/files:
    get:
      summary: List Serverless Files
      description: List files on the persistent `/data` volume mounted into Serverless runs.
      operationId: listFiles
      tags:
        - Files
      parameters:
        - name: path
          in: query
          required: false
          description: Subdirectory path under `/data` to list.
          schema:
            type: string
      responses:
        '200':
          description: File listing.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileEntry'

components:
  securitySchemes:
    FalKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Pass the fal API key as `Authorization: Key $FAL_KEY`.'

  parameters:
    AppId:
      name: app_id
      in: path
      required: true
      description: Serverless app identifier (e.g. `my-org/my-flux-finetune`).
      schema:
        type: string

  schemas:
    ServerlessApp:
      type: object
      required: [id, name, endpoint]
      properties:
        id:
          type: string
        name:
          type: string
        endpoint:
          type: string
          format: uri
          description: Invocation URL for the app.
        gpu:
          type: string
          description: GPU class (e.g. `H100`, `A100`).
        keep_alive:
          type: integer
          description: Seconds a warm worker is kept after the last request.
        min_concurrency:
          type: integer
        max_concurrency:
          type: integer
        public:
          type: boolean

    Secret:
      type: object
      required: [name]
      properties:
        name:
          type: string
        created_at:
          type: string
          format: date-time

    SecretWrite:
      type: object
      required: [name, value]
      properties:
        name:
          type: string
        value:
          type: string
          format: password

    FileEntry:
      type: object
      properties:
        path:
          type: string
        size:
          type: integer
        modified_at:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      properties:
        detail:
          type: string

  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: App or resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  examples:
    AppsExample:
      summary: Two deployed apps
      value:
        - id: my-org/flux-finetune
          name: flux-finetune
          endpoint: https://fal.run/my-org/flux-finetune
          gpu: H100
          keep_alive: 60
          min_concurrency: 0
          max_concurrency: 8
          public: false
        - id: my-org/sdxl-lcm
          name: sdxl-lcm
          endpoint: https://fal.run/my-org/sdxl-lcm
          gpu: A100
          keep_alive: 120
          min_concurrency: 1
          max_concurrency: 16
          public: true