Equinix Batches API

openapi: 3.0.1
info:
  title: Equinix API Authentication Batches API
  description: 'Equinix APIs use the OAuth 2.0 for authentication and authorization. Equinix supports the resource owner password and the client credentials flow.

    To begin, obtain OAuth 2.0 client credentials from the Equinix Developer Console under "My Apps". Then your client application  requests an access token from the Equinix API Authorization endpoint, extracts the access_token from the response, and sends the Bearer token to the API that you want to access'
  termsOfService: https://www.equinix.com/about/legal/terms
  contact:
    name: Equinix API Support
    url: https://docs.equinix.com/api-support.htm
  version: '1.2'
servers:
- url: https://api.equinix.com
tags:
- description: 'Manage device batches. See project endpoints to list batches for a particular project. Check out the product docs to learn more about [Batch Deployment](https://metal.equinix.com/developers/docs/deploy/batch-deployment/).

    '
  externalDocs:
    url: https://metal.equinix.com/developers/docs/deploy/batch-deployment/
  name: Batches
paths:
  /batches/{id}:
    delete:
      description: Deletes the Batch.
      operationId: deleteBatch
      parameters:
      - description: Batch UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Delete all instances created from this batch
        in: query
        name: remove_associated_instances
        schema:
          default: false
          type: boolean
      responses:
        '204':
          description: no content
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Delete the Batch
      tags:
      - Batches
    get:
      description: Returns a Batch
      operationId: findBatchById
      parameters:
      - description: Batch UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Batch'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Retrieve a Batch
      tags:
      - Batches
  /projects/{id}/batches:
    get:
      description: Returns all batches for the given project
      operationId: findBatchesByProject
      parameters:
      - description: Project UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: 'Nested attributes to include. Included objects will return their full

          attributes. Attribute names can be dotted (up to 3 levels) to included deeply

          nested objects.'
        explode: false
        in: query
        name: include
        schema:
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchesList'
          description: ok
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
      summary: Retrieve all batches by project
      tags:
      - Batches
  /projects/{id}/devices/batch:
    post:
      description: Creates new devices in batch and provisions them in our datacenter.
      operationId: createDeviceBatch
      parameters:
      - description: Project UUID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstancesBatchCreateInput'
        description: Batches to create
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchesList'
          description: created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: unprocessable entity
      summary: Create a devices batch
      tags:
      - Batches
