openapi: 3.0.0
info:
  description: |
    Administrate your Garage cluster programatically, including status, layout, keys, buckets, and maintainance tasks.

    *Disclaimer: The API is not stable yet, hence its v0 tag. The API can change at any time, and changes can include breaking backward compatibility. Read the changelog and upgrade your scripts before upgrading. Additionnaly, this specification is very early stage and can contain bugs, especially on error return codes/types that are not tested yet. Do not expect a well finished and polished product!*
  title: Garage Administration API v0+garage-v0.9.0
  version: v0.9.0
servers:
- description: A local server
  url: http://localhost:3903/v1/
security:
- bearerAuth: []
paths:
  /health:
    get:
      description: |
        Returns the global status of the cluster, the number of connected nodes (over the number of known ones), the number of healthy storage nodes (over the declared ones), and the number of healthy partitions (over the total).
      operationId: GetHealth
      responses:
        "500":
          description: |
            The server can not answer your request because it is in a bad state
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHealth_200_response'
          description: |
            Information about the queried node, its environment and the current layout
      summary: Cluster health report
      tags:
      - Nodes
  /status:
    get:
      description: |
        Returns the cluster's current status, including:
         - ID of the node being queried and its version of the Garage daemon
         - Live nodes
         - Currently configured cluster layout
         - Staged changes to the cluster layout

        *Capacity is given in bytes*
      operationId: GetNodes
      responses:
        "500":
          description: |
            The server can not answer your request because it is in a bad state
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNodes_200_response'
          description: |
            Information about the queried node, its environment and the current layout
      summary: Describe cluster
      tags:
      - Nodes
  /connect:
    post:
      description: |
        Instructs this Garage node to connect to other Garage nodes at specified `<node_id>@<net_address>`. `node_id` is generated automatically on node start.
      operationId: AddNode
      requestBody:
        content:
          application/json:
            schema:
              example:
              - ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f@10.0.0.11:3901
              - 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff@10.0.0.12:3901
              items:
                type: string
              type: array
        required: true
      responses:
        "500":
          description: |
            The server can not answer your request because it is in a bad state
        "400":
          description: |
            Your request is malformed, check your JSON
        "200":
          content:
            application/json:
              schema:
                example:
                - success: true
                  error: null
                - success: false
                  error: Handshake error
                items:
                  $ref: '#/components/schemas/AddNode_200_response_inner'
                type: array
          description: |
            The request has been handled correctly but it does not mean that all connection requests succeeded; some might have fail, you need to check the body!
      summary: Connect a new node
      tags:
      - Nodes
  /layout:
    get:
      description: "Returns the cluster's current layout, including:\n  - Currently\
        \ configured cluster layout\n  - Staged changes to the cluster layout\n  \n\
        *Capacity is given in bytes*\n*The info returned by this endpoint is a subset\
        \ of the info returned by `GET /status`.*\n"
      operationId: GetLayout
      responses:
        "500":
          description: |
            The server can not answer your request because it is in a bad state
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterLayout'
          description: |
            Returns the cluster's current cluster layout:
              - Currently configured cluster layout
              - Staged changes to the cluster layout
      summary: Details on the current and staged layout
      tags:
      - Layout
    post:
      description: |
        Send modifications to the cluster layout. These modifications will be included in the staged role changes, visible in subsequent calls of `GET /layout`. Once the set of staged changes is satisfactory, the user may call `POST /layout/apply` to apply the changed changes, or `POST /layout/revert` to clear all of the staged changes in the layout.

        Setting the capacity to `null` will configure the node as a gateway.
        Otherwise, capacity must be now set in bytes (before Garage 0.9 it was arbitrary weights).
        For example to declare 100GB, you must set `capacity: 100000000000`.

        Garage uses internally the International System of Units (SI), it assumes that 1kB = 1000 bytes, and displays storage as kB, MB, GB (and not KiB, MiB, GiB that assume 1KiB = 1024 bytes).
      operationId: AddLayout
      requestBody:
        content:
          application/json:
            schema:
              example:
              - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
                zone: geneva
                capacity: 100000000000
                tags:
                - gateway
              - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
                remove: true
              items:
                $ref: '#/components/schemas/NodeRoleChange'
              type: array
        description: |
          To add a new node to the layout or to change the configuration of an existing node, simply set the values you want (`zone`, `capacity`, and `tags`).
          To remove a node, simply pass the `remove: true` field.
          This logic is represented in OpenAPI with a "One Of" object.

          Contrary to the CLI that may update only a subset of the fields capacity, zone and tags, when calling this API all of these values must be specified.
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterLayout'
          description: The layout modification has been correctly staged
      summary: Send modifications to the cluster layout
      tags:
      - Layout
  /layout/apply:
    post:
      description: |
        Applies to the cluster the layout changes currently registered as staged layout changes.

        *Note: do not try to parse the `message` field of the response, it is given as an array of string specifically because its format is not stable.*
      operationId: ApplyLayout
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutVersion'
        description: |
          Similarly to the CLI, the body must include the version of the new layout that will be created, which MUST be 1 + the value of the currently existing layout in the cluster.
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyLayout_200_response'
          description: "The staged layout has been applied as the new layout of the\
            \ cluster, a rebalance has been triggered."
      summary: Apply staged layout
      tags:
      - Layout
  /layout/revert:
    post:
      description: |
        Clears all of the staged layout changes.
      operationId: RevertLayout
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutVersion'
        description: |
          Reverting the staged changes is done by incrementing the version number and clearing the contents of the staged change list. Similarly to the CLI, the body must include the incremented version number, which MUST be 1 + the value of the currently existing layout in the cluster.
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          description: "The staged layout has been cleared, you can start again sending\
            \ modification from a fresh copy with `POST /layout`."
      summary: Clear staged layout
      tags:
      - Layout
  /key?list:
    get:
      description: |
        Returns all API access keys in the cluster.
      operationId: ListKeys
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "200":
          content:
            application/json:
              schema:
                example:
                - id: GK31c2f218a2e44f485b94239e
                  name: test-key
                - id: GKe10061ac9c2921f09e4c5540
                  name: ""
                items:
                  $ref: '#/components/schemas/ListKeys_200_response_inner'
                type: array
          description: |
            Returns the key identifier (aka `AWS_ACCESS_KEY_ID`) and its associated, human friendly, name if any (otherwise return an empty string)
      summary: List all keys
      tags:
      - Key
    post:
      description: |
        Creates a new API access key.
      operationId: AddKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddKey_request'
        description: |
          You can set a friendly name for this key.
          If you don't want to, you can set the name to `null`.

          *Note: the secret key is returned in the response.*
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyInfo'
          description: The key has been added
      summary: Create a new API key
      tags:
      - Key
  /key:
    delete:
      description: "Delete a key from the cluster. Its access will be removed from\
        \ all the buckets. Buckets are not automatically deleted and can be dangling.\
        \ You should manually delete them before. \n"
      operationId: DeleteKey
      parameters:
      - description: The exact API access key generated by Garage
        example: GK31c2f218a2e44f485b94239e
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "200":
          description: The key has been deleted
      summary: Delete a key
      tags:
      - Key
    get:
      description: "Return information about a specific key like its identifiers,\
        \ its permissions and buckets on which it has permissions. \nYou can search\
        \ by specifying the exact key identifier (`id`) or by specifying a pattern\
        \ (`search`).\n\nFor confidentiality reasons, the secret key is not returned\
        \ by default: you must pass the `showSecretKey` query parameter to get it.\n"
      operationId: GetKey
      parameters:
      - description: |
          The exact API access key generated by Garage.

          Incompatible with `search`.
        example: GK31c2f218a2e44f485b94239e
        explode: true
        in: query
        name: id
        required: false
        schema:
          type: string
        style: form
      - description: |
          A pattern (beginning or full string) corresponding to a key identifier or friendly name.

          Incompatible with `id`.
        example: test-k
        explode: true
        in: query
        name: search
        required: false
        schema:
          type: string
        style: form
      - description: Wether or not the secret key should be returned in the response
        example: "true"
        explode: true
        in: query
        name: showSecretKey
        required: false
        schema:
          default: "false"
          enum:
          - "true"
          - "false"
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyInfo'
          description: |
            Returns information about the key
      summary: Get key information
      tags:
      - Key
    post:
      description: |
        Updates information about the specified API access key.

        *Note: the secret key is not returned in the response, `null` is sent instead.*
      operationId: UpdateKey
      parameters:
      - description: The exact API access key generated by Garage
        example: GK31c2f218a2e44f485b94239e
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKey_request'
        description: |
          For a given key, provide a first set with the permissions to grant, and a second set with the permissions to remove
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyInfo'
          description: |
            Returns information about the key
      summary: Update a key
      tags:
      - Key
  /key/import:
    post:
      description: |
        Imports an existing API key. This feature must only be used for migrations and backup restore.

        **Do not use it to generate custom key identifiers or you will break your Garage cluster.**
      operationId: ImportKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportKey_request'
        description: |
          Information on the key to import
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Invalid syntax or requested change
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyInfo'
          description: The key has been imported into the system
      summary: Import an existing key
      tags:
      - Key
  /bucket?list:
    get:
      description: |
        List all the buckets on the cluster with their UUID and their global and local aliases.
      operationId: ListBuckets
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "200":
          content:
            application/json:
              schema:
                example:
                - id: 70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033
                  globalAliases:
                  - container_registry
                - id: 96470e0df00ec28807138daf01915cfda2bee8eccc91dea9558c0b4855b5bf95
                  localAliases:
                  - alias: my_documents
                    accessKeyid: GK31c2f218a2e44f485b94239e
                - id: d7452a935e663fc1914f3a5515163a6d3724010ce8dfd9e4743ca8be5974f995
                  globalAliases:
                  - example.com
                  - www.example.com
                  localAliases:
                  - alias: corp_website
                    accessKeyId: GKe10061ac9c2921f09e4c5540
                  - alias: web
                    accessKeyid: GK31c2f218a2e44f485b94239e
                - id: ""
                items:
                  $ref: '#/components/schemas/ListBuckets_200_response_inner'
                type: array
          description: |
            Returns the UUID of the bucket and all its aliases
      summary: List all buckets
      tags:
      - Bucket
  /bucket:
    delete:
      description: |
        Delete a bucket.Deletes a storage bucket. A bucket cannot be deleted if it is not empty.

        **Warning:** this will delete all aliases associated with the bucket!
      operationId: DeleteBucket
      parameters:
      - description: "The exact bucket identifier, a 32 bytes hexadecimal string"
        example: b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: Bucket is not empty
        "404":
          description: Bucket not found
        "204":
          description: Bucket has been deleted
      summary: Delete a bucket
      tags:
      - Bucket
    get:
      description: |
        Given a bucket identifier (`id`) or a global alias (`alias`), get its information.
        It includes its aliases, its web configuration, keys that have some permissions
        on it, some statistics (number of objects, size), number of dangling multipart uploads,
        and its quotas (if any).
      operationId: GetBucketInfo
      parameters:
      - description: |
          The exact bucket identifier, a 32 bytes hexadecimal string.

          Incompatible with `alias`.
        example: b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87
        explode: true
        in: query
        name: id
        required: false
        schema:
          type: string
        style: form
      - description: |
          The exact global alias of one of the existing buckets.

          Incompatible with `id`.
        example: my_documents
        explode: true
        in: query
        name: alias
        required: false
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Get a bucket
      tags:
      - Bucket
    post:
      description: |
        Creates a new bucket, either with a global alias, a local one, or no alias at all.
        Technically, you can also specify both `globalAlias` and `localAlias` and that would create two aliases.
      operationId: CreateBucket
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBucket_request'
        description: |
          Aliases to put on the new bucket
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: The payload is not formatted correctly
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Create a bucket
      tags:
      - Bucket
    put:
      description: |
        All fields (`websiteAccess` and `quotas`) are optional.
        If they are present, the corresponding modifications are applied to the bucket, otherwise nothing is changed.

        In `websiteAccess`: if `enabled` is `true`, `indexDocument` must be specified.
        The field `errorDocument` is optional, if no error document is set a generic
        error message is displayed when errors happen. Conversely, if `enabled` is
        `false`, neither `indexDocument` nor `errorDocument` must be specified.

        In `quotas`: new values of `maxSize` and `maxObjects` must both be specified, or set to `null`
        to remove the quotas. An absent value will be considered the same as a `null`. It is not possible
        to change only one of the two quotas.
      operationId: UpdateBucket
      parameters:
      - description: "The exact bucket identifier, a 32 bytes hexadecimal string"
        example: b4018dc61b27ccb5c64ec1b24f53454bbbd180697c758c4d47a22a8921864a87
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBucket_request'
        description: |
          Requested changes on the bucket. Both root fields are optionals.
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your body."
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Update a bucket
      tags:
      - Bucket
  /bucket/allow:
    post:
      description: |
        ⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious.

        Allows a key to do read/write/owner operations on a bucket.

        Flags in permissions which have the value true will be activated. Other flags will remain unchanged (ie. they will keep their internal value).

        For example, if you set read to true, the key will be allowed to read the bucket.
        If you set it to false, the key will keeps its previous read permission.
        If you want to disallow read for the key, check the DenyBucketKey operation.
      operationId: AllowBucketKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowBucketKey_request'
        description: |
          Aliases to put on the new bucket
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Allow key
      tags:
      - Bucket
  /bucket/deny:
    post:
      description: |
        ⚠️ **DISCLAIMER**: Garage's developers are aware that this endpoint has an unconventional semantic. Be extra careful when implementing it, its behavior is not obvious.

        Denies a key from doing read/write/owner operations on a bucket.

        Flags in permissions which have the value true will be deactivated. Other flags will remain unchanged.

        For example, if you set read to true, the key will be denied from reading.
        If you set read to false,  the key will keep its previous permissions.
        If you want the key to have the reading permission, check the AllowBucketKey operation.
      operationId: DenyBucketKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllowBucketKey_request'
        description: |
          Aliases to put on the new bucket
        required: true
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Deny key
      tags:
      - Bucket
  /bucket/alias/global:
    delete:
      description: |
        Delete a global alias from the target bucket
      operationId: DeleteBucketGlobalAlias
      parameters:
      - example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      - example: my_documents
        explode: true
        in: query
        name: alias
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Delete a global alias
      tags:
      - Bucket
    put:
      description: |
        Add a global alias to the target bucket
      operationId: PutBucketGlobalAlias
      parameters:
      - example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      - example: my_documents
        explode: true
        in: query
        name: alias
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Add a global alias
      tags:
      - Bucket
  /bucket/alias/local:
    delete:
      description: |
        Delete a local alias, bound to specified account, from the target bucket
      operationId: DeleteBucketLocalAlias
      parameters:
      - example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      - example: GK31c2f218a2e44f485b94239e
        explode: true
        in: query
        name: accessKeyId
        required: true
        schema:
          type: string
        style: form
      - example: my_documents
        explode: true
        in: query
        name: alias
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Delete a local alias
      tags:
      - Bucket
    put:
      description: |
        Add a local alias, bound to specified account, to the target bucket
      operationId: PutBucketLocalAlias
      parameters:
      - example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
        explode: true
        in: query
        name: id
        required: true
        schema:
          type: string
        style: form
      - example: GK31c2f218a2e44f485b94239e
        explode: true
        in: query
        name: accessKeyId
        required: true
        schema:
          type: string
        style: form
      - example: my_documents
        explode: true
        in: query
        name: alias
        required: true
        schema:
          type: string
        style: form
      responses:
        "500":
          description: The server can not handle your request. Check your connectivity
            with the rest of the cluster.
        "400":
          description: "Bad request, check your request body"
        "404":
          description: Bucket not found
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketInfo'
          description: Returns exhaustive information about the bucket
      summary: Add a local alias
      tags:
      - Bucket
