API Reference

Send a passwordless login link to the given email address. If the user doesn't exist yet, an account and organization are created when the link is verified.

{
  "email": "[email protected]"
}

{
  "message": "magic link sent"
}

Verify the magic link token from the email. Sets a session cookie on success and redirects to the app. Creates a new user and organization on first login.

{
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "John Smith"
  },
  "organization": {
    "id": "org_xyz789",
    "name": "John Smith's Org"
  }
}

Destroys the current session. No request body required.

204 No Content

Returns the authenticated user and their organization. Requires auth.

{
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "John Smith"
  },
  "organization": {
    "id": "org_xyz789",
    "name": "John Smith's Org",
    "plan": "free"
  }
}

Returns all folders for the authenticated organization.

[
  {
    "id": "sec_001",
    "name": "Production",
    "description": "Production network ranges",
    "sort_order": 0,
    "created_at": "2026-03-01T12:00:00Z"
  }
]

Create a new folder.

{
  "name": "Production",
  "description": "Production network ranges",
  "sort_order": 0
}

Only name is required. description and sort_order are optional.

{
  "id": "sec_001",
  "name": "Production",
  "description": "Production network ranges",
  "sort_order": 0,
  "created_at": "2026-03-01T12:00:00Z"
}

Returns a single folder by ID.

{
  "id": "sec_001",
  "name": "Production",
  "description": "Production network ranges",
  "sort_order": 0,
  "created_at": "2026-03-01T12:00:00Z"
}

Update a folder. All fields are optional — only provided fields are changed.

{
  "name": "Prod (US-East)",
  "description": "US East production ranges",
  "sort_order": 1
}

Returns the updated folder object.

Delete a folder.

204 No Content

List subnets, optionally filtered by folder. Includes utilization statistics.

• section_id — filter by folder (optional)

[
  {
    "id": "sub_001",
    "network": "10.0.0.0/16",
    "name": "Core network",
    "description": "Main production range",
    "section_id": "sec_001",
    "vrf_id": null,
    "gateway": "10.0.0.1",
    "is_pool": false,
    "utilization": 0.12,
    "created_at": "2026-03-01T12:00:00Z"
  }
]

Create a new subnet. The parent is auto-detected based on CIDR containment. Overlapping ranges are rejected.

{
  "network": "10.0.1.0/24",
  "name": "Web servers",
  "description": "Web tier subnet",
  "section_id": "sec_001",
  "vrf_id": null,
  "gateway": "10.0.1.1",
  "is_pool": false
}

Only network is required. All other fields are optional.

Returns the created subnet object.

Returns a subnet and its child subnets.

{
  "id": "sub_001",
  "network": "10.0.0.0/16",
  "name": "Core network",
  "children": [
    {
      "id": "sub_002",
      "network": "10.0.1.0/24",
      "name": "Web servers"
    }
  ]
}

Update subnet metadata. All fields are optional.

{
  "name": "Web servers (prod)",
  "description": "Production web tier",
  "section_id": "sec_001",
  "is_pool": true,
  "gateway": "10.0.1.1"
}

Returns the updated subnet object.

Delete a subnet. Cascades to all child subnets and addresses.

204 No Content

Split a subnet into equal parts. The number of parts must be a power of 2 (2, 4, 8, etc.).

{
  "parts": 4
}

[
  { "id": "sub_010", "network": "10.0.0.0/26" },
  { "id": "sub_011", "network": "10.0.0.64/26" },
  { "id": "sub_012", "network": "10.0.0.128/26" },
  { "id": "sub_013", "network": "10.0.0.192/26" }
]

Returns utilization statistics for a subnet.

{
  "used": 42,
  "total": 254,
  "utilization": 0.165
}

Returns the first available IP address in the subnet. Returns null if the subnet is full.

{
  "ip": "10.0.1.5"
}

{
  "ip": null
}

List all IP addresses in a subnet.

[
  {
    "id": "addr_001",
    "ip": "10.0.1.10",
    "hostname": "web-01.prod",
    "mac_address": "00:1A:2B:3C:4D:5E",
    "description": "Primary web server",
    "status": "active",
    "owner": "platform-team",
    "created_at": "2026-03-01T12:00:00Z"
  }
]

Assign an IP address within a subnet. The IP is validated to be within the subnet's CIDR range.

{
  "ip": "10.0.1.10",
  "hostname": "web-01.prod",
  "mac_address": "00:1A:2B:3C:4D:5E",
  "description": "Primary web server",
  "status": "active",
  "owner": "platform-team"
}

Only ip is required. All other fields are optional.

Returns the created address object.

Returns a single address by ID.

{
  "id": "addr_001",
  "ip": "10.0.1.10",
  "hostname": "web-01.prod",
  "mac_address": "00:1A:2B:3C:4D:5E",
  "description": "Primary web server",
  "status": "active",
  "owner": "platform-team",
  "subnet_id": "sub_002",
  "created_at": "2026-03-01T12:00:00Z",
  "updated_at": "2026-03-10T08:30:00Z"
}

Update address metadata. All fields are optional.

{
  "hostname": "web-01a.prod",
  "mac_address": "00:1A:2B:3C:4D:5F",
  "description": "Migrated web server",
  "status": "active",
  "owner": "platform-team"
}

Returns the updated address object.

Remove an IP address assignment.

204 No Content

List all webhook subscriptions. The signing secret is never included in list responses.

