{% include 'header.html' %}

API Documentation

Authentication

All API requests require authentication using an API key. You can provide the API key in one of three ways:

  • Header: X-API-Key: your_api_key
  • Authorization Header: Authorization: Bearer your_api_key
  • Query Parameter: ?api_key=your_api_key

Base URL: /api/v1

Your API Key

Interactive Testing

Test GET endpoints directly in your browser. Other methods are documented below.

GET /api/v1/devices

List all devices

GET /api/v1/devices/{id}

Get device by ID

GET /api/v1/devices/by-tag/{tag}

Filter devices by tag

GET /api/v1/tags

List all tags

Devices

Read Operations

  • GET /api/v1/devices - List all devices
  • GET /api/v1/devices/{id} - Get device details
  • GET /api/v1/devices/by-tag/{tag} - Get devices by tag

Write Operations

  • POST /api/v1/devices - Create device
  • PUT /api/v1/devices/{id} - Update device
  • DELETE /api/v1/devices/{id} - Delete device
  • POST /api/v1/devices/{id}/ips - Add IP to device
  • DELETE /api/v1/devices/{id}/ips/{ip_id} - Remove IP

Subnets

Read Operations

  • GET /api/v1/subnets - List all subnets
  • GET /api/v1/subnets/{id} - Get subnet details

Write Operations

  • POST /api/v1/subnets - Create subnet
  • PUT /api/v1/subnets/{id} - Update subnet
  • DELETE /api/v1/subnets/{id} - Delete subnet

Racks

Read Operations

  • GET /api/v1/racks - List all racks
  • GET /api/v1/racks/{id} - Get rack details

Write Operations

  • POST /api/v1/racks - Create rack
  • DELETE /api/v1/racks/{id} - Delete rack
  • POST /api/v1/racks/{id}/devices - Add device to rack
  • DELETE /api/v1/racks/{id}/devices/{device_id} - Remove device

Tags

Read Operations

  • GET /api/v1/tags - List all tags
  • GET /api/v1/tags?format=simple - List tags in simple format
  • GET /api/v1/tags/{id} - Get tag details
  • GET /api/v1/devices/{id}/tags - Get device tags

Write Operations

  • POST /api/v1/tags - Create tag
  • PUT /api/v1/tags/{id} - Update tag
  • DELETE /api/v1/tags/{id} - Delete tag
  • POST /api/v1/devices/{id}/tags - Assign tag to device
  • DELETE /api/v1/devices/{id}/tags/{tag_id} - Remove tag

Additional Endpoints

System Information

  • GET /api/v1/info - System information
  • GET /api/v1/device-types - List device types

DHCP Management

  • GET /api/v1/subnets/{id}/dhcp - Get DHCP config
  • POST /api/v1/subnets/{id}/dhcp - Generate DHCP config

User & Role Management

  • GET /api/v1/users - List users
  • GET /api/v1/roles - List roles

Audit Log

  • GET /api/v1/audit - List audit entries

Supports filtering with query parameters

Response Format & Permissions

Success Responses

All API responses are in JSON format. Successful requests return:

  • 200 OK - Request successful
  • 201 Created - Resource created
  • 204 No Content - Success with no response body

Error Responses

Error responses include descriptive messages:

  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found

Permissions

API endpoints respect the same role-based permissions as the web interface. Users can only perform actions that their role allows. If a user lacks the required permission, the API will return a 403 Forbidden error with details about the missing permission.