Skip to content

REST API & OpenAPI reference

Danbyte exposes its full IPAM/DCIM data model as a REST API under /api/, with an interactive, self-describing OpenAPI 3 reference built in.

Where it lives

URL What it is
/api/ Redirects to the docs below.
/api/docs/ Swagger UI - interactive reference with "try it out" against your live tenant.
/api/docs/redoc/ ReDoc - a clean, readable reference view.
/api/schema/ The raw OpenAPI 3 schema (YAML) - the machine-readable source of truth.

All four require authentication (session cookie or an API token), consistent with the rest of the API's default-closed posture.

The reference is generated by drf-spectacular from the actual viewsets, serializers, and view annotations, so it never drifts from the running code. Its assets are bundled locally (drf-spectacular-sidecar), so the interactive docs work on airgapped installs with no CDN access.

Authenticating

  • API token - create one under Settings → Preferences → API tokens, then send it as a header: Authorization: Token <key>. In Swagger UI, click Authorize and paste the token. Every token is scoped to exactly one tenant and acts only there: it ignores the session's tenant switch and the user's home tenant. When the token's user loses that tenant (removed from it, or the tenant is deactivated - superusers included), every request with the token is refused with 401 This API token's tenant is no longer available to its user.; it never moves to another tenant. Restoring the access makes the token work again, on the same tenant. Tick Read only when creating one and every write is refused with 403 no matter what the owning user may do - the right choice for reporting, inventory pulls, and AI assistants. Tokens are created and revoked from a signed-in session only: a request authenticated with a token can't create, list or revoke tokens. One user holds at most 25 unexpired tokens (API_MAX_TOKENS_PER_USER, see Settings); creating another answers 400 until one is revoked or expires.
  • Session - when you are logged into the SPA, the same session cookie authorizes API calls from the browser.

Passwords are not an API-token concern. The sign-in and password endpoints below are plain JSON views for the browser: they take the session cookie and a CSRF token, are not in the OpenAPI schema, and never accept a token.

Endpoint Who Body Answer
POST /api/auth/password/change/ Signed-in session with a local password. A request with an Authorization header is refused with 403. current_password, new_password 200 {ok, sessions_ended}; 400 with current_password or new_password messages, or detail for a directory/SSO account; 429 when the sign-in lockout is reached.
POST /api/auth/password-reset/ Anyone, when reset by email is on; 404 otherwise. identifier (username or email) Always the same 200 {detail}; 429 past the sign-in limits.
POST /api/auth/password-reset/confirm/ Anyone with a link from the mail; 404 when reset is off. uid, token, password 200 {ok}; 400 detail for a bad or used link, password messages for a weak one. Ends every session and signs nobody in.

GET /api/me/ says whether the sign-in page offers the reset (password_reset_available, anonymous answer) and where the signed-in account's password lives (password_source: local, ldap, sso or none).

Every request is scoped to your active tenant and enforced by RBAC - the schema describes the shape of each endpoint, but access is always checked server-side.

Grouping

Operations are grouped by domain object (Prefixes, IP addresses, Devices, VLANs, Circuits, Monitoring, …) so you can find an endpoint by the thing it acts on. The CRUD object endpoints come from the router-registered viewsets; the remaining operational endpoints (monitoring, compliance, import/export, system, settings, …) are annotated with @extend_schema so they appear with proper summaries, request bodies, and responses.

Pagination

Every list endpoint pages its answer:

{
  "count": 41600,
  "next": "https://danbyte.example/api/interfaces/?page=2",
  "previous": null,
  "results": []
}
  • page_size - rows per page. Without it a list answers 100 rows (the deployment's API_PAGE_SIZE, see Settings). Ask for up to 2,000 with ?page_size= (the deployment's API_MAX_PAGE_SIZE); a larger number is cut to the cap, and a value that is not a positive number is ignored. A cut page still carries next, so a script that follows it reads every row whatever the cap.
  • page - which page, from 1. A page past the end answers 404.
  • limit / offset are not read. ?limit=500 answers the default 100 rows, with a next to the rest; ask with page_size instead. /api/installed-software/ is one of these lists: 100 rows by default, at most 2,000 with page_size. A client that reads only the first page of any list misses rows, so follow next.
  • count - every matching row, not only the rows on this page.
  • next / previous - full links to the neighbouring pages, with your filters and page_size kept, or null at either end. To read a whole list, follow next until it is null.
