Network interface API

Network interface API

Attach guest interfaces and manage explicit or automatic address allocations.

Interfaces connect droplets to project networks and own their address reservations. A droplet can retain an interface while stopped.

POST/organizations/{organization_id}/projects/{project_id}/droplets/{droplet_id}/interfaces
Scope
networks:write
Auth
Bearer API key

Attaches an interface and reserves an address for the target droplet.

The caller also needs permission to configure the target droplet. Supply the current droplet ETag in If-Match.

Attachment request
network_idstringrequired
Network in the same project and region.
subnet_idstringrequired
Subnet belonging to that network.
addressstringoptional
Explicit usable address when provided. null is invalid.
defaultAutomatic allocation
primarybooleanoptional
Requests primary-interface designation; at most one interface can be primary.
defaultfalse

Returns 202 with interface ID, reservation summary, and operation. Unsupported hot attachment returns 409 droplet_must_be_stopped. An occupied address returns 422 address_in_use; an exhausted range returns 422 subnet_exhausted.

Read observed attachment

GET/organizations/{organization_id}/projects/{project_id}/interfaces/{interface_id}
Scope
networks:read
Auth
Bearer API key

Returns interface identity, addresses, and desired and applied revisions.

Requires networks:read. The resource contains droplet_id, network_id, subnet_id, mac_address, addresses, state, desired_revision, and applied_revision.

Its virtual interface can be realized before the guest applies its address. Guest configuration status is separate from hypervisor attachment. The observed MAC address belongs to this interface and is not copied during droplet cloning.

Add an address family

POST/organizations/{organization_id}/projects/{project_id}/interfaces/{interface_id}/addresses
Scope
networks:write
Auth
Bearer API key

Adds another address allocation to an interface.

Accepts subnet_id and optional address. It requires If-Match on the interface and creates another allocation when the network and guest support the family. It does not delete the existing IPv4 allocation when adding IPv6.

DELETE/organizations/{organization_id}/projects/{project_id}/interfaces/{interface_id}/addresses/{allocation_id}
Scope
networks:write
Auth
Bearer API key

Removes the selected allocation. The operation can interrupt a listener bound to that address. It does not update external DNS records automatically.

Detach

DELETE/organizations/{organization_id}/projects/{project_id}/interfaces/{interface_id}
Scope
networks:write
Auth
Bearer API key

Detaches an interface and releases its addresses after cleanup.

Requires the interface ETag. Removing a primary interface requires a stopped droplet or an explicitly supported primary handover. The API rejects a change that would leave a running guest with an unsupported network configuration.

Address reservations are released after realization cleanup, not merely after the delete request is accepted. Query the original operation when an address still appears held.

See subnet addressing, Route API, and Firewalls for the other connectivity layers.

Allowed identities

PATCH/organizations/{organization_id}/projects/{project_id}/interfaces/{interface_id}
Scope
networks:write
Auth
Bearer API key

Updates the interface's allowed address pairs.

Accepts allowed_address_pairs and requires the interface ETag plus authorized network administration. Each entry has address as a permitted CIDR and optional mac_address; omission uses the managed interface MAC.

The array replaces the complete set. Omission preserves it, an empty array clears it, and null is rejected. Invalid prefixes, conflicting address ownership, and forbidden forwarding exceptions return 422 before application.

Accepted realization returns 202. Inspect desired and applied revision before assuming a new identity or withdrawal is active. See interface anti-spoofing.