REST API for IP addresses and subnets – documentation

Basics

Base URL: https://ipmanager.no/api/v1
All requests and responses are JSON (Content-Type: application/json).
Authenticate with an API key in the header Authorization: Bearer ipm_….
Every change made through the API is written to the audit log, with the key's name as the actor.

API keys and scopes

Keys are created by an administrator under Auto-discovery & API. The key is shown only once. Each key has one scope:

Scope	Can
`read`	Read addresses, subnets and search (GET)
`write`	Everything `read` can, plus create, change and delete
`agent`	Only send agent reports (`POST /agent/report`)

Example

curl -H "Authorization: Bearer $IPM_TOKEN" https://ipmanager.no/api/v1/search?q=10.20.3

Endpoints

Method	Path	Description
GET	`/addresses`	List addresses. Parameters: `q`, `status`, `subnet`, `limit`, `offset`
POST	`/addresses`	Create an address
GET	`/addresses/{id}`	Get one address
PATCH	`/addresses/{id}`	Change fields on an address
DELETE	`/addresses/{id}`	Delete an address
GET	`/subnets`	List subnets
POST	`/subnets`	Create a subnet
GET	`/subnets/{id}`	Get one subnet
PATCH	`/subnets/{id}`	Change a subnet
DELETE	`/subnets/{id}`	Delete a subnet (addresses are kept)
GET	`/subnets/{id}/next-free`	Next free IPv4 address in the subnet
GET	`/search?q=`	The same search as in the interface, filters included
POST	`/agent/report`	Report from an agent or collector
GET	`/agent/dns/targets?cidr=`	Registered addresses with hostnames to DNS-check (agent or read scope)
POST	`/agent/dns/report`	DNS check results from the collector
GET	`/conflicts`	List conflicts
POST	`/conflicts/{id}`	Handle a conflict (acknowledge or resolve)

Address fields

Field	Type	Notes
`ip`	string	IPv4 or IPv6. Required on create
`status`	string	`used`, `free`, `reserved`, `dhcp`, `offline` or `deprecated`. Default `used`
`hostname`	string	Stored in lower case
`mac`	string	Any common notation, stored as `aa:bb:cc:dd:ee:ff`
`device`, `device_type`	string	Device and device type
`room`, `department`, `site`, `owner`	string	Location and responsibility
`description`	string	Free text
`tags`	array	For example `["server", "production"]`
`custom`	object	Custom fields, for example `{"rack": "A12"}`
`subnet_id`	uuid	Set automatically to the most specific subnet
`source`, `last_seen_at`	–	Source (manual, import, agent, scan, api) and last seen
`created_at`, `updated_at`	time	ISO 8601

Examples

Create an address

curl -X POST https://ipmanager.no/api/v1/addresses \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"10.20.3.41","hostname":"pr-b215","status":"used","room":"B2.15","tags":["printer"]}'

Change an address

curl -X PATCH https://ipmanager.no/api/v1/addresses/{id} \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"deprecated","description":"Replaced in week 42"}'

Create a subnet

curl -X POST https://ipmanager.no/api/v1/subnets \
  -H "Authorization: Bearer $IPM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cidr":"10.20.4.0/24","name":"Students building C","vlan":31,"gateway":"10.20.4.1"}'

Next free IP

curl -H "Authorization: Bearer $IPM_TOKEN" \
  https://ipmanager.no/api/v1/subnets/{id}/next-free

Search with filters

curl -G https://ipmanager.no/api/v1/search \
  -H "Authorization: Bearer $IPM_TOKEN" \
  --data-urlencode 'q=status:free in:10.20.0.0/16'

Agent report

Agents and collectors use POST /agent/report with a key that has the agent scope. An agent reports its own interfaces:

From an agent

{
  "hostname": "srv01",
  "os": "Linux",
  "interfaces": [
    { "name": "eth0", "ip": "10.0.0.5", "mac": "00:11:22:33:44:55" }
  ]
}

From a collector

{
  "source": "scan",
  "hosts": [
    { "ip": "10.0.0.7", "hostname": "printer-2", "mac": "aa:bb:cc:dd:ee:ff" }
  ]
}

Response

{ "created": 1, "updated": 0, "unchanged": 3, "limited": 0, "errors": [] }

DNS check

The collector first fetches what to check, then reports the result. See auto-discovery.

Fetch addresses to check

curl -G https://ipmanager.no/api/v1/agent/dns/targets \
  -H "Authorization: Bearer $IPM_TOKEN" \
  --data-urlencode 'cidr=10.20.0.0/16'

{ "suffix": "corp.local", "targets": [ { "ip": "10.20.0.11", "hostname": "file01" } ] }

Report the result

POST /api/v1/agent/dns/report
{
  "resolver": "10.20.0.2",
  "results": [
    { "ip": "10.20.0.11", "ptr": ["file01.corp.local"], "forward": ["10.20.0.11"], "forward_checked": true }
  ]
}

{ "checked": 1, "ok": 1, "problems": 0, "unknown": 0 }

Conflicts

GET /conflicts lists the organisation's conflicts, such as duplicate IPs, mismatched or moved MACs and DNS mismatches, with severity (critical, warning, info). POST /conflicts/{id} is used to acknowledge or resolve a conflict. Every change is recorded in the audit log.

Errors

Errors are returned with an HTTP status code and a JSON object: {"error": "code", "detail": "…"}.

Status	Typical codes	Meaning
400 / 422	`invalid_ip`, `invalid_cidr`, `invalid_mac`, `invalid_status`, `invalid_vlan`, `gateway_outside`	Invalid data in the request
401	`unauthorized`, `invalid_token`	Missing or invalid key
403	`insufficient_scope`, `forbidden`, `ip_limit_reached`	The key lacks access, or the address limit has been reached
404	`not_found`	Does not exist in your organisation
409	`duplicate_ip`, `duplicate_subnet`	The address or subnet already exists