# Every interface, 1,000 at a time
url="https://danbyte.example/api/interfaces/?page_size=1000"
while [ "$url" != "null" ]; do
  page=$(curl -s -H "Authorization: Token $TOKEN" "$url")
  echo "$page" | jq -c '.results[]'
  url=$(echo "$page" | jq -r '.next')
done

Ask for the rows you need rather than the cap, and follow next: a big page takes seconds to build and holds a server worker while it does. A few 10,000-row pages used to hold every worker at once, so the cap is 2,000.

Large pages are limited per user. A request whose page_size is above 1,000 (API_LARGE_PAGE_THRESHOLD) is a large page, and one user may have 2 in flight at a time (API_LARGE_PAGE_CONCURRENCY), counted across their session and every API token they own. The next one answers 429 Too Many Requests with a Retry-After header in seconds; wait that long and send it again. Pages of 1,000 rows or fewer are never held back, so a script that pages at 1,000, as the loop above does, never meets the limit, and neither does the web app. The script SDK and the web app retry a 429 after its Retry-After on their own.

To serve bigger pages, an administrator sets API_MAX_PAGE_SIZE (and, to move or loosen the limit, API_LARGE_PAGE_THRESHOLD and API_LARGE_PAGE_CONCURRENCY) in the service environment and restarts the web service; see Settings. Raising them trades other users' response times for one client's fewer round trips.

A few lists page differently. Tags, statuses, IP roles and zones answer 500 rows a page whatever page_size says; follow next for more. The monitoring check and history lists and the MAC lists answer {count, page, page_size, num_pages, results} with their own default and cap, as their schema entries say. The script SDK's db.list() follows next for you (Scripts SDK).

Sorting and facets on the big lists

The device (/api/devices/), interface (/api/interfaces/), cable (/api/cables/) and virtual machine (/api/virtual-machines/) lists sort, filter and count on the server - the web app pages them this way. Every parameter here is optional, and a request without them answers as before.

