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 401This 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'sAPI_PAGE_SIZE, see Settings). Ask for up to 2,000 with?page_size=(the deployment'sAPI_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 carriesnext, so a script that follows it reads every row whatever the cap.page- which page, from 1. A page past the end answers404.limit/offsetare not read.?limit=500answers the default 100 rows, with anextto the rest; ask withpage_sizeinstead./api/installed-software/is one of these lists: 100 rows by default, at most 2,000 withpage_size. A client that reads only the first page of any list misses rows, so follownext.count- every matching row, not only the rows on this page.next/previous- full links to the neighbouring pages, with your filters andpage_sizekept, ornullat either end. To read a whole list, follownextuntil it isnull.
# 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:
clusterandgroup(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
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
slugand 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
slugyou send that another row has is refused onslug.
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'sairflowdirections andcooling_methods, and a rack'scooling_capability. Each option carriesvalueandlabel, and the grouped taxonomies agroupso 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 orapi.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.pathis 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:
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):