API REST para direcciones IP y subredes: documentación

Lo básico

URL base: https://ipmanager.no/api/v1
Todas las peticiones y respuestas son JSON (Content-Type: application/json).
Autenticación con una clave API en la cabecera Authorization: Bearer ipm_….
Todos los cambios hechos por la API quedan en el registro de auditoría, con el nombre de la clave como autor.

Claves API y permisos

Un administrador crea las claves en Autodetección y API. La clave se muestra una sola vez. Cada clave tiene un permiso:

Permiso	Puede
`read`	Leer direcciones, subredes y búsquedas (GET)
`write`	Todo lo de `read`, además de crear, modificar y eliminar
`agent`	Solo enviar informes de agentes (`POST /agent/report`)

Ejemplo

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

Endpoints

Método	Ruta	Descripción
GET	`/addresses`	Lista direcciones. Parámetros: `q`, `status`, `subnet`, `limit`, `offset`
POST	`/addresses`	Crea una dirección
GET	`/addresses/{id}`	Obtiene una dirección
PATCH	`/addresses/{id}`	Modifica campos de una dirección
DELETE	`/addresses/{id}`	Elimina una dirección
GET	`/subnets`	Lista subredes
POST	`/subnets`	Crea una subred
GET	`/subnets/{id}`	Obtiene una subred
PATCH	`/subnets/{id}`	Modifica una subred
DELETE	`/subnets/{id}`	Elimina una subred (las direcciones se conservan)
GET	`/subnets/{id}/next-free`	Siguiente dirección IPv4 libre de la subred
GET	`/search?q=`	La misma búsqueda que en la interfaz, con filtros
POST	`/agent/report`	Informe de un agente o recolector
GET	`/agent/dns/targets?cidr=`	Direcciones registradas con hostname para comprobar el DNS (permiso agent o read)
POST	`/agent/dns/report`	Resultados de la comprobación DNS del recolector
GET	`/conflicts`	Lista los conflictos
POST	`/conflicts/{id}`	Gestiona un conflicto (marcar como visto o resolver)

Campos de dirección

Campo	Tipo	Nota
`ip`	texto	IPv4 o IPv6. Obligatorio al crear
`status`	texto	`used`, `free`, `reserved`, `dhcp`, `offline` o `deprecated`. Por defecto `used`
`hostname`	texto	Se guarda en minúsculas
`mac`	texto	Cualquier notación habitual, se guarda como `aa:bb:cc:dd:ee:ff`
`device`, `device_type`	texto	Equipo y tipo de equipo
`room`, `department`, `site`, `owner`	texto	Ubicación y responsabilidad
`description`	texto	Texto libre
`tags`	lista	Por ejemplo `["servidor", "produccion"]`
`custom`	objeto	Campos propios, por ejemplo `{"rack": "A12"}`
`subnet_id`	uuid	Se asigna automáticamente a la subred más específica
`source`, `last_seen_at`	–	Origen (manual, import, agent, scan, api) y visto por última vez
`created_at`, `updated_at`	fecha	ISO 8601

Ejemplos

Crear una dirección

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":["impresora"]}'

Modificar una dirección

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

Crear una subred

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":"Alumnos edificio C","vlan":31,"gateway":"10.20.4.1"}'

Siguiente IP libre

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

Búsqueda con filtros

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

Informe de agente

Agentes y recolectores usan POST /agent/report con una clave con permiso agent. Un agente informa de sus propias interfaces:

Desde un agente

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

Desde un recolector

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

Respuesta

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

Comprobación DNS

El recolector obtiene primero qué debe comprobar y después comunica el resultado. Consulta la autodetección.

Obtener las direcciones que comprobar

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

{ "suffix": "empresa.local", "targets": [ { "ip": "10.20.0.11", "hostname": "archivos01" } ] }

Comunicar el resultado

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

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

Conflictos

GET /conflicts lista los conflictos de la organización, como IP duplicadas, MAC distintas o movidas y desajustes de DNS, con gravedad (critical, warning, info). POST /conflicts/{id} sirve para marcar como visto o resolver un conflicto. Todos los cambios quedan en el registro de auditoría.

Errores

Los errores se devuelven con un código de estado HTTP y un objeto JSON: {"error": "código", "detail": "…"}.

Estado	Códigos habituales	Significado
400 / 422	`invalid_ip`, `invalid_cidr`, `invalid_mac`, `invalid_status`, `invalid_vlan`, `gateway_outside`	Datos no válidos en la petición
401	`unauthorized`, `invalid_token`	Falta la clave o no es válida
403	`insufficient_scope`, `forbidden`, `ip_limit_reached`	La clave no tiene permiso o se ha alcanzado el límite de direcciones
404	`not_found`	No existe en tu organización
409	`duplicate_ip`, `duplicate_subnet`	La dirección o la subred ya existe