openapi.yml

openapi: 3.0.2
info:
  title: ToolForge API
  description: ToolForge is the self-serve tools platform for teams
  contact:
    email: api@toolforge.io
  version: 0.0.42
servers:
  - url: https://api.toolforge.io/v1
tags:
  - name: account
    description: Endpoints for manipulating accounts
  - name: apiKey
    description: Endpoints for manipulating API keys
  - name: container
    description: Endpoints for manipulating containers
  - name: docker
    description: Endpoints for managing Docker integration
  - name: workspace
    description: Endpoints for manipulating workspaces
  - name: execution
    description: Endpoints for manipulating executions
  - name: secret
    description: Endpoints for manipulating secrets
  - name: tool
    description: Endpoints for manipulating tools
paths:
  /accounts:
    get:
      tags:
        - account
      summary: List accounts
      description: List accounts one page at a time
      operationId: listAccounts
      parameters:
        - name: q
          in: query
          description: A prefix query to filter accounts
          schema:
            type: string
            format: PrefixQuery
            example: bbaggins
        - name: limit
          in: query
          description: The maximum number of accounts to return per page
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 100
            default: 10
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: AccountCursor
        - name: order
          in: query
          description: The order in which records are returned
          schema:
            $ref: '#/components/schemas/AccountListOrdering'
      responses:
        200:
          description: The user list was returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPage'

  /accounts/{accountReference}:
    parameters:
      - name: accountReference
        in: path
        description: The ID of the account to retrieve, or "me"
        required: true
        schema:
          type: string
          format: AccountReference
    get:
      tags:
        - account
      summary: Get account
      description: Get one account
      operationId: getAccount
      responses:
        200:
          description: The user was returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          $ref: '#/components/responses/NotFound'

  /accounts/{accountReference}/apiKeys:
    parameters:
      - name: accountReference
        in: path
        description: The ID of the account to retrieve, or "me"
        required: true
        schema:
          type: string
          format: AccountReference
    get:
      tags:
        - account
        - apiKey
      summary: List account's API keys
      description: List one account's API keys one page at a time. Users can only retrieve their own API keys.
      operationId: listAccountApiKeys
      parameters:
        - name: limit
          in: query
          description: The maximum number of API keys to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 10
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: ApiKeyCursor
      responses:
        200:
          description: The API keys were returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyPage'
        403:
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
        - account
        - apiKey
      summary: Create API key
      description: Create a new API key for the given account. Users can only create new API keys for their own accounts. Each account can have up to 10 API keys.
      operationId: createAccountApiKey
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ApiKeyDefinition'
      responses:
        200:
          description: The API key was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewApiKey'
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'

  /accounts/{accountReference}/apiKeys/{apiKeyId}:
    parameters:
      - name: accountReference
        in: path
        description: The ID of the account to retrieve, or "me"
        required: true
        schema:
          type: string
          format: AccountReference
      - name: apiKeyId
        in: path
        description: The ID of the API key to retrieve
        required: true
        schema:
          type: string
          format: ApiKeyId
    get:
      tags:
        - account
        - apiKey
      summary: Get API key
      description: Get one API key. Users can only retrieve API keys for their own accounts.
      operationId: getAccountApiKey
      responses:
        200:
          description: The API key was returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - account
        - apiKey
      summary: Delete API key
      description: Delete an API key from the given account. Users can only delete API keys from their own accounts.
      operationId: deleteAccountApiKey
      responses:
        204:
          description: The API key was deleted successfully
        403:
          $ref: '#/components/responses/Forbidden'

  /accounts/by/id/{accountId}:
    parameters:
      - name: accountId
        in: path
        description: The ID of the account to retrieve
        required: true
        schema:
          type: string
          format: AccountId
    get:
      tags:
        - account
      summary: Get account by ID
      description: Get one account by ID
      operationId: getAccountById
      responses:
        200:
          description: The user was returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          $ref: '#/components/responses/NotFound'

  /accounts/by/username/{username}:
    parameters:
      - name: username
        in: path
        description: The username of the account to retrieve
        required: true
        schema:
          type: string
          format: Username
    get:
      tags:
        - account
      summary: Get account by username
      description: Get one account by username
      operationId: getAccountByUsername
      responses:
        200:
          description: The user was returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        404:
          $ref: '#/components/responses/NotFound'

  /accounts/{accountReference}/picture:
    parameters:
      - name: accountReference
        in: path
        description: The ID of the account to retrieve, or "me"
        required: true
        schema:
          type: string
          format: AccountReference
    get:
      tags:
        - account
      summary: Get account profile picture
      description: Get one account's profile picture
      operationId: getAccountPicture
      responses:
        200:
          description: The user was returned successfully
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        404:
          $ref: '#/components/responses/NotFound'

  /containers:
    get:
      tags:
        - container
      summary: List containers
      description: List one page of containers
      operationId: listContainers
      parameters:
        - name: q
          in: query
          description: A keyword query to filter containers
          schema:
            type: string
            format: KeywordQuery
            example: twitter account
        - name: owner
          in: query
          description: A reference to the container owner
          schema:
            type: string
            format: AccountReference
            example: me
        - name: limit
          in: query
          description: The maximum number of containers to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 100
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: ContainerCursor
      responses:
        200:
          description: The list of containers was returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerPage'
    post:
      tags:
        - container
      summary: Create container
      description: Create a new container
      operationId: createContainer
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ContainerDefinition'
      responses:
        200:
          description: The container was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'


  /containers/by/owner/{owner}/slug/{slug}:
    parameters:
      - name: owner
        in: path
        required: true
        description: The container's owner
        schema:
          type: string
          format: AccountReference
          example: me
      - name: slug
        in: path
        required: true
        description: The slug of the container to get
        schema:
          type: string
          format: ContainerSlug
          example: container-slug
    get:
      tags:
        - container
      summary: Get container by owner's username and slug
      description: Get metadata about one container
      operationId: findContainerByOwnerSlug
      responses:
        200:
          description: The container was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
                
  /containers/{containerId}:
    parameters:
      - $ref: '#/components/parameters/containerId'
    get:
      tags:
        - container
      summary: Get container
      description: Get metadata about one container
      operationId: getContainer
      responses:
        200:
          description: The container was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - container
      summary: Update container
      description: Update metadata about one container
      operationId: updateContainer
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ContainerUpdate'
      responses:
        200:
          description: The container was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'

  /containers/{containerId}/install:
    parameters:
      - $ref: '#/components/parameters/containerId'
    post:
      tags:
        - container
      summary: Install current version of container
      description: Installs the current version of the given container into client's environment
      operationId: installContainer
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ContainerInstallation'
      responses:
        200:
          description: The container was installed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstalledContainer'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'

  /containers/{containerId}/transfer:
    parameters:
      - $ref: '#/components/parameters/containerId'
    post:
      tags:
        - container
      summary: Transfer container ownership
      description: Assign ownership of this container to another user
      operationId: transferContainer
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ContainerTransfer'
      responses:
        200:
          description: The container was installed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Container'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'

  /containers/{containerId}/logs/push:
    parameters:
      - $ref: '#/components/parameters/containerId'
    get:
      tags:
        - container
      summary: Get push logs
      description: Get the most recent docker push log entries for this container
      operationId: getContainerPushLogs
      responses:
        200:
          description: The tool was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerVersionPushLogEntries'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /containers/{containerId}/validate/manifest:
    parameters:
      - $ref: '#/components/parameters/containerId'
    post:
      tags:
        - container
      summary: Validate container manifest
      description: Analyze candidate container manifest for errors
      operationId: validateContainerManifest
      requestBody:
        content:
          'application/yaml':
            schema:
              $ref: '#/components/schemas/Manifest'
      responses:
        204:
          description: The manifest validated successfully
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        422:
          $ref: '#/components/responses/UnprocessableEntity'

  /containers/{containerId}/versions:
    parameters:
      - $ref: '#/components/parameters/containerId'
    get:
      tags:
        - container
      summary: List container versions
      description: List one page of versions of the given container. Container versions are sorted by creation time, descending.
      operationId: listContainerVersions
      parameters:
        - name: limit
          in: query
          description: The maximum number of versions to return per page
          schema:
            type: integer
            format: int32
            default: 10
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: ContainerVersionCursor
      responses:
        200:
          description: The tool was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerVersionPage'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /containers/{containerId}/versions/{containerVersion}:
    parameters:
      - $ref: '#/components/parameters/containerId'
      - $ref: '#/components/parameters/containerVersion'
    get:
      tags:
        - container
      summary: Get container version
      description: Get metadata about one version of one container
      operationId: getContainerVersion
      responses:
        200:
          description: The container version was found successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerVersion'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /containers/{containerId}/versions/{containerVersion}/release:
    parameters:
      - $ref: '#/components/parameters/containerId'
      - $ref: '#/components/parameters/containerVersion'
    post:
      tags:
        - container
      summary: Release container version
      description: Sets the given container's current version to the given version
      operationId: releaseContainerVersion
      responses:
        200:
          description: The container version was released successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerVersion'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /containers/{containerId}/versions/{containerVersion}/deprecate:
    parameters:
      - $ref: '#/components/parameters/containerId'
      - $ref: '#/components/parameters/containerVersion'
    post:
      tags:
        - container
      summary: Deprecate container version
      description: Deprecates the given version of the given tool.
      operationId: deprecateContainerVersion
      responses:
        200:
          description: The container version was deprecated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerVersion'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
          
  /docker/otp:
    post:
      tags:
        - docker
      summary: Get one-time password for docker
      description: Get a one-time password to use for docker login. Valid for 5 minutes.
      operationId: getDockerOneTimePassword
      responses:
        200:
          description: The one-time password was created successfully.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DockerPassword'
        403:
          $ref: '#/components/responses/Forbidden'
          
  /workspaces:
    get:
      tags:
        - workspace
      summary: List workspaces
      description: Get one page of workspaces
      operationId: listWorkspaces
      parameters:
        - name: q
          in: query
          description: A keyword query for filtering workspaces
          schema:
            type: string
            format: KeywordQuery
            example: service name
        - name: owner
          in: query
          description: The owner of the workspaces to return
          schema:
            type: string
            format: AccountReference
            example: me
        - name: limit
          in: query
          description: The maximum number of executions to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 100
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: WorkspaceCursor
      responses:
        200:
          description: The workspaces were retrieved successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/WorkspacePage'

  /workspaces/{workspaceId}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
    get:
      tags:
        - workspace
      summary: Get workspace
      description: Get one workspace
      operationId: getWorkspace
      responses:
        200:
          description: The workspace astrieved successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Workspace'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/secrets:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
    post:
      tags:
        - workspace
        - secret
      summary: Create workspace secret
      description: Create a new secret in the given workspace
      operationId: createWorkspaceSecret
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SecretDefinition'
      responses:
        200:
          description: The secret was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'
    get:
      tags:
        - workspace
        - secret
      summary: List workspace secrets
      description: List one page of secrets in the given workspace
      operationId: listWorkspaceSecrets
      parameters:
        - name: q
          in: query
          description: A keyword query for filtering secrets
          schema:
            type: string
            format: KeywordQuery
            example: service name
        - name: owner
          in: query
          description: The owner of the secrets to return
          schema:
            type: string
            format: AccountReference
            example: me
        - name: limit
          in: query
          description: The maximum number of executions to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 100
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: SecretCursor
      responses:
        200:
          description: The list of executions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretPage'

  /workspaces/{workspaceId}/secrets/{secretId}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/secretId'
    get:
      tags:
        - workspace
        - secret
      summary: Get workspace secret
      description: Get metadata about the given secret in the given workspace. This does not reveal the secret value.
      operationId: getWorkspaceSecret
      responses:
        200:
          description: The secret was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - workspace
        - secret
      summary: Update workspace secret
      description: Updates the given secret in the given workspace
      operationId: updateWorkspaceSecret
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SecretUpdate'
      responses:
        200:
          description: The secret was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'
    delete:
      tags:
        - workspace
        - secret
      summary: Delete workspace secret
      description: Deletes the given secret in the given workspace
      operationId: deleteWorkspaceSecret
      responses:
        204:
          description: The secret was deleted successfully.
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'


  /workspaces/{workspaceId}/secrets/by/name/{name}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - name: name
        in: path
        required: true
        description: The name of a secret
        schema:
          type: string
          format: SecretName
          example: SECRET_NAME
    get:
      tags:
        - workspace
        - secret
      summary: Get workspace secret by  name
      description: Get metadata about the given secret in the given workspace. This does not reveal the secret value.
      operationId: findWorkspaceSecretByName
      responses:
        200:
          description: The secret was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        404:
          $ref: '#/components/responses/NotFound'
          
  /workspaces/{workspaceId}/secrets/{secretId}/transfer:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/secretId'
    post:
      tags:
        - workspace
        - secret
      summary: Transfer workspace secret ownership
      description: Transfer this workspace secret to another owner
      operationId: transferWorkspaceSecret
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/SecretTransfer'
      responses:
        200:
          description: The secret was transferred successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/executions:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
    get:
      tags:
        - workspace
        - execution
      summary: List executions
      description: List one page of executions
      operationId: listExecutions
      parameters:
        - name: q
          in: query
          description: A keyword query for filtering executions
          schema:
            type: string
            format: KeywordQuery
            example: twitter account
        - name: owner
          in: query
          description: The owner of executions to return
          schema:
            type: string
            format: AccountReference
            example: me
        - name: state
          in: query
          description: The state of executions to return
          schema:
            $ref: '#/components/schemas/ExecutionState'
        - name: limit
          in: query
          description: The maximum number of executions to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 100
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: ExecutionCursor
      responses:
        200:
          description: The list of executions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionPage'

  /workspaces/{workspaceId}/executions/{executionId}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
    get:
      tags:
        - workspace
        - execution
      summary: Get execution
      description: Get metadata about one execution
      operationId: getExecution
      responses:
        200:
          description: The execution was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        410:
          $ref: '#/components/responses/Gone'
    patch:
      tags:
        - workspace
        - execution
      summary: Update execution
      description: Update metadata about one execution
      operationId: updateExecution
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ExecutionUpdate'
      responses:
        200:
          description: The execution was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        410:
          $ref: '#/components/responses/Gone'
    delete:
      tags:
        - workspace
        - execution
      summary: Delete execution
      description: Delete an execution by ID
      operationId: deleteExecution
      responses:
        204:
          description: The execution was deleted successfully.
        403:
          $ref: '#/components/responses/Forbidden'

  /workspaces/{workspaceId}/executions/{executionId}/logs:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
    get:
      tags:
        - workspace
        - execution
      summary: Get execution log page
      description: Get a page of the execution's logs
      operationId: listExecutionLogs
      parameters:
        - $ref: '#/components/parameters/limit'
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: LogCursor
      responses:
        200:
          description: The execution was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogPage'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        410:
          $ref: '#/components/responses/Gone'

  /workspaces/{workspaceId}/executions/{executionId}/inputs/{name}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
      - name: name
        in: path
        description: The name of the input to retrieve
        required: true
        schema:
          type: string
          format: SlotName
    get:
      tags:
        - workspace
        - execution
      summary: Get execution input
      description: Get metadata about the given execution's given input slot
      operationId: getExecutionInputData
      responses:
        200:
          description: The input slot was retrieved successfully.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        410:
          $ref: '#/components/responses/Gone'

  /workspaces/{workspaceId}/executions/{executionId}/outputs/{name}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
      - name: name
        in: path
        description: The name of the output to retrieve
        required: true
        schema:
          type: string
          format: SlotName
    get:
      tags:
        - workspace
        - execution
      summary: Get execution output
      description: Get metadata about the given execution's given output slot
      operationId: getExecutionOutputData
      responses:
        200:
          description: The output slot was retrieved successfully.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        202:
          description: The given execution is still running, so the data is not available at this time, but may be available later.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          description: The given execution has failed, so the data is not available at this time, and will not be available later.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        410:
          $ref: '#/components/responses/Gone'

  /workspaces/{workspaceId}/executions/{executionId}/outputs/{name}.{extension}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
      - name: name
        in: path
        description: The name of the output to retrieve
        required: true
        schema:
          type: string
          format: SlotName
      - name: extension
        in: path
        description: The extension of the output to retrieve
        required: true
        schema:
          type: string
          format: FileExtension
    get:
      tags:
        - workspace
        - execution
      summary: Get execution output
      description: Get metadata about the given execution's given output slot
      operationId: getExecutionOutputExtensionData
      responses:
        200:
          description: The output slot was retrieved successfully.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        202:
          description: The given execution is still running, so the data is not available at this time, but may be available later.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          description: The given execution has failed, so the data is not available at this time, and will not be available later.
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        410:
          $ref: '#/components/responses/Gone'

  /workspaces/{workspaceId}/executions/{executionId}/transfer:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
    post:
      tags:
        - workspace
        - execution
      summary: Transfer execution ownership
      description: Assign ownership of this execution to another user
      operationId: transferExecution
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ExecutionTransfer'
      responses:
        200:
          description: The execution was transferred successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/executions/{executionId}/cancel:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/executionId'
    post:
      tags:
        - workspace
        - execution
      summary: Cancel execution
      description: Cancel an execution
      operationId: cancelExecution
      responses:
        200:
          description: The execution was canceled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'
        410:
          $ref: '#/components/responses/Gone'

  /workspaces/{workspaceId}/tools:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
    get:
      tags:
        - workspace
        - tool
      summary: List workspace tools
      description: List the tools installed in the given workspace
      operationId: listWorkspaceTools
      parameters:
        - name: q
          in: query
          description: A keyword query to filter tool
          schema:
            type: string
            format: KeywordQuery
            example: twitter account
        - name: owner
          in: query
          description: The owner of the tool
          schema:
            type: string
            format: AccountReference
            example: me
        - name: order
          in: query
          description: The order in which tools are returned
          schema:
            $ref: '#/components/schemas/ToolListOrdering'
        - name: limit
          in: query
          description: The maximum number of tools to return per page
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 0
            maximum: 100
        - name: cursor
          in: query
          description: The pagination cursor
          schema:
            type: string
            format: ToolCursor        
      responses:
        200:
          description: The workspace astrieved successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ToolPage'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/tools/{toolId}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/toolId'
    get:
      tags:
        - workspace
        - tool
      summary: Get workspace tool
      description: Get the tool
      operationId: getWorkspaceTool
      responses:
        200:
          description: The workspace astrieved successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Tool'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - workspace
        - tool
      summary: Update tool in workspace
      description: Update the given tool in the workspace
      operationId: updateWorkspaceTool
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ToolUpdate'
      responses:
        200:
          description: The tool was installed successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Tool'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/tools/{toolId}/transfer:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/toolId'
    post:
      tags:
        - workspace
        - tool
      summary: Transfer tool ownership
      description: Assign ownership of this tool to another user
      operationId: transferWorkspaceTool
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ToolTransfer'
      responses:
        200:
          description: The tool was transferred successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Tool'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/tools/{toolId}/execute:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/toolId'
    post:
      tags:
        - tool
        - workspace
        - execution
      summary: Execute tool
      description: Execute the current version of the given tool
      operationId: executeWorkspaceTool
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ToolInvocation'
      responses:
        201:
          description: The execution was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Execution'
        403:
          $ref: '#/components/responses/Forbidden'
        409:
          $ref: '#/components/responses/Conflict'
        404:
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspaceId}/blobs:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
    post:
      tags:
        - workspace
        - blob
      summary: Create a blob
      # NOTE: Send filename on x-blob-filename header.
      description: Create a new blob from the given data
      operationId: createBlob
      requestBody:
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        201:
          description: The blob was created successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Blob'
  
  /workspaces/{workspaceId}/blobs/{blobId}:
    parameters:
      - $ref: '#/components/parameters/workspaceId'
      - $ref: '#/components/parameters/blobId'
    get:
      tags:
        - workspace
        - blob
      summary: Get a blob
      description: Retrieve information about the given blob
      operationId: getBlob
      responses:
        200:
          description: The blob was created successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Blob'
        404:
          $ref: '#/components/responses/NotFound'
          