[
  {
    "id": "wh_001",
    "url": "https://example.com/webhooks/ipcraft",
    "description": "CMDB sync",
    "event_types": ["subnet.created", "subnet.deleted"],
    "is_active": true,
    "failure_count": 0,
    "created_at": "2026-03-21T16:00:00Z"
  }
]

Create a new webhook subscription. Returns the signing secret — store it securely, it is only shown once.

{
  "url": "https://example.com/webhooks/ipcraft",
  "description": "CMDB sync",
  "event_types": ["subnet.created", "subnet.deleted"]
}

Leave event_types empty ([]) to receive all event types.

{
  "id": "a1b2c3d4-...",
  "url": "https://example.com/webhooks/ipcraft",
  "secret": "whsec_a1b2c3d4e5f6...",
  "event_types": ["subnet.created", "subnet.deleted"],
  "is_active": true
}

Get a single webhook subscription. The signing secret is not included.

Update a webhook's URL, description, event types, or active status. Re-enabling a disabled webhook resets the failure count.

{
  "url": "https://new-endpoint.example.com/hook",
  "event_types": ["address.created"],
  "is_active": true
}

200 OK

Permanently delete a webhook subscription and all its delivery history.

204 No Content

List recent delivery attempts for a webhook. Supports ?limit= and ?offset= query parameters (max 200).

[
  {
    "id": "del_001",
    "event_type": "subnet.created",
    "response_status": 200,
    "duration_ms": 142,
    "attempt": 1,
    "delivered_at": "2026-03-21T16:30:00Z"
  }
]

Send a test ping event to the webhook endpoint. Returns the delivery result so you can verify connectivity.

{
  "event_type": "ping",
  "response_status": 200,
  "duration_ms": 95,
  "attempt": 1
}

Returns 502 if the endpoint is unreachable or returns a non-2xx status.

Generate a new signing secret for the webhook. The old secret stops working immediately.

{
  "secret": "whsec_new_secret_value..."
}

List all API keys. Only the key prefix is shown — the full key is never returned after creation.

[
  {
    "id": "key_001",
    "name": "Ansible automation",
    "key_prefix": "ipc_a1b2c3",
    "created_at": "2026-03-01T12:00:00Z",
    "last_used_at": "2026-03-14T09:15:00Z"
  }
]

Generate a new API key. The full key is only returned in this response — store it securely.

{
  "name": "Ansible automation"
}

{
  "id": "key_001",
  "name": "Ansible automation",
  "key": "ipc_a1b2c3d4e5f6g7h8i9j0...",
  "key_prefix": "ipc_a1b2c3"
}

Revoke an API key. Any requests using this key will immediately start returning 401.

204 No Content

Returns current plan details, usage, and limits.

{
  "plan": "free",
  "usage": {
    "sections": 1,
    "subnets": 3,
    "addresses": 42
  },
  "limits": {
    "sections": 1,
    "subnets": 5,
    "addresses": 100
  }
}

Creates a Stripe Checkout session for upgrading to Pro. Redirect the user to the returned URL.

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Creates a Stripe Customer Portal session for managing billing, invoices, and cancellation.

{
  "url": "https://billing.stripe.com/p/session/..."
}

Search by IP address, hostname, network CIDR, description, or any other field. Returns matching subnets and addresses.

• q — search query (required)

{
  "subnets": [
    {
      "id": "sub_002",
      "network": "10.0.1.0/24",
      "name": "Web servers"
    }
  ],
  "addresses": [
    {
      "id": "addr_001",
      "ip": "10.0.1.10",
      "hostname": "web-01.prod"
    }
  ]
}

Returns a paginated list of activity entries.

• limit — number of entries to return (optional)
• offset — pagination offset (optional)

[
  {
    "id": "act_001",
    "action": "subnet.created",
    "resource_type": "subnet",
    "resource_id": "sub_002",
    "user_id": "usr_abc123",
    "details": "Created subnet 10.0.1.0/24",
    "created_at": "2026-03-14T10:30:00Z"
  }
]

Perform a DNS lookup from 3 independent resolvers (Google, Cloudflare, Quad9).

• domain — domain name to resolve (required)
• type — record type: A, AAAA, MX, TXT, NS, CNAME, SOA (required)

{
  "domain": "example.com",
  "type": "A",
  "resolvers": {
    "google": ["93.184.216.34"],
    "cloudflare": ["93.184.216.34"],
    "quad9": ["93.184.216.34"]
  }
}

Perform a reverse DNS lookup for an IP address.

• ip — IP address (required)

{
  "ip": "8.8.8.8",
  "hostnames": ["dns.google"]
}

Perform a WHOIS lookup for a domain or IP address.

• query — domain name or IP address (required)

{
  "query": "example.com",
  "raw": "Domain Name: EXAMPLE.COM\nRegistry Domain ID: ..."
}

TCP connectivity check to a host.

• host — hostname or IP address (required)

{
  "host": "example.com",
  "reachable": true,
  "latency_ms": 24
}

Scan 19 common ports on a host (FTP, SSH, HTTP, HTTPS, DNS, SMTP, etc.).

• host — hostname or IP address (required)

{
  "host": "example.com",
  "ports": [
    { "port": 80, "service": "http", "open": true },
    { "port": 443, "service": "https", "open": true },
    { "port": 22, "service": "ssh", "open": false }
  ]
}

Returns the client's public IP address and related information.

{
  "ip": "203.0.113.42"
}

Returns the HTTP headers sent by the client.

{
  "headers": {
    "User-Agent": "curl/8.1.0",
    "Accept": "*/*",
    "Host": "api.ipcraft.io"
  }
}