components:
  schemas:
    FacilityInput:
      properties:
        facility:
          deprecated: true
          description: 'The datacenter where the device should be created.


            Either metro or facility must be provided.


            The API will accept either a single facility `{ "facility": "f1" }`, or it can be instructed to create the device in the best available datacenter `{ "facility": "any" }`.


            Additionally it is possible to set a prioritized location selection. For example `{ "facility": ["f3", "f2", "any"] }` can be used to prioritize `f3` and then `f2` before accepting `any` facility. If none of the facilities provided have availability for the requested device the request will fail.'
          example:
          - sv15
          items:
            type: string
          type: array
      required:
      - facility
      type: object
    BatchesList:
      example:
        batches:
        - quantity: 0
          updated_at: 2000-01-23 04:56:07+00:00
          devices:
          - href: href
          - href: href
          created_at: 2000-01-23 04:56:07+00:00
          project:
            href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          state: state
          error_messages:
          - error_messages
          - error_messages
        - quantity: 0
          updated_at: 2000-01-23 04:56:07+00:00
          devices:
          - href: href
          - href: href
          created_at: 2000-01-23 04:56:07+00:00
          project:
            href: href
          id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
          state: state
          error_messages:
          - error_messages
          - error_messages
      properties:
        batches:
          items:
            $ref: '#/components/schemas/Batch'
          type: array
      type: object
    Batch:
      example:
        quantity: 0
        updated_at: 2000-01-23 04:56:07+00:00
        devices:
        - href: href
        - href: href
        created_at: 2000-01-23 04:56:07+00:00
        project:
          href: href
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        state: state
        error_messages:
        - error_messages
        - error_messages
      properties:
        created_at:
          format: date-time
          type: string
        devices:
          items:
            $ref: '#/components/schemas/Href'
          type: array
        error_messages:
          items:
            type: string
          type: array
        id:
          format: uuid
          type: string
        project:
          $ref: '#/components/schemas/Href'
        quantity:
          type: integer
        state:
          type: string
        updated_at:
          format: date-time
          type: string
      type: object
    SSHKeyInput:
      example:
        label: label
        key: key
        tags:
        - tags
        - tags
      properties:
        key:
          type: string
        label:
          type: string
        tags:
          items:
            type: string
          type: array
      type: object
    Partition:
      example:
        number: 3
        size: size
        label: label
      properties:
        label:
          type: string
        number:
          format: int32
          type: integer
        size:
          type: string
      type: object
    Mount:
      example:
        format: format
        options:
        - options
        - options
        device: device
        point: point
      properties:
        device:
          type: string
        format:
          type: string
        point:
          type: string
        options:
          items:
            type: string
          type: array
      type: object
    Raid:
      example:
        devices:
        - devices
        - devices
        level: level
        name: name
      properties:
        devices:
          items:
            type: string
          type: array
        level:
          type: string
        name:
          type: string
      type: object
    InstancesBatchCreateInput:
      example:
        batches:
        - null
        - null
      properties:
        batches:
          items:
            $ref: '#/components/schemas/InstancesBatchCreateInput_batches_inner'
          type: array
      type: object
    IPAddress:
      properties:
        address_family:
          $ref: '#/components/schemas/IPAddress_address_family'
        cidr:
          description: Cidr Size for the IP Block created. Valid values depends on the operating system being provisioned. (28..32 for IPv4 addresses, 124..127 for IPv6 addresses)
          example: 28
          format: int32
          type: integer
        ip_reservations:
          description: UUIDs of any IP reservations to use when assigning IPs
          items:
            type: string
          type: array
        public:
          default: true
          description: Address Type for IP Address
          example: false
          type: boolean
      type: object
    DeviceCreateInput_billing_cycle:
      description: The billing cycle of the device.
      enum:
      - hourly
      - daily
      - monthly
      - yearly
      type: string
    DeviceCreateInMetroInput:
      allOf:
      - $ref: '#/components/schemas/MetroInput'
      - $ref: '#/components/schemas/DeviceCreateInput'
    IPAddress_address_family:
      description: Address Family for IP Address
      enum:
      - 4
      - 6
      example: 4
      format: int32
      type: integer
    InstancesBatchCreateInput_batches_inner:
      allOf:
      - properties:
          hostnames:
            items:
              type: string
            type: array
          quantity:
            description: The number of devices to create in this batch. The hostname may contain an `{{index}}` placeholder, which will be replaced with the index of the device in the batch. For example, if the hostname is `device-{{index}}`, the first device in the batch will have the hostname `device-01`, the second device will have the hostname `device-02`, and so on.
            type: integer
        type: object
      - oneOf:
        - $ref: '#/components/schemas/DeviceCreateInMetroInput'
        - $ref: '#/components/schemas/DeviceCreateInFacilityInput'
    Disk:
      example:
        partitions:
        - number: 3
          size: size
          label: label
        - number: 3
          size: size
          label: label
        wipeTable: true
        device: device
      properties:
        device:
          type: string
        wipeTable:
          type: boolean
        partitions:
          items:
            $ref: '#/components/schemas/Partition'
          type: array
      type: object
    Filesystem:
      example:
        mount:
          format: format
          options:
          - options
          - options
          device: device
          point: point
      properties:
        mount:
          $ref: '#/components/schemas/Mount'
      type: object
    DeviceCreateInput:
      properties:
        always_pxe:
          default: false
          description: 'When true, devices with a `custom_ipxe` OS will always boot to iPXE. The

            default setting of false ensures that iPXE will be used on only the

            first boot.'
          type: boolean
        billing_cycle:
          $ref: '#/components/schemas/DeviceCreateInput_billing_cycle'
        customdata:
          additionalProperties: true
          default: {}
          description: 'Customdata is an arbitrary JSON value that can be accessed via the

            metadata service.'
          type: object
        description:
          description: 'Any description of the device or how it will be used. This may be used

            to inform other API consumers with project access.'
          type: string
        features:
          description: 'The features attribute allows you to optionally specify what features your server should have.


            In the API shorthand syntax, all features listed are `required`:


            ```

            { "features": ["tpm"] }

            ```


            Alternatively, if you do not require a certain feature, but would prefer to be assigned a server with that feature if there are any available, you may specify that feature with a `preferred` value. The request will not fail if we have no servers with that feature in our inventory. The API offers an alternative syntax for mixing preferred and required features:


            ```

            { "features": { "tpm": "required", "raid": "preferred" } }

            ```


            The request will only fail if there are no available servers matching the required `tpm` criteria.'
          items:
            type: string
          type: array
        hardware_reservation_id:
          default: ''
          description: 'The Hardware Reservation UUID to provision. Alternatively, `next-available` can be specified to select from any of the available hardware reservations. An error will be returned if the requested reservation option is not available.


            See [Reserved Hardware](https://metal.equinix.com/developers/docs/deploy/reserved/) for more details.'
          example: next-available
          type: string
        hostname:
          description: The hostname to use within the operating system. The same hostname may be used on multiple devices within a project.
          type: string
        ip_addresses:
          default:
          - address_family: 4
            public: true
          - address_family: 4
            public: false
          - address_family: 6
            public: true
          description: 'The `ip_addresses attribute will allow you to specify the addresses you want created with your device.


            The default value configures public IPv4, public IPv6, and private IPv4.


            Private IPv4 address is required. When specifying `ip_addresses`, one of the array items must enable private IPv4.


            Some operating systems require public IPv4 address. In those cases you will receive an error message if public IPv4 is not enabled.


            For example, to only configure your server with a private IPv4 address, you can send `{ "ip_addresses": [{ "address_family": 4, "public": false }] }`.


            It is possible to request a subnet size larger than a `/30` by assigning addresses using the UUID(s) of ip_reservations in your project.


            For example, `{ "ip_addresses": [..., {"address_family": 4, "public": true, "ip_reservations": ["uuid1", "uuid2"]}] }`


            To access a server without public IPs, you can use our Out-of-Band console access (SOS) or proxy through another server in the project with public IPs enabled.'
          items:
            $ref: '#/components/schemas/IPAddress'
          type: array
        ipxe_script_url:
          description: 'When set, the device will chainload an iPXE Script at boot fetched from the supplied URL.


            See [Custom iPXE](https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/) for more details.'
          externalDocs:
            url: https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/
          type: string
        locked:
          default: false
          description: Whether the device should be locked, preventing accidental deletion.
          type: boolean
        network_frozen:
          description: If true, this instance can not be converted to a different network type.
          type: boolean
        no_ssh_keys:
          default: false
          description: Overrides default behaviour of attaching all of the organization members ssh keys and project ssh keys to device if no specific keys specified
          type: boolean
        operating_system:
          description: The slug of the operating system to provision. Check the Equinix Metal operating system documentation for rules that may be imposed per operating system, including restrictions on IP address options and device plans.
          type: string
        plan:
          description: The slug of the device plan to provision.
          example: c3.large.x86
          type: string
        private_ipv4_subnet_size:
          default: 28
          description: Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device.
          format: int32
          type: integer
          x-deprecated: true
        project_ssh_keys:
          description: 'A list of UUIDs identifying the device parent project

            that should be authorized to access this device (typically

            via /root/.ssh/authorized_keys). These keys will also appear in the device metadata.


            If no SSH keys are specified (`user_ssh_keys`, `project_ssh_keys`, and `ssh_keys` are all empty lists or omitted),

            all parent project keys, parent project members keys and organization members keys will be included. This behaviour can

            be changed with ''no_ssh_keys'' option to omit any SSH key being added.

            '
          items:
            format: uuid
            type: string
          type: array
        public_ipv4_subnet_size:
          default: 31
          description: Deprecated. Use ip_addresses. Subnet range for addresses allocated to this device. Your project must have addresses available for a non-default request.
          format: int32
          type: integer
          x-deprecated: true
        spot_instance:
          description: Create a spot instance. Spot instances are created with a maximum bid price. If the bid price is not met, the spot instance will be terminated as indicated by the `termination_time` field.
          type: boolean
        spot_price_max:
          description: The maximum amount to bid for a spot instance.
          example: 1.23
          format: float
          type: number
        ssh_keys:
          description: "A list of new or existing project ssh_keys\nthat should be authorized to access this device (typically\nvia /root/.ssh/authorized_keys). These keys will also\nappear in the device metadata.\n\nThese keys are added in addition to any keys defined by\n  `project_ssh_keys` and `user_ssh_keys`.\n"
          items:
            $ref: '#/components/schemas/SSHKeyInput'
          type: array
        storage:
          $ref: '#/components/schemas/Storage'
        tags:
          items:
            type: string
          type: array
        termination_time:
          description: 'When the device will be terminated. If you don''t supply timezone info, the timestamp is assumed to be in UTC.


            This is commonly set in advance for

            ephemeral spot market instances but this field may also be set with

            on-demand and reservation instances to automatically delete the resource

            at a given time. The termination time can also be used to release a

            hardware reservation instance at a given time, keeping the reservation

            open for other uses.  On a spot market device, the termination time will

            be set automatically when outbid.

            '
          example: 2021-09-03 16:32:00+03:00
          format: date-time
          type: string
        user_ssh_keys:
          description: 'A list of UUIDs identifying the users

            that should be authorized to access this device (typically

            via /root/.ssh/authorized_keys).  These keys will also

            appear in the device metadata.


            The users must be members of the project or organization.


            If no SSH keys are specified (`user_ssh_keys`, `project_ssh_keys`, and `ssh_keys` are all empty lists or omitted),

            all parent project keys, parent project members keys and organization members keys will be included. This behaviour can

            be changed with ''no_ssh_keys'' option to omit any SSH key being added.

            '
          items:
            format: uuid
            type: string
          type: array
        userdata:
          description: 'The userdata presented in the metadata service for this device.  Userdata is fetched and interpreted by the operating system installed on the device. Acceptable formats are determined by the operating system, with the exception of a special iPXE enabling syntax which is handled before the operating system starts.


            See [Server User Data](https://metal.equinix.com/developers/docs/servers/user-data/) and [Provisioning with Custom iPXE](https://metal.equinix.com/developers/docs/operating-systems/custom-ipxe/#provisioning-with-custom-ipxe) for more details.'
          externalDocs:
            url: https://metal.equinix.com/developers/docs/servers/user-data/
          type: string
      required:
      - operating_system
      - plan
      type: object
    Error:
      description: Error responses are included with 4xx and 5xx HTTP responses from the API service. Either "error" or "errors" will be set.
      properties:
        error:
          description: A description of the error that caused the request to fail.
          type: string
        errors:
          description: A list of errors that contributed to the request failing.
          items:
            description: An error message that contributed to the request failing.
            type: string
          type: array
      type: object
    MetroInput:
      properties:
        metro:
          description: 'Metro code or ID of where the instance should be provisioned in.

            Either metro or facility must be provided.'
          example: sv
          type: string
      required:
      - metro
      type: object
    Storage:
      example:
        disks:
        - partitions:
          - number: 3
            size: size
            label: label
          - number: 3
            size: size
            label: label
          wipeTable: true
          device: device
        - partitions:
          - number: 3
            size: size
            label: label
          - number: 3
            size: size
            label: label
          wipeTable: true
          device: device
        filesystems:
        - mount:
            format: format
            options:
            - options
            - options
            device: device
            point: point
        - mount:
            format: format
            options:
            - options
            - options
            device: device
            point: point
        raid:
        - devices:
          - devices
          - devices
          level: level
          name: name
        - devices:
          - devices
          - devices
          level: level
          name: name
      properties:
        disks:
          items:
            $ref: '#/components/schemas/Disk'
          type: array
        raid:
          items:
            $ref: '#/components/schemas/Raid'
          type: array
        filesystems:
          items:
            $ref: '#/components/schemas/Filesystem'
          type: array
      type: object
    DeviceCreateInFacilityInput:
      allOf:
      - $ref: '#/components/schemas/FacilityInput'
      - $ref: '#/components/schemas/DeviceCreateInput'
    Href:
      example:
        href: href
      properties:
        href:
          type: string
      required:
      - href
      type: object
x-eqx-api-linter-skip-rules:
- 3
- 38