components:
  responses:
    Processing:
      description: The requested data is still processing and is not ready yet.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    BadRequest:
      description: The given request could not be satisfied because it's invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Forbidden:
      description: The current user does not have permission to perform the operation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    NotFound:
      description: The object could not be found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Conflict:
      description: The request conflicts with application state.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Gone:
      description: The object has expired.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    UnprocessableEntity:
      description: There was a problem with the request body
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
            
  parameters:
    toolId:
      name: toolId
      in: path
      description: The ID of the tool to manipulate
      required: true
      schema:
        type: string
        format: ToolId
    toolVersion:
      name: toolVersion
      in: path
      description: The version of the tool to manipulate
      required: true
      schema:
        type: string
        format: ToolVersionId
    containerId:
      name: containerId
      in: path
      description: The ID of the container to manipulate
      required: true
      schema:
        type: string
        format: ContainerId
    containerVersion:
      name: containerVersion
      in: path
      description: The ID of the container version to manipulate
      required: true
      schema:
        type: string
        format: ContainerVersionId
    executionId:
      name: executionId
      in: path
      description: The ID of the execution to manipulate
      required: true
      schema:
        type: string
        format: ExecutionId
    workspaceId:
      name: workspaceId
      in: path
      description: The ID of the workspace to manipulate
      required: true
      schema:
        type: string
        format: WorkspaceId
    blobId:
      name: blobId
      in: path
      description: The ID of the blob to manipulate
      required: true
      schema:
        type: string
        format: BlobId
    secretId:
      name: secretId
      in: path
      description: The ID of the secret to manipulate
      required: true
      schema:
        type: string
        format: SecretId
    limit:
      name: limit
      in: query
      description: The maximum number of items to return per page
      required: false
      schema:
        type: integer
        format: int32
        default: 10
    
  schemas:
    # application/problem+json
    # https://datatracker.ietf.org/doc/html/rfc7807
    # https://lakitna.medium.com/understanding-problem-json-adf68e5cf1f8
    ErrorMessage:
      type: object
      properties:
        type:
          type: string
          format: url
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string

    AccountPreview:
      type: object
      required:
        - id
        - username
        - picture
      properties:
        id:
          type: string
          format: AccountId
        username:
          type: string
          format: Username
        picture:
          type: string
          format: url

    AccountDescription:
      allOf:
        - $ref: '#/components/schemas/AccountPreview'
        - type: object
          required:
            - createdAt
          properties:
            name:
              type: string
              format: HumanName
            email:
              type: string
              format: EmailAddress
            createdAt:
              type: string
              format: date-time
            activeAt:
              type: string
              format: date-time
            lastExecutionAt:
              type: string
              format: date-time
          
    Account:
      allOf:
        - $ref: '#/components/schemas/AccountDescription'
        - type: object
          properties:
            roles:
              type: array
              items:
                type: string
                format: RoleId
          
    AccountListOrdering:
      type: string
      enum:
        - lastExecutionAt
        - activeAt
        - createdAt
        - username

    AccountPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AccountDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: AccountCursor
          
    SecretDefinition:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          pattern: "[a-zA-z][a-zA-Z0-9_]*"
          minLength: 1
          maxLength: 64
        description:
          type: string
          format: markdown
        value:
          type: string
          minLength: 1
          maxLength: 10240
          
    SecretPreview:
      type: object
      properties:
        id:
          type: string
          format: SecretId
        name:
          type: string
        owner:
          $ref: '#/components/schemas/AccountPreview'
          
    SecretDescription:
      allOf:
        - $ref: '#/components/schemas/SecretPreview'
        - type: object
          properties:
            createdAt:
              type: string
              format: date-time
            retrievedAt:
              type: string
              format: date-time
          
    Secret:
      allOf:
        - $ref: '#/components/schemas/SecretDescription'
        - type: object
          properties:
            updatedAt:
              type: string
              format: date-time
            description:
              type: string
              format: markdown
              
    SecretTransfer:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          format: AccountId

    SecretUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          format: markdown
        value:
          type: string

    SecretPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SecretDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: SecretCursor

    WorkspaceVisibility:
      type: string
      enum:
        - public
        - private
          
    WorkspacePreview:
      type: object
      properties:
        id:
          type: string
          format: WorkspaceId
        owner:
          $ref: '#/components/schemas/AccountPreview'
        name:
          type: string
          maxLength: 80
        slug:
          type: string
          maxLength: 80
          
    WorkspaceDescription:
      allOf:
        - $ref: '#/components/schemas/WorkspacePreview'
        - type: object
          properties:
            visibility:
              $ref: '#/components/schemas/WorkspaceVisibility'

    Workspace:
      allOf:
        - $ref: '#/components/schemas/WorkspaceDescription'
        - type: object
          properties:
            description:
              type: string
              format: markdown
          
    WorkspacePage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: WorkspaceCursor

    ApiKeyDescription:
      type: object
      required:
        - id
        - description
        - createdAt
      properties:
        id:
          type: string
          format: ApiKeyId
          minLength: 64
          maxLength: 64
        description:
          type: string
          minLength: 1
          maxLength: 80
        createdAt:
          type: string
          format: date-time
        activeAt:
          type: string
          format: date-time

    ApiKey:
      allOf:
        - $ref: '#/components/schemas/ApiKeyDescription'
        - type: object
          required:
            - hint
          properties:
            hint:
              type: string
              format: ApiKeyHint
              minLength: 4
              maxLength: 4

    NewApiKey:
      allOf:
        - $ref: '#/components/schemas/ApiKey'
        - type: object
          required:
            - token
          properties:
            token:
              type: string
              format: ApiKeyToken
              minLength: 40
              maxLength: 40

    ApiKeyDefinition:
      type: object
      required:
        - description
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 80
          
    ApiKeyPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ApiKeyDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: ApiKeyCursor

    StringDomainType:
      type: string
      enum:
        - pattern
        - enumeration
              
    StringDomain:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/StringDomainType'
      required:
        - type
      discriminator:
        propertyName: type
        mapping:
          pattern: PatternStringDomain
          enumeration: EnumerationStringDomain
          
    PatternStringDomain:
      allOf:
        - $ref: '#/components/schemas/StringDomain'
        - type: object
          required:
            - pattern
          properties:
            pattern:
              type: string
              format: regex
    
    EnumerationStringDomain:
      allOf:
        - $ref: '#/components/schemas/StringDomain'
        - type: object
          required:
            - values
          properties:
            values:
              type: array
              uniqueItems: true
              minItems: 1
              items:
                type: string

    ParameterType:
      type: string
      enum:
        - int
        - float
        - string
        - date
        - boolean
        
    ParameterDefinition:
      type: object
      required:
        - type
        - name
        - description
        - required
      properties:
        type:
          $ref: '#/components/schemas/ParameterType'
        name:
          type: string
          pattern: '^[a-zA-Z][a-zA-Z0-9]*'
          maxLength: 64
        description:
          type: string
          format: markdown
        required:
          type: boolean
          default: true
      discriminator:
        propertyName: type
        mapping:
          int: IntParameterDefinition
          float: FloatParameterDefinition
          string: StringParameterDefinition
          date: DateParameterDefinition
          boolean: BooleanParameterDefinition
          
    IntParameterDefinition:
      allOf:
        - $ref: '#/components/schemas/ParameterDefinition'
        - type: object
          required:
            - minimum
            - maximum
            - default
          properties:
            minimum:
              type: integer
              format: int64
            maximum:
              type: integer
              format: int64
            default:
              type: integer
              format: int64

    FloatParameterDefinition:
      allOf:
        - $ref: '#/components/schemas/ParameterDefinition'
        - type: object
          required:
            - minimum
            - maximum
            - default
          properties:
            minimum:
              type:  number
              format: double
            maximum:
              type: number
              format: double
            default:
              type: number
              format: double

    StringParameterDefinition:
      allOf:
        - $ref: '#/components/schemas/ParameterDefinition'
        - type: object
          required:
            - domain
            - default
          properties:
            domain:
              $ref: '#/components/schemas/StringDomain'
            default:
              type: string
                
    DateParameterDefinition:
      allOf:
        - $ref: '#/components/schemas/ParameterDefinition'
        - type: object
          required:
            - minimum
            - maximum
            - default
          properties:
            minimum:
              type: string
              format: DateExpr
            maximum:
              type: string
              format: DateExpr
            default:
              type: string
              format: DateExpr
        
    BooleanParameterDefinition:
      allOf:
        - $ref: '#/components/schemas/ParameterDefinition'
        - type: object
          required:
            - default
          properties:
            default:
              type: boolean

    Slot:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          pattern: "^[a-zA-Z][a-zA-Z0-9]*$"
          maxLength: 64
        description:
          type: string
          format: markdown
        extensions:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            type: string
            format: FileExtension

    ManifestEnvironment:
      type: object
      required:
        - size
      properties:
        size:
          $ref: '#/components/schemas/ContainerSize'
        variables:
          type: array
          minLength: 0
          maxLength: 10
          items:
            $ref: '#/components/schemas/ContainerVersionVariable'
        secrets:
          type: array
          minLength: 0
          maxLength: 10
          items:
            $ref: '#/components/schemas/ContainerVersionSecret'

    ContainerType:
      type: string
      enum:
        - tool

    Manifest:
      type: object
      required:
        - toolforge
        - type
        - container
        - environment
      properties:
        toolforge:
          # 1.0 for now
          type: string
          format: ManifestVersion
        container:
          type: string
          format: ContainerId
        type:
          $ref: '#/components/schemas/ContainerType'
        environment:
          $ref: '#/components/schemas/ManifestEnvironment'
        # TODO cost? or is that in tool?
      discriminator:
        propertyName: type
        mapping:
          tool: '#/components/schemas/ToolManifest'

    ToolManifest:
      allOf:
        - $ref: '#/components/schemas/Manifest'
        - type: object
          properties:
            parameters:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/ParameterDefinition'
            inputs:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/Slot'
            outputs:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/Slot'
            
    Parameter:
      type: object
      required:
        - type
        - name
        - description
        - required
      properties:
        type:
          $ref: '#/components/schemas/ParameterType'
        name:
          type: string
          pattern: '^[a-zA-Z][a-zA-Z0-9]*'
          maxLength: 64
        description:
          type: string
        required:
          type: boolean
          default: true
      discriminator:
        propertyName: type
        mapping:
          int: IntParameter
          float: FloatParameter
          string: StringParameter
          date: DateParameter
          boolean: BooleanParameter
          
    IntParameter:
      allOf:
        - $ref: '#/components/schemas/Parameter'
        - type: object
          properties:
            minimum:
              type: integer
              format: int64
            maximum:
              type: integer
              format: int64
            default:
              type: integer
              format: int64

    FloatParameter:
      allOf:
        - $ref: '#/components/schemas/Parameter'
        - type: object
          properties:
            minimum:
              type:  number
              format: double
            maximum:
              type: number
              format: double
            default:
              type: number
              format: double

    StringParameter:
      allOf:
        - $ref: '#/components/schemas/Parameter'
        - type: object
          required:
            - domain
          properties:
            domain:
              $ref: '#/components/schemas/StringDomain'
            default:
              type: string
                
    DateParameter:
      allOf:
        - $ref: '#/components/schemas/Parameter'
        - type: object
          properties:
            minimum:
              type: string
              format: date
            maximum:
              type: string
              format: date
            default:
              type: string
              format: date
        
    BooleanParameter:
      allOf:
        - $ref: '#/components/schemas/Parameter'
        - type: object
          properties:
            default:
              type: boolean
              
    ContainerVersionPushOutcome:
      type: string
      enum:
        # There was a problem with the Docker push
        - push-failed
        # The Docker image manifest could not be found (application/vnd.docker.distribution.manifest.v2+json)
        - image-manifest-not-found
        # The ToolForge manifest could not be found
        - toolforge-manifest-not-found
        # The Docker container manifest could not be found (application/vnd.docker.container.image.v1+json)
        - container-manifest-not-found
        # The Container ID in the manifest does not match the Container ID being pushed
        - container-id-mismatch
        # The ToolForge manifest is not valid
        - invalid-manifest
        # There was a generic internal error
        - internal-error
        # The push was successful
        - success
              
    ContainerVersionPushLogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        digest:
          type: string
        outcome:
          $ref: '#/components/schemas/ContainerVersionPushOutcome'

    ContainerVersionPushLogEntries:
      type: object
      properties:
        containerId:
          type: string
          format: ContainerId
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContainerVersionPushLogEntry'

    ContainerTransfer:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          format: AccountId
              
    ContainerDefinition:
      type: object
      required:
        - type
        - name
        - description
      properties:
        type:
          $ref: '#/components/schemas/ContainerType'
        name:
          type: string
        description:
          type: string
          format: markdown

    ContainerVersionVariable:
      type: object
      required:
        - name
        - required
        - description
      properties:
        name:
          type: string
          pattern: '^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*'
          minLength: 1
          maxLength: 64
        description:
          type: string
          format: markdown
        required:
          type: boolean
          default: true
        default:
          type: string

    ContainerVersionSecret:
      type: object
      required:
        - name
        - required
        - description
      properties:
        name:
          type: string
          pattern: '^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*'
          minLength: 1
          maxLength: 64
        description:
          type: string
          format: markdown
        required:
          type: boolean
          default: true
        example:
          type: string

    ContainerSize:
      type: string
      enum:
        # 0.25CPU, 2GB Memory
        - tiny
        # 0.5CPU, 4GB Memory
        - small
        # 1.0CPU, 8GB Memory
        - medium
        # 2.0 CPU, 16GB Memory
        - large
        # 4.0 CPU, 30GB Memory
        - xlarge

    ContainerPreview:
      type: object
      required:
        - type
        - id
        - owner
        - name
        - slug
      properties:
        type:
          $ref: '#/components/schemas/ContainerType'
        id:
          type: string
          format: ContainerId
        owner:
          $ref: '#/components/schemas/AccountPreview'
        name:
          type: string
        slug:
          type: string
      
    ContainerDescription:
      allOf:
        - $ref: '#/components/schemas/ContainerPreview'
        - type: object
          required:
            - createdAt
            - description
          properties:
            description:
              type: string
              format: markdown
            createdAt:
              type: string
              format: date-time
              
    Container:
      allOf:
        - $ref: '#/components/schemas/ContainerDescription'
        - type: object
          properties:
            repository:
              type: string
            currentVersion:
              $ref: '#/components/schemas/ContainerVersion'
            
    ContainerPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContainerDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: ContainerCursor

    ContainerUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          format: markdown

    ContainerVersionState:
      type: string
      enum:
        - ready
        - current
        - deprecated
        - retired
          
    ContainerVersionDescription:
      type: object
      properties:
        version:
          type: string
          format: ContainerVersionId
        createdAt:
          type: string
          format: date-time
        state:
          $ref: '#/components/schemas/ContainerVersionState'
        creator:
          $ref: '#/components/schemas/AccountPreview'

    ContainerVersion:
      allOf:
        - $ref: '#/components/schemas/ContainerVersionDescription'
        - type: object
          properties:
            parameters:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/Parameter'
            inputs:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/Slot'
            outputs:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/Slot'
            variables:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/ContainerVersionVariable'
            secrets:
              type: array
              minLength: 0
              maxLength: 10
              items:
                $ref: '#/components/schemas/ContainerVersionSecret'
                
    ContainerVersionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContainerVersionDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: ContainerVersionCursor
          
    ContainerInstallation:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/ContainerType'
      discriminator:
        propertyName: type
        mapping:
          tool: '#/components/schemas/ToolContainerInstallation'
          
    ToolContainerInstallationVariable:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          maxLength: 64
        value:
          type: string
          
    ToolContainerInstallationSecret:
      type: object
      required:
        - name
        - secret
      properties:
        name:
          type: string
          maxLength: 64
        secret:
          type: string
          format: SecretId
          
    ToolContainerInstallation:
      allOf:
        - $ref: '#/components/schemas/ContainerInstallation'
        - type: object
          required:
            - workspace
          properties:
            workspace:
              type: string
              format: WorkspaceId
            variables:
              type: array
              minLength: 1
              maxLength: 10
              items:
                $ref: '#/components/schemas/ToolContainerInstallationVariable'
            secrets:
              type: array
              minLength: 1
              maxLength: 10
              items:
                $ref: '#/components/schemas/ToolContainerInstallationSecret'
            
    InstalledContainer:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ContainerType'
        container:
          $ref: '#/components/schemas/ContainerPreview'
      discriminator:
        propertyName: type
        mapping:
          tool: '#/components/schemas/ToolInstalledContainer'
          
    ToolInstalledContainer:
      allOf:
        - $ref: '#/components/schemas/InstalledContainer'
        - type: object
          required:
            - workspace
            - tool
          properties:
            workspace:
              $ref: '#/components/schemas/WorkspacePreview'
            tool:
              $ref: '#/components/schemas/Tool'

    ToolListOrdering:
      type: string
      enum:
        - lastExecutedByTeamAt
        - lastExecutedByMeAt
        - name

    ToolTransfer:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          format: AccountId
          
    ToolUpdateVariable:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 64
        value:
          type: string
          
    ToolUpdateSecret:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 64
        secret:
          type: string
          format: SecretId
          
    ToolUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          format: markdown
        variables:
          type: array
          items:
            $ref: '#/components/schemas/ToolUpdateVariable'
        secrets:
          type: array
          items:
            $ref: '#/components/schemas/ToolUpdateSecret'

    ToolPreview:
      type: object
      required:
        - id
        - owner
        - name
        - slug
      properties:
        id:
          type: string
          format: ToolId
        currentVersion:
          type: string
          format: ToolVersionId
        owner:
          $ref: '#/components/schemas/AccountPreview'
        name:
          type: string
        slug:
          type: string

    ToolDescription:
      allOf:
        - $ref: '#/components/schemas/ToolPreview'
        - type: object
          required:
            - createdAt
            - description
          properties:
            description:
              type: string
              format: markdown
            createdAt:
              type: string
              format: date-time
            lastExecutedByMeAt:
              type: string
              format: date-time
            lastExecutedByTeamAt:
              type: string
              format: date-time

    Tool:
      allOf:
        - $ref: '#/components/schemas/ToolDescription'
        - type: object
          properties:
            container:
              $ref: '#/components/schemas/ContainerPreview'
            parameters:
              type: array
              items:
                $ref: '#/components/schemas/Parameter'
            inputs:
              type: array
              items:
                $ref: '#/components/schemas/Slot'
            outputs:
              type: array
              items:
                $ref: '#/components/schemas/Slot'
            
    ToolPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ToolDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: ToolCursor

    Argument:
      type: object
      properties:
        name:
          type: string
          pattern: "^[a-zA-Z][a-zA-Z0-9]*$"
          maxLength: 64
        value:
          $ref: '#/components/schemas/ArgumentValue'

    ArgumentValue:
      oneOf:
        - type: string
        - type: integer
          format: int64
        - type: number
          format: double
        - type: boolean
        
    InvocationDataType:
      type: string
      enum:
        - blob
        
    InvocationData:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/InvocationDataType'
      discriminator:
        propertyName: type
        mapping:
          blob: BlobInvocationData
        
    BlobInvocationData:
      allOf:
        - $ref: '#/components/schemas/InvocationData'
        - type: object
          properties:
            blob:
              type: string
              format: BlobId
    
    ToolInvocationInput:
      type: object
      properties:
        name:
          type: string
          pattern: "^[a-zA-Z][a-zA-Z0-9]*$"
          maxLength: 64
        data:
          $ref: '#/components/schemas/InvocationData'
            
    ToolInvocation:
      type: object
      properties:
        arguments:
          type: array
          items:
            $ref: '#/components/schemas/Argument'
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolInvocationInput'
            
    LogEntry:
      type: object
      required:
      - timestamp
      - message
      properties:
        timestamp:
          type: string
          format: date-time
        message:
          type: string

    LogPage:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/LogEntry'
        cursor:
          type: string
          format: LogCursor
      
    ExecutionState:
      type: string
      enum:
        # The execution has been invoked, but has not started running yet.
        - starting
        # The execution is currently running. It has not completed yet.
        - running
        # The execution has completed running successfully.
        - succeeded
        # The execution has completed running unsuccessfully.
        - failed
        # The execution was cancelled by the user.
        - cancelled

    ExecutionTransfer:
      type: object
      required:
        - owner
      properties:
        owner:
          type: string
          format: AccountId
          
    ExecutionUpdate:
      type: object
      properties:
        name:
          type: string

    ExecutionDescription:
      type: object
      properties:
        id:
          type: string
          format: ExecutionId
        tool:
          $ref: '#/components/schemas/ToolPreview'
        owner:
          $ref: '#/components/schemas/AccountPreview'
        name:
          type: string
        state:
          $ref: '#/components/schemas/ExecutionState'
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time

    ExecutionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExecutionDescription'
        total:
          type: integer
          format: int32
        cursor:
          type: string
          format: ExecutionCursor
          
    # TODO How do we represent inputs? status?
    # TODO How do we represent outputs? status?
    Execution:
      allOf:
        - $ref: '#/components/schemas/ExecutionDescription'
        - type: object
          properties:
            toolVersion:
              type: string
              format: ToolVersionId
            arguments:
              type: array
              items:
                $ref: '#/components/schemas/Argument'
            inputs:
              type: array
              items:
                $ref: '#/components/schemas/ExecutionInput'
            outputs:
              type: array
              items:
                $ref: '#/components/schemas/ExecutionOutput'
                
    ExecutionDataState:
      type: string
      enum:
        # The data is not available now, but may be available in the future.
        - waiting
        # The data is available now.
        - populated
        # The data is not available now and will not be available in the future because the execution completed successfully but did not populate it.
        - unpopulated
        # The data is not available now and will not be available in the future because the execution did not complete successfully. 
        - cancelled

    ExecutionInput:
      type: object
      properties:
        name:
          type: string
          pattern: "^[a-zA-Z][a-zA-Z0-9]*$"
          maxLength: 64
        state:
          $ref: '#/components/schemas/ExecutionDataState'

    ExecutionOutput:
      type: object
      properties:
        name:
          type: string
          pattern: "^[a-zA-Z][a-zA-Z0-9]*$"
          maxLength: 64
        representations:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ExecutionOutputRepresentation'

    ExecutionOutputRepresentation:
      type: object
      properties:
        extension:
          type: string
          format: FileExtension
        state:
          $ref: '#/components/schemas/ExecutionDataState'

    Blob:
      type: object
      properties:
        id:
          type: string
          format: BlobId
        extension:
          type: string
        size:
          type: integer
          format: int64
          
    DockerPassword:
      type: object
      description: A one-time password for docker login
      properties:
        username:
          type: string
          format: Username
        password:
          type: string
          format: password
        registry:
          type: string
          format: hostname
        expiresAt:
          type: string
          format: date-time