canonical: https://jentic.com/apis/phpipam.net/phpipam

# phpIPAM

Jentic publishes the only available OpenAPI specification for phpIPAM, keeping it validated and agent-ready. phpIPAM is an open-source IP address management (IPAM) system that provides a REST API for managing network sections, subnets, IP addresses, VLANs, VRFs, L2 domains, and network devices. The API exposes 49 endpoints covering subnet allocation, address assignment, VLAN tracking, device inventory, and utilization reporting for enterprise and data center network management.

## For AI agents

Manage IP address allocations, subnets, VLANs, VRFs, and network devices through phpIPAM's REST API. Assign addresses, check subnet utilization, and track network infrastructure inventory.

## Scope

Does not handle DNS management, firewall rules, traffic monitoring, or network configuration deployment - use for IP address and subnet inventory management only.

## Capabilities

- Allocate and release IP addresses within managed subnets with automatic first-free detection
- Create and organize subnets into hierarchical sections for network segmentation
- Track VLAN assignments and map them to subnets across L2 domains
- Manage VRF instances and their associated subnet ranges for routing isolation
- Maintain a device inventory with subnet and address associations per device
- Query subnet utilization metrics including used, free, and reserved address counts
- Search IP addresses by hostname, MAC address, or IP across all managed subnets

## Use cases

### IP Address Allocation

Assign IP addresses to hosts within managed subnets using automatic first-free detection. phpIPAM tracks which addresses are in use, reserved, or available, preventing allocation conflicts. The API returns the next available address in a given subnet and creates the assignment record with hostname and MAC metadata in a single call.

Example prompt: Query GET `/addresses/first_free/{subnetId}` for subnet ID 5 to get the next available IP, then POST /addresses/ to assign it with hostname 'web-server-04'

### Subnet and VLAN Management

Create, organize, and monitor subnets with VLAN tagging and section grouping. phpIPAM supports hierarchical subnet structures, CIDR-based lookups, and VLAN-to-subnet mapping across multiple L2 domains. Network engineers use this to plan address space allocation and track which VLANs serve which network segments.

Example prompt: Create a new /24 subnet under section ID 2 with VLAN tag 100, then query its utilization to confirm zero addresses are in use

### Network Device Inventory

Maintain a centralized inventory of network devices (routers, switches, firewalls) with their associated subnets and IP addresses. phpIPAM links each device to the subnets it manages and the addresses assigned to its interfaces, providing a single source of truth for network topology documentation.

Example prompt: List all devices with GET /devices/, then retrieve all subnets managed by device ID 3 using GET `/devices/3/subnets`/

### AI Agent Network Provisioning via Jentic

AI agents managing infrastructure provisioning can allocate IP addresses and create subnets through Jentic without managing phpIPAM tokens directly. The agent searches for IP allocation operations, loads the endpoint schema, and executes with Jentic handling token-based authentication. This enables automated network provisioning as part of server deployment workflows.

Example prompt: Search Jentic for 'allocate next free IP address', load the phpIPAM first_free operation, and assign the returned address to a new server with hostname 'db-replica-02'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/user/` | Authenticate and obtain an API token |
| GET | `/subnets/{id}/` | Retrieve subnet details by ID |
| GET | `/subnets/{id}/usage/` | Get subnet utilization statistics |
| GET | `/subnets/{id}/addresses/` | List all addresses in a subnet |
| GET | `/addresses/first_free/{subnetId}/` | Find the next available IP in a subnet |
| POST | `/addresses/` | Create a new IP address assignment |
| GET | `/addresses/search/{ip}/` | Search for an IP address across all subnets |
| GET | `/vlan/` | List all VLANs |

## Key resources

- **Sections** — Organize subnets into hierarchical groups for network segmentation
- **Subnets** — Create, manage, and query subnets with CIDR notation and utilization tracking
- **Addresses** — Assign, search, and manage individual IP addresses within subnets
- **VLANs** — Track VLAN assignments and map them to subnets
- **VRFs** — Manage Virtual Routing and Forwarding instances with associated subnets
- **Devices** — Maintain network device inventory with subnet and address associations
- **L2 Domains** — Manage Layer 2 domains that group VLANs

## Why Jentic

- **Setup:** Wiring phpIPAM by hand means logging in via POST /user/ to obtain a token or using basic auth, pointing at your own {host} and {appName} since the base URL is templated per install, and formatting the subnet and address requests yourself. Through Jentic you install once, import phpIPAM from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** phpIPAM puts the resource id in the URL path (`/subnets/{id}`/, `/addresses/search/{ip}`/, `/addresses/first_free/{subnetId}`/), so a rule can pin your agent to one subnet: it can read that subnet, its usage, and its addresses. You choose the operations it may call, so writes like creating an address or logging in a user are not included unless you add them.
- **Credential handling:** Your phpIPAM token or basic credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find the next free IP in a subnet', and Jentic returns the matching phpIPAM operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NetBox API** — Data center infrastructure management including IPAM, DCIM, and circuit tracking
- **Cloudinary Admin API** — Cloud resource management that pairs with IPAM for infrastructure documentation
- **Telnyx API** — Telephony and networking infrastructure with IP-based SIP services

## FAQ

### Why is there no official OpenAPI spec for phpIPAM?

phpIPAM does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call phpIPAM via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the phpIPAM API use?

phpIPAM supports two authentication methods: token-based auth via the phpipam-token header (obtained from POST /user/) and HTTP Basic authentication. Token auth is preferred for API integrations. Through Jentic, credentials are stored in your Jentic One instance and the phpipam-token header is injected automatically after token acquisition.

### Can I find the next available IP address in a subnet?

Yes. Use GET `/addresses/first_free/{subnetId}`/ to retrieve the next unassigned IP address in a given subnet. The endpoint scans the subnet's address range and returns the first address that is not currently assigned, reserved, or excluded.

### How do I search for an IP address across all managed subnets?

Use GET `/addresses/search/{ip}`/ with the full IP address to find its assignment record regardless of which subnet it belongs to. You can also search by hostname with GET `/addresses/search_hostname/{hostname}`/ or by MAC address with GET `/addresses/search_mac/{mac}/.`

### How do I allocate IP addresses through Jentic with phpIPAM?

Search Jentic for 'find next free IP address in subnet' to find the first_free operation. Load the schema, provide your subnet ID, and execute to get an available IP. Then use the create address operation (POST /addresses/) to assign it with hostname and description. Jentic handles token authentication throughout.

### Does phpIPAM support VLAN-to-subnet mapping?

Yes. VLANs are managed as a separate resource (GET /vlan/) and each subnet can be associated with a VLAN. Use GET `/vlan/{id}/subnets`/ to retrieve all subnets tagged with a specific VLAN ID. L2 domains provide an additional grouping layer for VLANs across network segments.

### Can I limit what my agent is allowed to do with the phpIPAM API?

Yes. Because you run Jentic One yourself, your own rules decide which phpIPAM operations and credentials the agent may use. Since phpIPAM carries the resource id in the URL path, such as `/subnets/{id}`/, `/subnets/{id}/usage`/, and `/addresses/first_free/{subnetId}`/, you can pin the agent to a single subnet so it only reads that subnet, its usage, and its addresses. You also choose the exact operations it may call, so writes like creating an address with POST /addresses/ or logging in a user via POST /user/ stay out of reach unless you add them.