Parameter What it does
ordering=<column> / -<column> Sort by one column of the list's table (name, status, site, updated…), a catalog field (serial_number, site.region) or a custom field (custom_fields.<key>). Names sort in natural order; empty values sort last both ways. A column the list cannot sort by is a 400.
f_<facet>=a,b Rows in any of the listed buckets of one facet (f_status=<id>,<id>, f_tags=core, f_manufacturer=Acme). __none__ is the empty bucket (the interface list's status uses none, which reads as Active). A comma inside a value is written \,. Facets combine with AND. An unknown facet is a 400.
f_<facet>=min..max A range facet (the device list's f_ips=2..10); either side may be left out.
expr=<json> The Advanced filter as its JSON tree ({"kind": "cmp", "field": "status.name", "cmp": "=", "value": "active"}, groups as {"kind": "group", "op": "and", "terms": [...]}). Strings compare without case. A field the list does not have is a 400.
view=table The slim row: only what the web app's table reads. The default row stays the full one.
include=a,b With view=table: add these fields of the full row.

GET <list>/facets/ takes the same filters and answers the rail: {"facets": {"<facet>": [{"value", "label", "count", "color", "text_color"}]}, "sortable": [...]}. Each facet counts the rows every other filter leaves, so its own selection does not hide its other buckets; at most 500 buckets per facet, the selected ones always. GET <list>/table-ids/ answers every matching id in list order ({"count", "truncated", "results"}, at most 50,000). Both are scoped exactly like the list: tenant, permissions and site scope.

The facets per list:

  • Devices: status, role, platform, eol, coverage, type, manufacturer (by name), cooling, site, software_version, software_target, ips (range), tags.
  • Interfaces: device, status, tags.
  • Cables: type, status, tags.
  • Virtual machines: cluster and group (by name), status, power, synced_from, site, role, platform, eol, software_version, software_target, tags.
# The second page of planned devices at one site, by site then name
curl -s -H "Authorization: Token $TOKEN" \
  "https://danbyte.example/api/devices/?view=table&page=2&page_size=50&ordering=site&f_status=$PLANNED&f_site=$SITE"

Unknown query parameters

A list endpoint names every query parameter it did not use. Before 0.19.1 it ignored them silently: GET /api/ips/?device_id=<id> answered every address in the tenant, because the filter is called device. From 0.20 such a request is a 400 (strict mode, below). With strict mode off (?strict=0, or API_STRICT_QUERY_PARAMS=0) the response carries

X-Danbyte-Unknown-Params: device_id
Warning: 299 - "Unknown query parameters ignored: device_id"

and the rows are the same as without the parameter. Names are percent-encoded (%0D%0A for a CR/LF). The headers stay small whatever the request holds: each name is cut at 64 bytes, ending in an encoded … (%E2%80%A6), each header value stays within 512 bytes and lists at most 20 names, and the rest are counted as +N more. Strict mode's 400 lists every name in full. A list knows the parameters its filters, sorting, facets, search and paging read on that request, plus page, page_size, format, strict and the _ cache-buster on every list. A parameter that only counts with another one (with_vc without picker=1, include without view=table) is unknown when it was ignored. Details, writes and actions (facets/, table-ids/, report/) are not checked, and neither is an error response.

Strict mode, the default from 0.20, turns an unknown parameter into a 400:

{
  "detail": "Unknown query parameter: device_id (did you mean device?). This list takes: device, format, page, page_size, search, …. Send strict=0 to ignore unknown parameters.",
  "unknown": ["device_id"],
  "hint": {"device_id": "device"},
  "allowed": ["device", "format", "page", "page_size", "search", "strict", "…"]
}

hint names the parameter you probably meant: <x> for <x>_id when the list takes <x>, else the closest name the list knows. allowed is what the list read on that request, so a parameter that only counts with another one (include without view=table) is not in it. ?strict=0 (or X-Danbyte-Strict: 0) turns strict mode off for one request: the list answers as if the parameter were absent and names it in the headers above. API_STRICT_QUERY_PARAMS=0 (settings) turns it off for the whole install, and ?strict=1 (or X-Danbyte-Strict: 1) then turns it on for one request.

Changed in 0.20: the setting was off in 0.19, so a client that sent a parameter a list ignores got the whole list and now gets a 400. Fix the parameter (the hint usually names it), send strict=0, or set API_STRICT_QUERY_PARAMS=0 until your clients are fixed. The web app's own requests are checked against the lists in the test suite (api/tests_frontend_query_params.py).

Some lists also take <x>_id as an alias of an id filter <x>. Sending both with different values is a 400.

List Aliases
/api/ips/ device_id, virtual_machine_id, assigned_interface_id, assigned_vm_id
/api/interfaces/, /api/cables/, /api/front-ports/, /api/rear-ports/, /api/modules/, /api/tunnels/, /api/tunnel-terminations/, /api/port-reservations/, /api/virtual-machines/ (the host), /api/deploy-runs/, /api/deploy-pipeline-runs/, device config snapshots, SSH host keys, device credentials, connect protocols device_id
/api/mac-addresses/, routing Ethernet segments, PRTG sensors device_id, interface_id
IS-IS and EIGRP interfaces interface_id
/api/virtual-disks/, /api/vm-interfaces/, virtualization networks and changes vm_id, virtual_machine_id
Oxidized node links, PRTG device links, application groups device_id, virtual_machine_id

Filtering by tag

The device, IP address (/api/ips/) and prefix (/api/prefixes/) lists take ?tag=<slug> and ?tag_id=<id>. Each is repeatable, and a row must carry every tag named: ?tag=pod-1&tag=anycast-gw answers the rows tagged with both. A slug no row carries answers an empty list; a tag_id that is not a number answers 400.

curl -s -H "Authorization: Token $TOKEN" \
  "https://danbyte.example/api/ips/?tag=anycast-gw&page_size=1000"

Catalog names and slugs

The tenant catalogs - platforms, platform groups, manufacturers, device roles, RIRs, VLAN groups, service templates, location and area types, sensitivity labels, custom-field groups and the other name-and-slug catalogs - take one rule on POST and PATCH:

  • A name another row has, case aside, is refused on create and on a rename, with the error on name. An edit that keeps the name is never refused for it, so rows that already share a name stay editable.
  • Leave out slug and a create takes it from the name; an edit keeps the row's slug unless it renames the row, which takes the new name's.
  • A slug you send that another row has is refused on slug.

Asking the API what it accepts

These endpoints describe the API's own vocabulary so a client never has to hard-code a list that can go stale:

  • GET /api/dcim/choices/ - the option lists behind the long taxonomy dropdowns (interface and cable types, duplex, 802.1Q modes, PoE, connector fibre counts, common speeds), the hardware's airflow directions and cooling_methods, and a rack's cooling_capability. Each option carries value and label, and the grouped taxonomies a group so a UI can render sub-categorised dropdowns.
  • GET /api/editable-fields/ - which fields of a model a field-level write path may set, and what editor each needs. ?model=interface (registry slug or api.interface) returns descriptors:
{"key": "mtu",       "label": "MTU",           "kind": "int",    "nullable": true}
{"key": "type",      "label": "Type",          "kind": "choice", "choices": "interface_types"}
{"key": "status_id", "label": "Status",        "kind": "status", "status_model": "device"}
{"key": "site_id",   "label": "Site",          "kind": "object", "object_model": "site",
                                               "endpoint": "/api/sites/"}

kind names the editor to render; choices/suggestions name a list in /api/dcim/choices/. Omitting ?model= lists the covered models. The response is filtered by the caller's change permission - it describes writes, so a caller who cannot change devices does not see device at all.

The field names come from each viewset's own write allow-list (the same declaration bulk-update enforces); everything else - label, editor kind, option list, nullability - is derived from the model definition, so this endpoint cannot drift from what a write will actually accept.

  • GET /api/list-fields/?path=/api/devices/ - which fields a list's rows carry that can be shown as table columns. path is the list endpoint the table fetches - any routed list, including /api/routing/…, /api/monitoring/… and plugin lists. The answer:
{"path": "/api/devices/", "model": "api.device", "slug": "device", "cf_model": "device",
 "fields": [
   {"key": "asset_tag",   "label": "Asset tag", "kind": "text",   "group": "fields"},
   {"key": "face",        "label": "Face",      "kind": "choice", "group": "fields",
    "options": [{"value": "front", "label": "Front"}, {"value": "rear", "label": "Rear"}]},
   {"key": "airflow",     "label": "Airflow",   "kind": "choice", "group": "fields",
    "choices": "airflow", "setting": "airflow"},
   {"key": "site.region", "label": "Region",    "kind": "object", "group": "related",
    "related": "api.region", "via": "Site"},
   {"key": "config_template", "path": "config_template.resolved", "label": "Config template",
    "kind": "object", "group": "related", "related": "api.exporttemplate"}],
 "custom_fields": [{"key": "owner", "label": "Owner", "type": "text", "choices": [], …}]}

key is a dotted path into a row (path when the value sits deeper); kind is one of text, longtext, ip, number, bool, choice, date, datetime, color, object, objects, tags or auto (render by the value's shape). A choice list /api/dcim/choices/ publishes - the long taxonomies, airflow, cooling - is named by its key in choices instead of inlined as options. related is the app.model an object points at. setting names the device-field switch (Settings → Device fields) that hides the field. custom_fields are the model's visible custom-field definitions.

Everything is derived from the list's own serializer: the catalog never adds data, it describes what the list already returns. Left out are ids and plumbing (id, numid, permissions, raw foreign-key ids), structures (JSON, lists), nested lists of records that have no name, get_<x>_display twins, @detail_only getters and names in the serializer's list_columns_exclude. The request is gated exactly like the list - 403 without view permission on it, 404 for a path that is not a list or a list that is not enabled.

Malformed input

A JSON body must be an object. A string, list, number or null answers 400 with {"non_field_errors": ["Expected a JSON object."]} before the call does anything. A query parameter that should be a number, id or flag and is not either answers 400 naming the parameter ({"limit": ["A whole number is required."]}) or falls back to its default; never a server error. A query parameter carrying a NUL byte (%00) answers 400 on every path.

Error text

An error's detail (or error) is written for the person reading it: a validation message, or what a remote server said when a connection test, import or upgrade fails talking to it - only its first line, without the file paths an operating-system error names. An exception Danbyte did not expect never reaches the response: the server logs it with its traceback (logger danbyte.errors) and the call answers a plain sentence that points there.

Bulk calls

Every bulk-delete/ and bulk-update/ takes a JSON object whose ids is a non-empty list of object ids (some lists take at most 1000 per call). An id that is not one answers 400 with {"ids": "«nope» is not an id."} and touches nothing; a body that is not an object answers as in Malformed input. Ids outside the active tenant or the caller's permissions are left out, as in a list.

More ids than a call takes answer 400 ({"ids": "At most 1000 ids per call."}) and touch nothing. Send them in consecutive calls of at most that many, as the web UI does with a big selection (see Large selections).

A value a field cannot take answers 400 too - {"non_field_errors": [...]} when no serializer named the field - never a server error.

Errors in a nested list (a pipeline's steps, a cabinet's rails, an SLA group's items, a report's sheets) are an object keyed by the position of each item that failed, counting from 0; the items that passed are left out:

{"steps": {"1": {"timeout_minutes": ["Ensure this value is greater than or equal to 1."]}}}

An error about the list as a whole (not a list, empty, too long) stays a list of messages under the field. Changed in 0.20: before, the field held a list with one entry per item sent, {} for those that passed ({"steps": [{}, {"timeout_minutes": [...]}]}). This is Django REST framework's own format from 3.18 (LIST_SERIALIZER_ERRORS_AS_DICT), and the only one from 3.20. A cabinet's own rail checks (on the plate, no overlap, room for its devices) answer rails and rail_templates in the same keyed form. The per-row answers of a whole call (a cable bulk-create/'s cables, a cabinet arrange's placements) keep their list form.

bulk-update/ checks each value in fields exactly as a PATCH of that type checks it: choices, text length, number range, and that a related id is in the active tenant (and behind the site fence). Where the type has rules that tie a field to the rest of the object - an interface's bundle settings need a LAG, a splitter rear port has one position - each selected row is checked as its own PATCH would be, and the error names the row ({"lag_protocol": ["eth0: Only an interface of type LAG has bundle settings."]}). Text is trimmed and booleans read as a PATCH reads them. One bad value refuses the whole call: nothing is written.

A list that declares its bulk-edit fields (the routing lists, platforms and virtual machines) also answers GET <list>/bulk-edit-fields/ with {"fields": [...], "tags": true, "custom_fields": null}: the keys its bulk-update/ accepts, each described as /api/editable-fields/ describes a field (an object field carries the endpoint to pick it from). Its bulk-update/ answers 409 when the values would make two rows the same (a static route's path). The routing lists' bulk-delete/ keeps a row that other records still reference, with the reason in skipped - see Routing; platforms keep one a device, virtual machine or device profile uses - see Platforms.

Where custom_fields names a model ("virtualmachine"), bulk-update/ also takes fields.custom_fields: an object of custom-field keys and their new values, checked as the field's type checks them. Only the keys sent change; null (or "", []) clears one. A key that is not one of that model's custom fields, or clearing a required one, answers 400 under custom_fields - see Virtual machines.

The lists that preview a delete (circuits, wireless, virtual chassis, power panels and feeds, platforms) answer bulk-delete/ with {deleted, deleted_ids, skipped: [{id, name, reason}], impact: [{label, count}], released: [{label, count}], notes: [{id, name, label, detail}], dry_run}. skipped are the rows kept because something still uses them; impact counts everything else the delete removes, including a cable left with no port on one end; notes name rows that go but are worth a look first, such as a power feed still cabled to a device.

Renumbering a prefix

POST /api/prefixes/<id>/renumber/ with {"new_prefix": "2001:db8:1230::/60", "dry_run": true} moves the prefix, everything inside it and the references to it to the new network (see Prefixes). dry_run defaults to true; false applies it in one transaction. It needs change on the prefix.

Both answer:

{
  "prefix": {"id": "…", "cidr": "2001:db8:abc0::/60"},
  "new_prefix": "2001:db8:1230::/60",
  "dry_run": true, "applied": false,
  "counts": [{"kind": "ipaddress", "label": "IP addresses", "count": 12}],
  "total": 31, "truncated": false,
  "changes": [{"kind": "ipaddress", "id": "…", "label": "gw.v10",
               "field": "ip_address", "old": "2001:db8:abc0:1::1",
               "new": "2001:db8:1230:1::1"}],
  "unchanged_counts": [{"kind": "dhcpscope", "label": "DHCP scopes", "count": 1}],
  "unchanged_total": 1,
  "unchanged": [{"kind": "dhcpscope", "id": "…", "label": "…", "value": "…",
                 "reason": "On a DHCP server: change it there, the next sync follows."}],
  "linked": [{"kind": "fhrpgroup", "label": "Fhrp groups", "count": 2}],
  "hidden_total": 0
}

changes has one row per changed field and unchanged one per reference; each list holds at most 2,000 rows, with the full figure in total and unchanged_total. A different family or length, a host address, the current network, a vrf_id, or a prefix, address or range already in the new network answers 400 under new_prefix. A kind the caller may not change, or a row outside their sites, answers 403 naming it - for the preview too. Nothing is written by a refusal.

Every row in changes, unchanged and linked is one the caller may view, by the same rule as that object's own API (an ARP sighting through its device or VM and macaddress view, a BMC endpoint or SNMP binding through its target). The others are only counted, all kinds together, in hidden_total: no address, label or id. A row the renumber would rewrite that the caller can't view refuses it with 403 ("N objects you can't view"), and a conflicting prefix, address or range they can't view is not named in the 400. Rows counted in hidden_total on a successful renumber are references left unchanged, which the apply answer counts too.

Free space in prefixes

Four calls find and fill the free space inside prefixes (see Prefixes). Free space is computed against every prefix of the tenant and VRF, so a block offered is really free; blocks are offered only inside prefixes the caller may view, and space a prefix the caller may not view takes is not offered, named or counted. IPv6 space under a /64 or shorter is offered in whole /64s unless a longer length is asked for.

The list. GET /api/prefixes/?free=1 adds, beside results, the free blocks of the parents on that page (containers and prefixes with children):

{
  "count": 4, "next": null, "previous": null, "results": [ … ],
  "free": [{"kind": "free", "cidr": "10.20.2.0/23", "prefixlen": 23,
            "family": 4, "parent": "<prefix id>", "vrf": null}],
  "free_totals": {"<prefix id>": 6}
}

length=29 lists free blocks of exactly that size instead of the largest aligned ones; scope=<cidr> keeps to a block; strategy=first|best orders them (lowest address, or smallest free block first); limit is per parent (8 without a length, 16 with, at most 256). free_totals counts every free block of each parent, and only parents that have one. count and paging are unchanged. Without free=1 these parameters are unknown (see Unknown query parameters).

Available. GET /api/prefixes/available/?length=29 answers free blocks as a list:

[{"cidr": "10.0.0.16/29", "prefixlen": 29, "family": 4,
  "parent": {"id": "…", "cidr": "10.0.0.0/24"},
  "vrf": {"id": "…", "name": "CUST"}}]
Parameter Meaning
length The size; without it, the largest aligned free blocks.
within One parent: its id, or its CIDR in vrf (the global table without vrf). Without it, every container or parent the caller may view.
scope A CIDR the blocks must sit in.
vrf, site Narrow the parents (vrf=global for the global table).
strategy first (default, lowest address) or best (the smallest free block that holds one).
limit Default 16, at most 256.

A within the caller can't see, a scope outside it or a length larger than it answers 400.

Allocate. POST /api/prefixes/<id>/allocate/ with {"length": 29} and any prefix fields (description, status_id, vlan_id, site_id, tag_ids, custom_fields …; the site defaults to the parent's) creates the next free child and answers 201 with the prefix, like a create. scope and strategy work as above; cidr and vrf_id are refused. It holds a row lock on the parent and every prefix above it while it picks and creates, so two callers never get the same block. No room answers 409 under length, naming the largest free block. It needs add on prefixes and view on the parent (else 404); a site-limited caller may create only in their own site's space (403). The change log's cause is Allocated in <parent>. A plain POST /api/prefixes/ takes the same lock on the prefixes holding its cidr before it is validated, so it waits for an allocation in that space and is then refused as a duplicate, or the allocation picks the next block. A PUT or PATCH that changes cidr or vrf_id, a bulk-update/ that sets vrf_id, and an import row (/api/io/prefix/import/) that creates a prefix or changes its CIDR or VRF take it too, on the prefixes holding where the prefix lands.

Each prefix's permissions carries add_child next to change and delete: whether the caller may create a prefix inside it. It is false for a site-limited caller when the prefix, or one holding it, is shared or another site's - the creates above would be refused.

Plan. POST /api/prefixes/<id>/plan/:

{"requests": [{"count": 2, "length": 24, "description": "servers-{n}"},
              {"count": 5, "length": 29, "keep_together": true}],
 "scope": "10.0.0.0/22", "strategy": "first", "reserve_growth": false,
 "dry_run": true}

Each request takes count, length and optionally description ({n} numbers it), status_id, vlan_id, site_id, location_id, tag_ids and keep_together. Requests are placed largest first, aligned; at most 1,024 subnets. It answers:

{"parent": {"id": "…", "cidr": "10.0.0.0/22"}, "scope": "10.0.0.0/22",
 "strategy": "first", "dry_run": true, "applied": false, "fits": false,
 "items": [{"request": 0, "n": 1, "length": 24, "cidr": "10.0.1.0/24",
            "description": "servers-1", "reason": null},
           {"request": 0, "n": 2, "length": 24, "cidr": null, "description": "servers-2",
            "reason": "No free /24 left in 10.0.0.0/22; largest free block is /25."}],
 "reserved": [],
 "strip": {"root": "10.0.0.0/22", "used": [[0.0, 0.125]],
           "planned": [[0.25, 0.5]], "reserved": []},
 "created": []}

strip holds fractions of the scope for drawing. dry_run defaults to true; false creates every item in one transaction under the same lock as allocate, or nothing: a request that doesn't fit, or a field error on any item, answers 400. Send the preview's CIDRs as cidrs and the apply answers 409 if the free space changed in between. The answer then has applied: true and created: [{id, cidr}]; each change-log entry has the cause Planned in <parent>. Permissions are those of allocate, and a site-limited caller is refused (403) on the preview too.

Generating the schema offline

To export the schema to a file (for client generation, diffing, or CI):

.venv/bin/python manage.py spectacular --file schema.yaml --validate