Overview
Alongside the 4.6.15 release, we're shipping a major expansion to our REST API, moving from /api/2.0/ to /api/2.1/. The new namespace is a superset of 2.0 — same schema, same authentication, plus a large catalog of new capabilities.
Point Claude Code or any other AI to /api/2.1/docs/json and it will instantly know how to sync almost all data in and out of the IT Portal. Same as 2.0, but now with folders, files, relationships, full type CRUD, global search, and address creation.
Swagger (authoritative): https://<your-host>/api/2.1/docs/json/
Test script: https://<your-host>/api/test-portal-api/
Why this matters
The 2.0 API exposed mostly read-side inventory endpoints. 2.1 closes the write-side gaps that mattered most for automation and AI agents — the surfaces that let a program round-trip everything the portal holds: object records, attached files, cross-object links, and type catalogs.
Scale of the change: 76 → 158 top-level endpoint paths, with 82 new paths and full CRUD added where only GET existed in 2.0.
What's new in 2.1
Folders & files on every object
Every major object kind now exposes its folder tree and binary attachments through the API. Documents, devices, contacts, KBs, agreements, configurations, cabinets, sites, facilities, accounts, and companies — all 11 object types get the same six folder endpoints plus five file endpoints. Multipart uploads, raw-binary downloads, soft-delete, 409 safeguards when folders contain files.
Agents and automation can finally round-trip attached documents, signed agreements, contact photos, device manuals, and KB references — not just the metadata.
Relationships API
Link any two portal objects (device ↔ agreement, contact ↔ document, etc.) through a uniform /relationships/ endpoint. Create, list, update notes, delete. Symmetric duplicate detection (creating A→B when B→A already exists returns 409 duplicateRelationship), self-link prevention, and clean source/target normalization in every response regardless of which side you query from.
Global search
A single query hits every indexed field across accounts, agreements, devices, documents, and more — with quick vs. deep ("crawl") modes and company scoping:
GET /api/2.1/search/ cross-object fuzzy search
GET /api/2.1/search/credentials/ credential-specific search
This is the recommended entry point for AI agents: find the right object first, then call the object-specific endpoints to act on it.
Full CRUD on Types and KB Categories
2.0 exposed only the read side. 2.1 adds create, rename, and delete for all eight type kinds (account, agreement, company, contact, device, document, facility, configuration) plus KB categories and subcategories. Safe-delete rejects with 409 typeInUse or categoryInUse when rows still reference the type.
Now migration scripts and provisioning tools can stand up a target tenant's type catalog without the UI.
Company-scoped convenience routes
Fetch a customer's inventory without a ?companyId= parameter dance:
GET /api/2.1/companies/{companyId}/devices/
GET /api/2.1/companies/{companyId}/documents/
Each honors the same filters as the top-level list endpoints (modifiedSince, cursor, limit).
Addresses endpoint: create + improved response
2.0 exposed /addresses/ as read-only and omitted the owning company from responses — so migration tools couldn't resolve an address to its parent. 2.1 fixes both:
POST /api/2.1/addresses/creates an address from body withcompany.id- Every address response now includes
company: { id, name }, matching every other resource type
Richer device and configuration models
Devices gain full CRUD on IPs, management URLs, notes, and switch-port ranges. Configurations now expose a credentials fetch (GET /api/2.1/configurations/{id}/credentials/), joining devices and accounts.
Interactions as a first-class object
Notes on any object (Account, Agreement, ConfigObject, Contact, Device, Document, Facility, KB, Cabinet, Site, Subnet) now have full CRUD through /api/2.1/interactions/{objectType}/{objectId}/.
Sheets, Forms, Logs, Templates, System
The following areas got complete API coverage in 2.1, most of which were sparse or missing in 2.0:
- Sheets — per-object data sheets
- Forms & Form Instances — template-driven form collection
- Logs — user access, admin access, login/logout, password access, password changes
- Templates — full template and per-field file support
- System — users, countries, security groups, main contacts
Behavior fixes worth calling out
| Change | Impact |
|---|---|
PUT returns 405 Method Not Allowed with Use PATCH for partial updates. |
On 2.0, PUT silently dropped the write. Any ported code still sending PUT now gets a loud error instead of silent corruption. |
GET /addresses/ responses include company: { id, name } |
Migration tools can resolve an address to its owning company. |
| Cursor pagination on every list endpoint | Stable keyset pagination with modifiedSince for change polling. Offset pagination still works but is deprecated. |
?modifiedSince=<ISO> filter on every list endpoint |
Indexed on mod_date; safe for frequent polling. Replaces the need for webhooks for most use cases. |
Migrating from 2.0
- Switch the base path from
/api/2.0/to/api/2.1/. Everything that worked on 2.0 works on 2.1 without code changes. - Stop using PUT. 2.1 rejects PUT with a clear 405 directing you to PATCH. On 2.0, PUT silently dropped the write — any 2.0 client still using PUT is likely losing data and won't know it until it switches.
- Pull Swagger fresh from
/api/2.1/docs/json/before coding. It's machine-readable and covers every parameter, filter, and response shape.
2.0 remains available and unchanged; migrate to 2.1 at your pace.
