Clarity Cloud Functions Admin API

openapi: 3.2.0
info:
  title: Fast Cloud Functions Admin API
  version: 0.1.0
tags:
- name: cloud_functions_admin
paths:
  /api/v1/admin/projects/{project_id}/cloud-functions:
    get:
      tags:
      - cloud_functions_admin
      summary: List Functions
      description: The project's functions, newest first, each with its latest run.
      operationId: list_functions_api_v1_admin_projects__project_id__cloud_functions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - cloud_functions_admin
      summary: Create Function
      description: 'Create a function and deploy its first version. A bundle that breaks a rule is a 400 that

        says what to fix; a failed deploy is a 502, and the function stays ``failed`` until a code

        upload succeeds.'
      operationId: create_function_api_v1_admin_projects__project_id__cloud_functions_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunctionRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}:
    get:
      tags:
      - cloud_functions_admin
      summary: Get Function
      description: 'One function: settings, status, schedule and the state its last successful run saved.'
      operationId: get_function_api_v1_admin_projects__project_id__cloud_functions__function_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - cloud_functions_admin
      summary: Update Function
      description: 'Change description, timeout, memory or whether it serves HTTP; a deployed function gets the

        new settings at once.'
      operationId: update_function_api_v1_admin_projects__project_id__cloud_functions__function_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFunctionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - cloud_functions_admin
      summary: Delete Function
      description: Delete the schedule, the Lambda, the stored code and the run history.
      operationId: delete_function_api_v1_admin_projects__project_id__cloud_functions__function_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/code:
    put:
      tags:
      - cloud_functions_admin
      summary: Update Code
      description: 'Upload new code: a new version, deployed before the response returns.'
      operationId: update_code_api_v1_admin_projects__project_id__cloud_functions__function_id__code_put
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCodeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/schedule:
    put:
      tags:
      - cloud_functions_admin
      summary: Set Schedule
      description: Set or replace the schedule; it starts enabled. Runs at most every 5 minutes.
      operationId: set_schedule_api_v1_admin_projects__project_id__cloud_functions__function_id__schedule_put
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - cloud_functions_admin
      summary: Remove Schedule
      description: Remove the schedule; the function stays and can still be invoked.
      operationId: remove_schedule_api_v1_admin_projects__project_id__cloud_functions__function_id__schedule_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/schedule/pause:
    post:
      tags:
      - cloud_functions_admin
      summary: Pause Schedule
      description: Stop scheduled runs and keep the schedule.
      operationId: pause_schedule_api_v1_admin_projects__project_id__cloud_functions__function_id__schedule_pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/schedule/resume:
    post:
      tags:
      - cloud_functions_admin
      summary: Resume Schedule
      description: Start scheduled runs again.
      operationId: resume_schedule_api_v1_admin_projects__project_id__cloud_functions__function_id__schedule_resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/invoke:
    post:
      tags:
      - cloud_functions_admin
      summary: Invoke Function
      description: 'Run now. ``sync`` waits and returns the finished run (only for functions whose timeout is

        at most 60 s); ``async`` returns ``202`` with the run, which finishes later.'
      operationId: invoke_function_api_v1_admin_projects__project_id__cloud_functions__function_id__invoke_post
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__cloud_functions__schemas__RunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/runs:
    get:
      tags:
      - cloud_functions_admin
      summary: List Runs
      description: Run history, newest first.
      operationId: list_runs_api_v1_admin_projects__project_id__cloud_functions__function_id__runs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__cloud_functions__schemas__RunListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/cloud-functions/{function_id}/runs/{run_id}:
    get:
      tags:
      - cloud_functions_admin
      summary: Get Run
      description: 'One run: status, output, error and the log tail of a sync run.'
      operationId: get_run_api_v1_admin_projects__project_id__cloud_functions__function_id__runs__run_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: function_id
        in: path
        required: true
        schema:
          type: integer
          title: Function Id
      - name: run_id
        in: path
        required: true
        schema:
          type: integer
          title: Run Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__cloud_functions__schemas__RunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RunSummary:
      properties:
        id:
          type: integer
          title: Id
        status:
          $ref: '#/components/schemas/src__cloud_functions__constants__RunStatus'
        trigger_type:
          $ref: '#/components/schemas/RunTrigger'
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
      type: object
      required:
      - id
      - status
      - trigger_type
      - started_at
      - finished_at
      - duration_ms
      title: RunSummary
      description: 'A run in one line, for a function list: what happened last and when.'
    InvokeRequest:
      properties:
        input:
          additionalProperties: true
          type: object
          title: Input
        mode:
          $ref: '#/components/schemas/RunMode-Input'
          description: '`sync` waits for the result; `async` returns a run.'
          default: sync
      additionalProperties: false
      type: object
      title: InvokeRequest
    ScheduleRequest:
      properties:
        expression:
          type: string
          title: Expression
          description: 5-field cron (`0 8 * * *`) or `rate(1 hour)`; at least 5 minutes apart.
        timezone:
          type: string
          title: Timezone
          description: IANA timezone the cron is read in.
          default: UTC
        input:
          additionalProperties: true
          type: object
          title: Input
          description: The `input` every scheduled run gets.
      additionalProperties: false
      type: object
      required:
      - expression
      title: ScheduleRequest
    CreateFunctionRequest:
      properties:
        name:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{0,62}$
          title: Name
          description: 'Unique in the project: lowercase letters, digits, hyphens.'
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        handler:
          type: string
          title: Handler
          description: '`module.function`, e.g. `main.handler`.'
          default: main.handler
        timeout_s:
          type: integer
          maximum: 900.0
          minimum: 1.0
          title: Timeout S
          description: Seconds before Lambda stops a run.
          default: 60
        memory_mb:
          type: integer
          maximum: 2048.0
          minimum: 128.0
          title: Memory Mb
          description: Memory in MB; CPU scales with it.
          default: 256
        code_zip_base64:
          type: string
          minLength: 1
          title: Code Zip Base64
          description: 'The zip, base64: the handler module at its root plus vendored packages.'
        http_enabled:
          type: boolean
          title: Http Enabled
          description: 'Serve the function''s own routes to mini-apps (`voc.functions.fetch`): the handler gets API Gateway HTTP API v2 events. Needs `timeout_s` <= 30.'
          default: false
      additionalProperties: false
      type: object
      required:
      - name
      - code_zip_base64
      title: CreateFunctionRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ScheduleStatus:
      type: string
      enum:
      - none
      - enabled
      - paused
      title: ScheduleStatus
    RunTrigger:
      type: string
      enum:
      - manual
      - schedule
      - http
      title: RunTrigger
    UpdateFunctionRequest:
      properties:
        description:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Description
        timeout_s:
          anyOf:
          - type: integer
            maximum: 900.0
            minimum: 1.0
          - type: 'null'
          title: Timeout S
        memory_mb:
          anyOf:
          - type: integer
            maximum: 2048.0
            minimum: 128.0
          - type: 'null'
          title: Memory Mb
        http_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Http Enabled
          description: 'Serve the function''s own routes to mini-apps (`voc.functions.fetch`): the handler gets API Gateway HTTP API v2 events. Needs `timeout_s` <= 30.'
      additionalProperties: false
      type: object
      title: UpdateFunctionRequest
    src__cloud_functions__constants__RunMode:
      type: string
      enum:
      - sync
      - async
      title: RunMode
    RunMode-Input:
      type: string
      enum:
      - sync
      - async
      title: RunMode
    UpdateCodeRequest:
      properties:
        code_zip_base64:
          type: string
          minLength: 1
          title: Code Zip Base64
          description: 'The zip, base64: the handler module at its root plus vendored packages.'
        handler:
          anyOf:
          - type: string
          - type: 'null'
          title: Handler
          description: Keeps the current handler when omitted.
      additionalProperties: false
      type: object
      required:
      - code_zip_base64
      title: UpdateCodeRequest
    FunctionListResponse:
      properties:
        functions:
          items:
            $ref: '#/components/schemas/FunctionResponse'
          type: array
          title: Functions
      type: object
      required:
      - functions
      title: FunctionListResponse
    src__cloud_functions__schemas__RunResponse:
      properties:
        id:
          type: integer
          title: Id
        function_id:
          type: integer
          title: Function Id
        version:
          type: integer
          title: Version
        trigger_type:
          $ref: '#/components/schemas/RunTrigger'
        mode:
          $ref: '#/components/schemas/src__cloud_functions__constants__RunMode'
        status:
          $ref: '#/components/schemas/src__cloud_functions__constants__RunStatus'
        input:
          additionalProperties: true
          type: object
          title: Input
        output:
          anyOf:
          - {}
          - type: 'null'
          title: Output
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        log_tail:
          anyOf:
          - type: string
          - type: 'null'
          title: Log Tail
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
        created_at:
          type: string
          format: date-time
          title: Created At
        scheduled_for:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled For
          description: The schedule slot of a scheduled run.
      type: object
      required:
      - id
      - function_id
      - version
      - trigger_type
      - mode
      - status
      - input
      - output
      - error
      - log_tail
      - started_at
      - finished_at
      - duration_ms
      - created_at
      title: RunResponse
    src__cloud_functions__constants__RunStatus:
      type: string
      enum:
      - running
      - succeeded
      - failed
      - timed_out
      title: RunStatus
    src__cloud_functions__schemas__RunListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/src__cloud_functions__schemas__RunResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
      type: object
      required:
      - items
      - total
      title: RunListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FunctionStatus:
      type: string
      enum:
      - deploying
      - active
      - failed
      title: FunctionStatus
    FunctionResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        handler:
          type: string
          title: Handler
        timeout_s:
          type: integer
          title: Timeout S
        memory_mb:
          type: integer
          title: Memory Mb
        status:
          $ref: '#/components/schemas/FunctionStatus'
        deploy_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Deploy Error
        current_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Version
        schedule_expression:
          anyOf:
          - type: string
          - type: 'null'
          title: Schedule Expression
        schedule_timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Schedule Timezone
        schedule_input:
          additionalProperties: true
          type: object
          title: Schedule Input
        schedule_status:
          $ref: '#/components/schemas/ScheduleStatus'
        state:
          additionalProperties: true
          type: object
          title: State
        http_enabled:
          type: boolean
          title: Http Enabled
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        last_run:
          anyOf:
          - $ref: '#/components/schemas/RunSummary'
          - type: 'null'
          description: The newest run, in list responses only.
      type: object
      required:
      - id
      - name
      - description
      - handler
      - timeout_s
      - memory_mb
      - status
      - deploy_error
      - current_version
      - schedule_expression
      - schedule_timezone
      - schedule_input
      - schedule_status
      - state
      - http_enabled
      - created_at
      - updated_at
      title: FunctionResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic