openapi: 3.0.1
info:
  title: Golem Cloud API
  description: >-
    REST API for the Golem durable computing platform. Manage WebAssembly
    components, launch and invoke durable workers, define and deploy custom
    HTTP APIs (the Worker Gateway), and manage plugins. The same API is served
    by the open-source self-hosted Golem and by the managed Golem Cloud hosted
    service. Authenticate with a bearer token created from your account.
  termsOfService: https://www.golem.cloud/terms
  contact:
    name: Golem Cloud Support
    url: https://learn.golem.cloud
  license:
    name: BUSL-1.1
    url: https://github.com/golemcloud/golem/blob/main/LICENSE
  version: '1.0'
servers:
  - url: https://release.api.golem.cloud
    description: Golem Cloud managed hosted service
  - url: http://localhost:9881
    description: Local self-hosted Golem (default worker/registry service port)
security:
  - Token: []
tags:
  - name: Component
    description: WebAssembly component registry operations.
  - name: Worker
    description: Durable worker lifecycle and invocation operations.
  - name: ApiDefinition
    description: Custom HTTP API definitions and deployments (Worker Gateway).
  - name: Plugin
    description: Plugin registration and grants.
paths:
  /v1/envs/{environment_id}/components:
    post:
      tags:
        - Component
      operationId: createComponent
      summary: Create a new component in the environment
      description: Uploads a new WebAssembly component into the given environment.
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                component:
                  type: string
                  format: binary
      responses:
        '200':
          description: The created component metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Component'
        '400':
          $ref: '#/components/responses/Error'
    get:
      tags:
        - Component
      operationId: listEnvironmentComponents
      summary: List all components in the environment
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
      responses:
        '200':
          description: A list of components.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Component'
  /v1/envs/{environment_id}/components/{component_name}:
    get:
      tags:
        - Component
      operationId: getComponentByName
      summary: Get a component in the environment by name
      parameters:
        - $ref: '#/components/parameters/EnvironmentId'
        - name: component_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The component metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Component'
  /v1/components/{component_id}:
    get:
      tags:
        - Component
      operationId: getComponent
      summary: Get the latest version of a component by id
      parameters:
        - $ref: '#/components/parameters/ComponentId'
      responses:
        '200':
          description: The component metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Component'
    patch:
      tags:
        - Component
      operationId: updateComponent
      summary: Update a component with a new version
      parameters:
        - $ref: '#/components/parameters/ComponentId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                component:
                  type: string
                  format: binary
      responses:
        '200':
          description: The updated component metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Component'
    delete:
      tags:
        - Component
      operationId: deleteComponent
      summary: Delete a component
      parameters:
        - $ref: '#/components/parameters/ComponentId'
      responses:
        '200':
          description: Component deleted.
  /v1/components/{component_id}/revisions/{revision}/wasm:
    get:
      tags:
        - Component
      operationId: downloadComponentWasm
      summary: Download the WASM binary of a specific component revision
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - name: revision
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: The WASM binary.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /v1/components/{component_id}/workers:
    post:
      tags:
        - Worker
      operationId: launchNewWorker
      summary: Launch a new worker
      description: >-
        Creates a new durable worker (agent) from a component. The worker's
        execution is durably persisted and survives crashes and restarts.
      parameters:
        - $ref: '#/components/parameters/ComponentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerCreationRequest'
      responses:
        '200':
          description: The created worker id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerId'
    get:
      tags:
        - Worker
      operationId: getWorkersMetadata
      summary: Get metadata of multiple workers
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - name: cursor
          in: query
          schema:
            type: string
        - name: count
          in: query
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Page of worker metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkersMetadataResponse'
  /v1/components/{component_id}/workers/{agent_name}:
    get:
      tags:
        - Worker
      operationId: getWorkerMetadata
      summary: Get metadata of a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
      responses:
        '200':
          description: The worker metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerMetadata'
    delete:
      tags:
        - Worker
      operationId: deleteWorker
      summary: Delete a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
      responses:
        '200':
          description: Worker deleted.
  /v1/components/{component_id}/workers/{agent_name}/invoke:
    post:
      tags:
        - Worker
      operationId: invokeFunction
      summary: Invoke a function on a worker without waiting for a result
      description: Fire-and-forget invocation of an exported function on the worker.
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: function
          in: query
          required: true
          schema:
            type: string
        - name: idempotency-key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeParameters'
      responses:
        '200':
          description: Invocation accepted.
  /v1/components/{component_id}/workers/{agent_name}/invoke-and-await:
    post:
      tags:
        - Worker
      operationId: invokeAndAwaitFunction
      summary: Invoke a function on a worker and await its result
      description: >-
        Synchronous invocation of an exported function; blocks until the
        durable worker returns a result value.
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: function
          in: query
          required: true
          schema:
            type: string
        - name: idempotency-key
          in: header
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvokeParameters'
      responses:
        '200':
          description: The function result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvokeResult'
  /v1/components/{component_id}/workers/{agent_name}/interrupt:
    post:
      tags:
        - Worker
      operationId: interruptWorker
      summary: Interrupt a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: recovery-immediately
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Worker interrupted.
  /v1/components/{component_id}/workers/{agent_name}/resume:
    post:
      tags:
        - Worker
      operationId: resumeWorker
      summary: Resume a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
      responses:
        '200':
          description: Worker resumed.
  /v1/components/{component_id}/workers/{agent_name}/update:
    post:
      tags:
        - Worker
      operationId: updateWorker
      summary: Update a worker to a new component version
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkerRequest'
      responses:
        '200':
          description: Worker update scheduled.
  /v1/components/{component_id}/workers/{agent_name}/oplog:
    get:
      tags:
        - Worker
      operationId: getOplog
      summary: Get the oplog of a worker
      description: Returns the durable operation log that records every step of the worker.
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: from
          in: query
          schema:
            type: integer
            format: int64
        - name: count
          in: query
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: A page of oplog entries.
  /v1/components/{component_id}/workers/{agent_name}/connect:
    get:
      tags:
        - Worker
      operationId: connectWorker
      summary: Connect to a worker using a websocket and stream events
      description: >-
        Upgrades the HTTP connection to a WebSocket and streams live worker
        events (stdout, stderr, log output, and invocation events). Modeled in
        detail in asyncapi/golem-cloud-asyncapi.yml.
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
      responses:
        '101':
          description: Switching protocols to WebSocket.
  /v1/api/definitions:
    get:
      tags:
        - ApiDefinition
      operationId: listApiDefinitions
      summary: List HTTP API definitions
      description: >-
        Lists the custom HTTP API definitions (Worker Gateway) that map external
        HTTP routes onto worker invocations.
      parameters:
        - name: api-definition-id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of API definitions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HttpApiDefinition'
    post:
      tags:
        - ApiDefinition
      operationId: createApiDefinition
      summary: Create an HTTP API definition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpApiDefinition'
      responses:
        '200':
          description: The created API definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpApiDefinition'
  /v1/api/definitions/{id}/{version}:
    get:
      tags:
        - ApiDefinition
      operationId: getApiDefinition
      summary: Get an HTTP API definition by id and version
      parameters:
        - $ref: '#/components/parameters/ApiDefinitionId'
        - $ref: '#/components/parameters/ApiDefinitionVersion'
      responses:
        '200':
          description: The API definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpApiDefinition'
    put:
      tags:
        - ApiDefinition
      operationId: updateApiDefinition
      summary: Update an HTTP API definition
      parameters:
        - $ref: '#/components/parameters/ApiDefinitionId'
        - $ref: '#/components/parameters/ApiDefinitionVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpApiDefinition'
      responses:
        '200':
          description: The updated API definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpApiDefinition'
    delete:
      tags:
        - ApiDefinition
      operationId: deleteApiDefinition
      summary: Delete an HTTP API definition
      parameters:
        - $ref: '#/components/parameters/ApiDefinitionId'
        - $ref: '#/components/parameters/ApiDefinitionVersion'
      responses:
        '200':
          description: API definition deleted.
  /v1/api/deployments:
    get:
      tags:
        - ApiDefinition
      operationId: listApiDeployments
      summary: List HTTP API deployments
      parameters:
        - name: api-definition-id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of API deployments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiDeployment'
    post:
      tags:
        - ApiDefinition
      operationId: deployApiDefinition
      summary: Deploy an HTTP API definition to a host/domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiDeploymentRequest'
      responses:
        '200':
          description: The created deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDeployment'
  /v1/api/deployments/{site}:
    get:
      tags:
        - ApiDefinition
      operationId: getApiDeployment
      summary: Get an HTTP API deployment by site
      parameters:
        - name: site
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The API deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDeployment'
    delete:
      tags:
        - ApiDefinition
      operationId: deleteApiDeployment
      summary: Delete an HTTP API deployment
      parameters:
        - name: site
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deployment deleted.
  /v1/accounts/{account_id}/plugins:
    get:
      tags:
        - Plugin
      operationId: listPlugins
      summary: List registered plugins for an account
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: A list of plugins.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plugin'
    post:
      tags:
        - Plugin
      operationId: createPlugin
      summary: Register a new plugin
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Plugin'
      responses:
        '200':
          description: Plugin registered.
  /v1/plugins/{plugin_id}:
    get:
      tags:
        - Plugin
      operationId: getPlugin
      summary: Get a plugin by id
      parameters:
        - $ref: '#/components/parameters/PluginId'
      responses:
        '200':
          description: The plugin.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plugin'
    delete:
      tags:
        - Plugin
      operationId: deletePlugin
      summary: Delete a plugin
      parameters:
        - $ref: '#/components/parameters/PluginId'
      responses:
        '200':
          description: Plugin deleted.
  /v1/components/{component_id}/workers/{agent_name}/activate-plugin:
    post:
      tags:
        - Plugin
      operationId: activatePlugin
      summary: Activate a plugin on a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: plugin-installation-id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plugin activated.
  /v1/components/{component_id}/workers/{agent_name}/deactivate-plugin:
    post:
      tags:
        - Plugin
      operationId: deactivatePlugin
      summary: Deactivate a plugin on a worker
      parameters:
        - $ref: '#/components/parameters/ComponentId'
        - $ref: '#/components/parameters/AgentName'
        - name: plugin-installation-id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plugin deactivated.