components:
  schemas:
    NodeNetworkInfo:
      properties:
        id:
          example: 6a8e08af2aab1083ebab9b22165ea8b5b9d333b60a39ecd504e85cc1f432c36f
          type: string
        addr:
          example: 10.0.0.11:3901
          type: string
        isUp:
          example: true
          type: boolean
        lastSeenSecsAgo:
          example: 9
          nullable: true
          type: integer
        hostname:
          example: node1
          type: string
      required:
      - addr
      - hostname
      - isUp
      - lastSeenSecsAgo
      type: object
    NodeClusterInfo:
      properties:
        zone:
          example: dc1
          type: string
        capacity:
          example: 4
          format: int64
          nullable: true
          type: integer
        tags:
          description: |
            User defined tags, put whatever makes sense for you, these tags are not interpreted by Garage
          example:
          - gateway
          - fast
          items:
            type: string
          type: array
      required:
      - id
      - tags
      - zone
      type: object
    NodeRoleChange:
      oneOf:
      - $ref: '#/components/schemas/NodeRoleRemove'
      - $ref: '#/components/schemas/NodeRoleUpdate'
    NodeRoleRemove:
      properties:
        id:
          example: 6a8e08af2aab1083ebab9b22165ea8b5b9d333b60a39ecd504e85cc1f432c36f
          type: string
        remove:
          example: true
          type: boolean
      required:
      - id
      - remove
      type: object
    NodeRoleUpdate:
      properties:
        id:
          example: 6a8e08af2aab1083ebab9b22165ea8b5b9d333b60a39ecd504e85cc1f432c36f
          type: string
        zone:
          example: dc1
          type: string
        capacity:
          example: 150000000000
          format: int64
          nullable: true
          type: integer
        tags:
          example:
          - gateway
          - fast
          items:
            type: string
          type: array
      required:
      - capacity
      - id
      - tags
      - zone
      type: object
    ClusterLayout:
      example:
        roles:
        - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
          zone: madrid
          capacity: 300000000000
          tags:
          - fast
          - amd64
        - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
          zone: geneva
          capacity: 700000000000
          tags:
          - arm64
        stagedRoleChanges:
        - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
          zone: geneva
          capacity: 800000000000
          tags:
          - gateway
        - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
          remove: true
        version: 12
      properties:
        version:
          example: 12
          type: integer
        roles:
          example:
          - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
            zone: madrid
            capacity: 300000000000
            tags:
            - fast
            - amd64
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            zone: geneva
            capacity: 700000000000
            tags:
            - arm64
          items:
            $ref: '#/components/schemas/NodeClusterInfo'
          type: array
        stagedRoleChanges:
          example:
          - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
            zone: geneva
            capacity: 800000000000
            tags:
            - gateway
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            remove: true
          items:
            $ref: '#/components/schemas/NodeRoleChange'
          type: array
      required:
      - roles
      - stagedRoleChanges
      - version
      type: object
    LayoutVersion:
      example:
        version: 13
      properties:
        version:
          example: 13
          type: integer
      required:
      - version
      type: object
    KeyInfo:
      example:
        accessKeyId: GK31c2f218a2e44f485b94239e
        secretAccessKey: b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835
        permissions:
          createBucket: false
        buckets:
        - permissions:
            owner: false
            read: true
            write: true
          localAliases:
          - GK31c2f218a2e44f485b94239e:localname
          - GK31c2f218a2e44f485b94239e:localname
          globalAliases:
          - my-bucket
          - my-bucket
          id: 70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033
        - permissions:
            owner: false
            read: true
            write: true
          localAliases:
          - GK31c2f218a2e44f485b94239e:localname
          - GK31c2f218a2e44f485b94239e:localname
          globalAliases:
          - my-bucket
          - my-bucket
          id: 70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033
        name: test-key
      properties:
        name:
          example: test-key
          type: string
        accessKeyId:
          example: GK31c2f218a2e44f485b94239e
          type: string
        secretAccessKey:
          example: b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835
          nullable: true
          type: string
        permissions:
          $ref: '#/components/schemas/KeyInfo_permissions'
        buckets:
          items:
            $ref: '#/components/schemas/KeyInfo_buckets_inner'
          type: array
      type: object
    BucketInfo:
      example:
        websiteConfig:
          indexDocument: index.html
          errorDocument: error/400.html
        quotas:
          maxSize: 0
          maxObjects: 6
        keys:
        - accessKeyId: accessKeyId
          bucketLocalAliases:
          - my_documents
          - my_documents
          permissions:
            owner: true
            read: true
            write: true
          name: name
        - accessKeyId: accessKeyId
          bucketLocalAliases:
          - my_documents
          - my_documents
          permissions:
            owner: true
            read: true
            write: true
          name: name
        bytes: 13189855625
        objects: 14827
        globalAliases:
        - my_documents
        - my_documents
        id: afa8f0a22b40b1247ccd0affb869b0af5cff980924a20e4b5e0720a44deb8d39
        websiteAccess: true
        unfinishedUploads: 0
      properties:
        id:
          example: afa8f0a22b40b1247ccd0affb869b0af5cff980924a20e4b5e0720a44deb8d39
          type: string
        globalAliases:
          items:
            example: my_documents
            type: string
          type: array
        websiteAccess:
          example: true
          type: boolean
        websiteConfig:
          $ref: '#/components/schemas/BucketInfo_websiteConfig'
        keys:
          items:
            $ref: '#/components/schemas/BucketKeyInfo'
          type: array
        objects:
          example: 14827
          format: int64
          type: integer
        bytes:
          example: 13189855625
          format: int64
          type: integer
        unfinishedUploads:
          example: 0
          type: integer
        quotas:
          $ref: '#/components/schemas/BucketInfo_quotas'
      type: object
    BucketKeyInfo:
      example:
        accessKeyId: accessKeyId
        bucketLocalAliases:
        - my_documents
        - my_documents
        permissions:
          owner: true
          read: true
          write: true
        name: name
      properties:
        accessKeyId:
          type: string
        name:
          type: string
        permissions:
          $ref: '#/components/schemas/CreateBucket_request_localAlias_allow'
        bucketLocalAliases:
          items:
            example: my_documents
            type: string
          type: array
      type: object
    GetHealth_200_response:
      example:
        storageNodesOk: 3
        partitions: 256
        partitionsQuorum: 256
        knownNodes: 4
        connectedNodes: 4
        storageNodes: 3
        partitionsAllOk: 256
        status: healthy
      properties:
        status:
          example: healthy
          type: string
        knownNodes:
          example: 4
          format: int64
          type: integer
        connectedNodes:
          example: 4
          format: int64
          type: integer
        storageNodes:
          example: 3
          format: int64
          type: integer
        storageNodesOk:
          example: 3
          format: int64
          type: integer
        partitions:
          example: 256
          format: int64
          type: integer
        partitionsQuorum:
          example: 256
          format: int64
          type: integer
        partitionsAllOk:
          example: 256
          format: int64
          type: integer
      required:
      - connectedNodes
      - knownNodes
      - partitions
      - partitionsAllOk
      - partitionsQuorum
      - status
      - storageNodes
      - storageNodesOk
      type: object
    GetNodes_200_response:
      example:
        layout:
          roles:
          - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
            zone: madrid
            capacity: 300000000000
            tags:
            - fast
            - amd64
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            zone: geneva
            capacity: 700000000000
            tags:
            - arm64
          stagedRoleChanges:
          - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
            zone: geneva
            capacity: 800000000000
            tags:
            - gateway
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            remove: true
          version: 12
        node: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
        dbEngine: LMDB (using Heed crate)
        rustVersion: 1.68.0
        knownNodes:
        - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
          addr: 10.0.0.11:3901
          isUp: true
          lastSeenSecsAgo: 9
          hostname: orion
        - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
          addr: 10.0.0.12:3901
          isUp: true
          lastSeenSecsAgo: 13
          hostname: pegasus
        - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
          addr: 10.0.0.13:3901
          isUp: true
          lastSeenSecsAgo: 2
          hostname: neptune
        garageFeatures:
        - k2v
        - lmdb
        - sqlite
        - consul-discovery
        - kubernetes-discovery
        - metrics
        - telemetry-otlp
        - bundled-libs
        garageVersion: v0.9.0
      properties:
        node:
          example: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
          type: string
        garageVersion:
          example: v0.9.0
          type: string
        garageFeatures:
          example:
          - k2v
          - lmdb
          - sqlite
          - consul-discovery
          - kubernetes-discovery
          - metrics
          - telemetry-otlp
          - bundled-libs
          items:
            type: string
          type: array
        rustVersion:
          example: 1.68.0
          type: string
        dbEngine:
          example: LMDB (using Heed crate)
          type: string
        knownNodes:
          example:
          - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
            addr: 10.0.0.11:3901
            isUp: true
            lastSeenSecsAgo: 9
            hostname: orion
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            addr: 10.0.0.12:3901
            isUp: true
            lastSeenSecsAgo: 13
            hostname: pegasus
          - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
            addr: 10.0.0.13:3901
            isUp: true
            lastSeenSecsAgo: 2
            hostname: neptune
          items:
            $ref: '#/components/schemas/NodeNetworkInfo'
          type: array
        layout:
          $ref: '#/components/schemas/ClusterLayout'
      required:
      - dbEngine
      - garageFeatures
      - garageVersion
      - knownNodes
      - layout
      - node
      - rustVersion
      type: object
    AddNode_200_response_inner:
      properties:
        success:
          example: true
          type: boolean
        error:
          nullable: true
          type: string
          example: null
      type: object
    ApplyLayout_200_response:
      example:
        layout:
          roles:
          - id: ec79480e0ce52ae26fd00c9da684e4fa56658d9c64cdcecb094e936de0bfe71f
            zone: madrid
            capacity: 300000000000
            tags:
            - fast
            - amd64
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            zone: geneva
            capacity: 700000000000
            tags:
            - arm64
          stagedRoleChanges:
          - id: e2ee7984ee65b260682086ec70026165903c86e601a4a5a501c1900afe28d84b
            zone: geneva
            capacity: 800000000000
            tags:
            - gateway
          - id: 4a6ae5a1d0d33bf895f5bb4f0a418b7dc94c47c0dd2eb108d1158f3c8f60b0ff
            remove: true
          version: 12
        message:
        - ==== COMPUTATION OF A NEW PARTITION ASSIGNATION ====
        - ""
        - Partitions are replicated 1 times on at least 1 distinct zones.
        - ""
        - "Optimal partition size:                     419.4 MB (3 B in previous layout)"
        - "Usable capacity / total cluster capacity:   107.4 GB / 107.4 GB (100.0\
          \ %)"
        - "Effective capacity (replication factor 1):  107.4 GB"
        - ""
        - A total of 0 new copies of partitions need to be transferred.
        - ""
        - |+
          dc1                 Tags  Partitions        Capacity  Usable capacity
            6a8e08af2aab1083  a,v   256 (0 new)       107.4 GB  107.4 GB (100.0%)
            TOTAL                   256 (256 unique)  107.4 GB  107.4 GB (100.0%)

      properties:
        message:
          example:
          - ==== COMPUTATION OF A NEW PARTITION ASSIGNATION ====
          - ""
          - Partitions are replicated 1 times on at least 1 distinct zones.
          - ""
          - "Optimal partition size:                     419.4 MB (3 B in previous\
            \ layout)"
          - "Usable capacity / total cluster capacity:   107.4 GB / 107.4 GB (100.0\
            \ %)"
          - "Effective capacity (replication factor 1):  107.4 GB"
          - ""
          - A total of 0 new copies of partitions need to be transferred.
          - ""
          - |+
            dc1                 Tags  Partitions        Capacity  Usable capacity
              6a8e08af2aab1083  a,v   256 (0 new)       107.4 GB  107.4 GB (100.0%)
              TOTAL                   256 (256 unique)  107.4 GB  107.4 GB (100.0%)

          items:
            type: string
          type: array
        layout:
          $ref: '#/components/schemas/ClusterLayout'
      required:
      - layout
      - message
      type: object
    ListKeys_200_response_inner:
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      type: object
    AddKey_request:
      properties:
        name:
          example: test-key
          nullable: true
          type: string
      type: object
    UpdateKey_request_allow:
      properties:
        createBucket:
          example: true
          type: boolean
      type: object
      example: null
    UpdateKey_request_deny:
      properties:
        createBucket:
          example: true
          type: boolean
      type: object
    UpdateKey_request:
      properties:
        name:
          example: test-key
          type: string
        allow:
          $ref: '#/components/schemas/UpdateKey_request_allow'
        deny:
          $ref: '#/components/schemas/UpdateKey_request_deny'
      type: object
    ImportKey_request:
      properties:
        name:
          example: test-key
          nullable: true
          type: string
        accessKeyId:
          example: GK31c2f218a2e44f485b94239e
          type: string
        secretAccessKey:
          example: b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835
          type: string
      required:
      - accessKeyId
      - name
      - secretAccessKey
      type: object
    ListBuckets_200_response_inner_localAliases_inner:
      properties:
        alias:
          type: string
        accessKeyId:
          type: string
      required:
      - accessKeyId
      - alias
      type: object
    ListBuckets_200_response_inner:
      properties:
        id:
          type: string
        globalAliases:
          items:
            type: string
          type: array
        localAliases:
          items:
            $ref: '#/components/schemas/ListBuckets_200_response_inner_localAliases_inner'
          type: array
      required:
      - id
      type: object
    UpdateBucket_request_websiteAccess:
      properties:
        enabled:
          example: true
          type: boolean
        indexDocument:
          example: index.html
          type: string
        errorDocument:
          example: error/400.html
          type: string
      type: object
    UpdateBucket_request_quotas:
      properties:
        maxSize:
          example: 19029801
          format: int64
          nullable: true
          type: integer
        maxObjects:
          format: int64
          nullable: true
          type: integer
          example: null
      type: object
    UpdateBucket_request:
      properties:
        websiteAccess:
          $ref: '#/components/schemas/UpdateBucket_request_websiteAccess'
        quotas:
          $ref: '#/components/schemas/UpdateBucket_request_quotas'
      type: object
    CreateBucket_request_localAlias_allow:
      example:
        owner: true
        read: true
        write: true
      properties:
        read:
          example: true
          type: boolean
        write:
          example: true
          type: boolean
        owner:
          example: true
          type: boolean
      type: object
    CreateBucket_request_localAlias:
      properties:
        accessKeyId:
          type: string
        alias:
          type: string
        allow:
          $ref: '#/components/schemas/CreateBucket_request_localAlias_allow'
      type: object
    CreateBucket_request:
      properties:
        globalAlias:
          example: my_documents
          type: string
        localAlias:
          $ref: '#/components/schemas/CreateBucket_request_localAlias'
      type: object
    AllowBucketKey_request_permissions:
      properties:
        read:
          example: true
          type: boolean
        write:
          example: true
          type: boolean
        owner:
          example: true
          type: boolean
      required:
      - owner
      - read
      - write
      type: object
    AllowBucketKey_request:
      properties:
        bucketId:
          example: e6a14cd6a27f48684579ec6b381c078ab11697e6bc8513b72b2f5307e25fff9b
          type: string
        accessKeyId:
          example: GK31c2f218a2e44f485b94239e
          type: string
        permissions:
          $ref: '#/components/schemas/AllowBucketKey_request_permissions'
      required:
      - accessKeyId
      - bucketId
      - permissions
      type: object
    KeyInfo_permissions:
      example:
        createBucket: false
      properties:
        createBucket:
          example: false
          type: boolean
      type: object
    KeyInfo_buckets_inner_permissions:
      example:
        owner: false
        read: true
        write: true
      properties:
        read:
          example: true
          type: boolean
        write:
          example: true
          type: boolean
        owner:
          example: false
          type: boolean
      type: object
    KeyInfo_buckets_inner:
      example:
        permissions:
          owner: false
          read: true
          write: true
        localAliases:
        - GK31c2f218a2e44f485b94239e:localname
        - GK31c2f218a2e44f485b94239e:localname
        globalAliases:
        - my-bucket
        - my-bucket
        id: 70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033
      properties:
        id:
          example: 70dc3bed7fe83a75e46b66e7ddef7d56e65f3c02f9f80b6749fb97eccb5e1033
          type: string
        globalAliases:
          items:
            example: my-bucket
            type: string
          type: array
        localAliases:
          items:
            example: GK31c2f218a2e44f485b94239e:localname
            type: string
          type: array
        permissions:
          $ref: '#/components/schemas/KeyInfo_buckets_inner_permissions'
      type: object
    BucketInfo_websiteConfig:
      example:
        indexDocument: index.html
        errorDocument: error/400.html
      nullable: true
      properties:
        indexDocument:
          example: index.html
          type: string
        errorDocument:
          example: error/400.html
          type: string
      type: object
    BucketInfo_quotas:
      example:
        maxSize: 0
        maxObjects: 6
      properties:
        maxSize:
          format: int64
          nullable: true
          type: integer
          example: null
        maxObjects:
          format: int64
          nullable: true
          type: integer
          example: null
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http