openapi: 3.1.0
info:
  title: Streamlit Community Cloud Apps API
  description: The Streamlit Community Cloud API provides programmatic access to manage Streamlit applications hosted on Community Cloud. Developers can use this API to deploy apps from GitHub repositories, manage app secrets, view deployment logs, restart apps, and manage workspace settings. Authentication uses Streamlit-issued API tokens.
  version: 1.0.0
  contact:
    name: Streamlit Support
    url: https://discuss.streamlit.io
  termsOfService: https://streamlit.io/terms-of-use
servers:
- url: https://api.streamlit.io/v1
  description: Streamlit Community Cloud API
security:
- streamlitBearerAuth: []
tags:
- name: Apps
  description: Manage Streamlit applications deployed on Community Cloud. Deploy, list, restart, and delete apps connected to GitHub repositories.
paths:
  /apps:
    get:
      operationId: listApps
      summary: List Apps
      description: Returns a list of all Streamlit applications deployed in the authenticated workspace.
      tags:
      - Apps
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of apps per page
        schema:
          type: integer
          default: 25
      responses:
        '200':
          description: A list of Streamlit apps
          content:
            application/json:
              schema:
                type: object
                properties:
                  apps:
                    type: array
                    items:
                      $ref: '#/components/schemas/App'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: deployApp
      summary: Deploy App
      description: Deploys a new Streamlit application from a GitHub repository. The repository must be accessible to the authenticated workspace. The app will be built and deployed from the specified branch and file path.
      tags:
      - Apps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppDeployRequest'
      responses:
        '201':
          description: App deployment initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /apps/{appId}:
    get:
      operationId: getApp
      summary: Get App
      description: Returns the details of a specific Streamlit application including its deployment status, GitHub connection, and URL.
      tags:
      - Apps
      parameters:
      - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The app details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteApp
      summary: Delete App
      description: Deletes a Streamlit application from Community Cloud. This action is irreversible and removes the deployment but does not affect the GitHub repository.
      tags:
      - Apps
      parameters:
      - $ref: '#/components/parameters/AppId'
      responses:
        '204':
          description: App deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /apps/{appId}/restart:
    post:
      operationId: restartApp
      summary: Restart App
      description: Restarts a deployed Streamlit application. Useful for applying new secrets or recovering from an error state.
      tags:
      - Apps
      parameters:
      - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: App restart initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: The error code
        message:
          type: string
          description: A human-readable error message
    AppDeployRequest:
      type: object
      required:
      - repo
      - branch
      - mainFile
      properties:
        repo:
          type: string
          description: The GitHub repository to deploy from (org/repo format)
        branch:
          type: string
          description: The branch to deploy from
        mainFile:
          type: string
          description: The path to the main Python file (e.g., app.py)
        appName:
          type: string
          description: Optional custom name for the app
    Pagination:
      type: object
      properties:
        page:
          type: integer
        perPage:
          type: integer
        total:
          type: integer
    App:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the app
        name:
          type: string
          description: The display name of the app
        url:
          type: string
          format: uri
          description: The public URL of the deployed app
        status:
          type: string
          enum:
          - running
          - sleeping
          - error
          - building
          - deploying
          description: The current status of the app
        repo:
          type: string
          description: The GitHub repository (org/repo format)
        branch:
          type: string
          description: The GitHub branch to deploy from
        mainFile:
          type: string
          description: The path to the main app file (e.g., app.py, streamlit_app.py)
        createdAt:
          type: string
          format: date-time
          description: When the app was first deployed
        updatedAt:
          type: string
          format: date-time
          description: When the app was last updated or restarted
        owner:
          type: string
          description: The GitHub username or org that owns the repository
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AppId:
      name: appId
      in: path
      required: true
      description: The unique identifier of the Streamlit app
      schema:
        type: string
  securitySchemes:
    streamlitBearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token issued from the Streamlit Community Cloud account settings. Include as Authorization: Bearer {token}.'
externalDocs:
  description: Streamlit Community Cloud Documentation
  url: https://docs.streamlit.io/deploy/streamlit-community-cloud