components:
  securitySchemes:
    Token:
      type: http
      scheme: bearer
      description: >-
        Bearer token created for your Golem account. Pass it in the
        Authorization header as `Bearer <token>`.
  parameters:
    EnvironmentId:
      name: environment_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ComponentId:
      name: component_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AgentName:
      name: agent_name
      in: path
      required: true
      description: The worker (agent) name.
      schema:
        type: string
    AccountId:
      name: account_id
      in: path
      required: true
      schema:
        type: string
    PluginId:
      name: plugin_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ApiDefinitionId:
      name: id
      in: path
      required: true
      schema:
        type: string
    ApiDefinitionVersion:
      name: version
      in: path
      required: true
      schema:
        type: string
  responses:
    Error:
      description: An error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GolemError'
  schemas:
    Component:
      type: object
      properties:
        componentId:
          type: string
          format: uuid
        componentName:
          type: string
        componentVersion:
          type: integer
          format: int64
        componentSize:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
    WorkerId:
      type: object
      properties:
        componentId:
          type: string
          format: uuid
        workerName:
          type: string
    WorkerCreationRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        args:
          type: array
          items:
            type: string
        env:
          type: object
          additionalProperties:
            type: string
    WorkerMetadata:
      type: object
      properties:
        workerId:
          $ref: '#/components/schemas/WorkerId'
        status:
          type: string
          enum:
            - Running
            - Idle
            - Suspended
            - Interrupted
            - Retrying
            - Failed
            - Exited
        componentVersion:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
    WorkersMetadataResponse:
      type: object
      properties:
        workers:
          type: array
          items:
            $ref: '#/components/schemas/WorkerMetadata'
        cursor:
          type: string
    InvokeParameters:
      type: object
      properties:
        params:
          type: array
          items: {}
    InvokeResult:
      type: object
      properties:
        result: {}
    UpdateWorkerRequest:
      type: object
      properties:
        mode:
          type: string
          enum:
            - Automatic
            - Manual
        targetVersion:
          type: integer
          format: int64
    HttpApiDefinition:
      type: object
      properties:
        id:
          type: string
        version:
          type: string
        draft:
          type: boolean
        routes:
          type: array
          items:
            type: object
            properties:
              method:
                type: string
              path:
                type: string
              binding:
                type: object
    ApiDeploymentRequest:
      type: object
      properties:
        apiDefinitionId:
          type: string
        version:
          type: string
        site:
          type: object
          properties:
            host:
              type: string
            subdomain:
              type: string
    ApiDeployment:
      type: object
      properties:
        apiDefinitions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              version:
                type: string
        site:
          type: object
          properties:
            host:
              type: string
            subdomain:
              type: string
        createdAt:
          type: string
          format: date-time
    Plugin:
      type: object
      properties:
        name:
          type: string
        version:
          type: string
        description:
          type: string
        scope:
          type: object
        specs:
          type: object
    GolemError:
      type: object
      properties:
        error:
          type: string