> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach an interface to a floating IP

> Adds the interface to the floating IP. Reattaching the same interface and address is idempotent.

Multiple direct interfaces must belong to the same VPC and require anycast support in the region. Pool-owned and load-balancer-owned addresses are refused (409); manage them through their owner. A direct interface without a health check has health `unknown` and remains advertised.

A public floating IP requires the interface subnet to route the family default (`0.0.0.0/0` or `::/0`) to an internet gateway. A private floating IP requires an interface in its allocation VPC. Each interface can receive one floating IP per family and visibility.


<Info>
  Requires the IAM action **`network:AttachFloatingIP`**. See [NETWORK permissions](/networking/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/network.yaml post /v1/floating-ips/{floating_ip_id}/interfaces
openapi: 3.0.3
info:
  title: Basaltic Network API
  version: 1.0.0
  description: |
    The VPC surface — networks and subnets, interfaces, route tables,
    security groups, internet, NAT and egress-only gateways, and floating
    IPs.

    Relationship inputs use one reference field: UUID, CRN, or an exact name
    when the request supplies its required parent scope. Subnets and route
    tables are VPC-scoped; interfaces are subnet-scoped. Nested CRNs use
    vpc/<vpc>/subnet/<subnet>, vpc/<vpc>/route-table/<table>, and
    vpc/<vpc>/subnet/<subnet>/interface/<interface>. Names are immutable.
    Unknown request fields and list parameters are rejected.
    Supplied empty references are invalid and failed lookups never fall back
    to another reference kind. Every list accepts exact name and crn filters.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://network.{region}.basaltic.sh
    description: Regional API endpoint
    variables:
      region:
        default: sa-saopaulo-1
        description: Region code
security:
  - BearerAuth: []
paths:
  /v1/floating-ips/{floating_ip_id}/interfaces:
    post:
      tags:
        - Networking
      summary: Attach an interface to a floating IP
      description: >
        Adds the interface to the floating IP. Reattaching the same interface
        and address is idempotent.


        Multiple direct interfaces must belong to the same VPC and require
        anycast support in the region. Pool-owned and load-balancer-owned
        addresses are refused (409); manage them through their owner. A direct
        interface without a health check has health `unknown` and remains
        advertised.


        A public floating IP requires the interface subnet to route the family
        default (`0.0.0.0/0` or `::/0`) to an internet gateway. A private
        floating IP requires an interface in its allocation VPC. Each interface
        can receive one floating IP per family and visibility.
      operationId: attachFloatingIp
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/FloatingIpId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - interface
                - address_id
              properties:
                interface:
                  type: string
                  minLength: 1
                  description: >-
                    Interface UUID or nested CRN. Bare names have no subnet
                    scope and are rejected.
                  example: >-
                    crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
                address_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Interface attached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FloatingIpInterfaceResponse'
        '400':
          description: >-
            The region does not support anycast, or the interface has no
            matching address or required internet gateway route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            The interface already carries another floating IP of this family and
            visibility, belongs to a different VPC, or the address is owned by a
            load balancer or instance pool.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Optional client-generated key that makes a create replay-safe. Retrying
        a request with the same key returns the original outcome verbatim
        instead of creating a duplicate resource. Reusing a key with a different
        request body is rejected (422); a request whose key is still being
        processed returns 409. Records are honored for 24 hours. Use a UUID or
        similarly unique token.
      required: false
      schema:
        type: string
        maxLength: 255
      example: 550e8400-e29b-41d4-a716-446655440000
    FloatingIpId:
      name: floating_ip_id
      in: path
      description: Floating IP ID
      required: true
      schema:
        type: string
        format: uuid
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    FloatingIpInterfaceResponse:
      type: object
      required:
        - interface
      properties:
        interface:
          $ref: '#/components/schemas/FloatingIpInterface'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
    FloatingIpInterface:
      description: An interface receiving the floating IP, with its attachment health.
      allOf:
        - $ref: '#/components/schemas/Interface'
        - type: object
          required:
            - health
            - reason
          properties:
            health:
              type: string
              enum:
                - unknown
                - healthy
                - unhealthy
              description: >
                What the platform knows about this member.


                `unknown` — nobody is checking. A member you attached yourself
                with no

                health check on the address reads this: you chose the moment of
                attach,

                and the platform has no signal about what runs inside the
                instance. It

                is advertised.


                `healthy` — the platform has evidence this member is up (and, if
                a

                health check is configured on the address, that the check is
                passing).


                `unhealthy` — the platform is waiting for that evidence and has
                not

                seen it, or a configured check is failing. The member keeps its
                place

                on the address and receives no traffic until it recovers.


                Without a health check this is liveness only — `healthy` means
                the guest

                came up, not that your service is listening. Configure
                `health_check` on

                the floating IP to add readiness on top of that.
              example: unknown
            reason:
              type: string
              enum:
                - unprobed
                - booting
                - probe_failed
                - passing
              description: >
                Why the member reads the `health` it does — so you can tell
                "your

                service is not answering" from "the guest has not booted yet".


                `unprobed` — nobody is checking (no health check,
                hand-attached).

                `booting` — the platform has not yet seen the guest come up.

                `probe_failed` — the configured health check is failing.

                `passing` — the guest is up and, if a check is configured, it
                passes.
              example: unprobed
            address_id:
              type: string
              format: uuid
              description: Target child address on the member interface.
    Interface:
      type: object
      required:
        - id
        - crn
        - subnet
        - name
        - mac
        - tags
        - created_at
        - updated_at
        - attached_to
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        crn:
          type: string
          readOnly: true
          example: >-
            crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/web-eth0
        subnet:
          allOf:
            - $ref: '#/components/schemas/ResourceRef'
          description: Subnet containing this interface.
          example:
            id: 550e8400-e29b-41d4-a716-446655440006
            crn: crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/private
            name: private
        name:
          description: >-
            Resource names must not start with the literal crn: prefix or be
            UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
            case).
          type: string
          example: web-eth0
        description:
          type: string
          example: Primary NIC for the web server
        mac:
          type: string
          example: aa:bb:cc:dd:ee:ff
        attached_to:
          anyOf:
            - $ref: '#/components/schemas/ResourceRef'
            - type: object
              nullable: true
              enum:
                - null
          description: >-
            Instance holding this interface, including a stopped instance. Null
            when unbound. Floating IP attachments are tracked separately.
          example:
            id: 550e8400-e29b-41d4-a716-446655440010
            crn: crn:compute:sa-saopaulo-1:my-account:instance/web-1
            name: web-1
        tags:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    ResourceRef:
      type: object
      required:
        - id
        - crn
      properties:
        id:
          type: string
          format: uuid
          example: 288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        crn:
          type: string
          example: crn:catalog::platform:country/288aa1e9-bbf5-5584-bce9-6a688f06d8a1
        name:
          type: string
          description: >-
            Display label at response time — the resource's name where it has
            one, otherwise its human label (an invoice number, an account
            display name). Absent when the target is gone. Not a lookup key.
          example: Brazil
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
    UnprocessableEntity:
      description: |
        The request is well-formed but cannot be processed as sent. On the
        operations that accept `Idempotency-Key` this is the key-reuse case: the
        key was first seen with a different request payload, so replaying the
        stored outcome would answer a question the caller did not ask.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: IDEMPOTENCY_KEY_REUSED
              message: >-
                This Idempotency-Key was already used with a different request
                payload
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.