Mike Swanson
d75c367bf7
Key is now provisioned + live-verified, so grounded the skill in the real spec (RTFM): - Mapped the OpenAPI surface (v44.4.10, 239 paths / 354 ops) — capability map added to SKILL.md (what the platform exposes vs what's wrapped vs raw-only). - Added 6 live-verified read wrappers (ns.py + ns_client.py): callqueues, timeframes, sites, contacts, autoattendants, billing (domain limits/usage). - Replaced the stale "not yet provisioned" credentials section with the live status (vaulted nsr_ reseller key, key-id nsr_hSGUB5Wo, scope Reseller 91912.service, RW) + the pbx.packetdial.com vs api.ucaasnetwork.com hostname note + override. - api.md history updated. Writes remain gated behind --confirm; everything unwrapped reachable via `raw`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# NetSapiens SNAPsolution API v2 — Reference (PacketDial / OITVOIP)
|
|
|
|
Source of truth: the live OpenAPI spec at
|
|
`https://pbx.packetdial.com/ns-api/webroot/openapi/openapi.json`
|
|
(title "NetSapiens API v2", version 44.4.10 as of 2026-06-02).
|
|
|
|
## Hosts
|
|
|
|
- **API host:** `pbx.packetdial.com` — `https://pbx.packetdial.com/ns-api/v2`
|
|
- **Customer portal (no API):** `voip.packetdial.com` — login-gated UI; the
|
|
Cascades fax/UC dashboard lives here (account 28598). Hitting `/ns-api/*` on
|
|
this host returns `errors/not_found`.
|
|
|
|
## Authentication (`bearerAuth`)
|
|
|
|
All calls send `Authorization: Bearer <token>`. Two ways to get the token:
|
|
|
|
1. **Static API key** — created in `pbx.packetdial.com` Admin > API Keys.
|
|
Prefix encodes scope: `nsr_` = reseller, `nss_` = system, `nsd_` = domain.
|
|
Use the key string directly as the bearer token (no exchange step).
|
|
2. **OAuth2 password grant** — `POST /ns-api/v2/tokens` form-encoded:
|
|
`grant_type=password&client_id=..&client_secret=..&username=..&password=..`
|
|
Response includes `access_token` (JWT) + `expires_in`. The client caches it
|
|
and refreshes ~60s before expiry.
|
|
|
|
## Endpoint inventory (239 paths, grouped)
|
|
|
|
Top-level resource groups and the methods present:
|
|
|
|
| Resource | Methods | Notes |
|
|
|---|---|---|
|
|
| `/version` | GET | platform version |
|
|
| `/apikeys`, `/apikeys/{id}`, `/apikeys/~` | GET POST PUT DELETE | `~` = current key |
|
|
| `/tokens`, `/jwt` | POST (+ GET/DELETE on jwt) | auth / token mgmt |
|
|
| `/resellers`, `/resellers/{reseller}` | GET POST PUT DELETE | |
|
|
| `/domains`, `/domains/{domain}` | GET POST PUT PATCH DELETE | `/domains/count` for totals |
|
|
| `/domains/{domain}/users`, `/users/{user}` | GET POST PUT DELETE | extensions |
|
|
| `/domains/{domain}/users/{user}/devices` | GET POST PUT DELETE | per-user SIP devices |
|
|
| `/domains/{domain}/users/{user}/answerrules` | GET POST | call routing |
|
|
| `/domains/{domain}/users/{user}/cdrs` | GET | per-user CDRs |
|
|
| `/domains/{domain}/phones` | GET POST PUT DELETE | domain device list |
|
|
| `/domains/{domain}/phonenumbers`, `/{phonenumber}` | GET POST PUT DELETE | DIDs |
|
|
| `/domains/{domain}/addresses`, `/addresses/endpoints` | GET POST PUT DELETE | emergency/E911 addrs |
|
|
| `/domains/{domain}/cdrs`, `/cdrs` | GET | call detail records (`/count` variants) |
|
|
| `/phonenumbers` | GET | global DID search |
|
|
| `/smsnumbers` | GET | |
|
|
| `/subscriptions` | GET POST PUT DELETE | event/webhook subs |
|
|
| `/connections`, `/routes`, `/routecon` | GET POST PUT DELETE | SIP trunks / routing |
|
|
| `/configurations`, `/config-definitions`, `/templates` | GET POST PUT DELETE | |
|
|
| `/certificates`, `/images` | GET POST PUT DELETE | |
|
|
| `/meetings`, `/video`, `/firebase` | GET POST | UC / video |
|
|
| `/sipflow` | GET | SIP trace |
|
|
| `/holidays`, `/cdrs` | GET | |
|
|
| `/backup`, `/restore` | POST / GET PUT | platform backup |
|
|
|
|
Many resources also expose `/count` (totals) and `#1/#2/#3` openapi-dedup
|
|
variants (same path, different query-param shapes). Use the Swagger UI for the
|
|
exact request/response schema of any specific path.
|
|
|
|
## Common query params
|
|
|
|
- List endpoints accept `limit`, `offset`, and resource-specific filters.
|
|
- CDR endpoints accept `start-date` / `end-date` (and `domain`, `user` scoping
|
|
via the nested path). Always bound CDR queries — they can be large.
|
|
|
|
## Provisioning flow (new customer domain)
|
|
|
|
1. `POST /domains` — creates the domain; dial plan auto-generates.
|
|
2. `POST /domains/{domain}/users` — one per extension.
|
|
3. `POST /domains/{domain}/users/{user}/devices` or
|
|
`POST /domains/{domain}/phones` — SIP devices (MAC provisioning).
|
|
4. `POST /domains/{domain}/phonenumbers` — attach DIDs, route to users.
|
|
5. Configure `answerrules` as needed.
|
|
|
|
## History
|
|
|
|
- 2026-04-20: API researched (session log `session-logs/2026-04-20-session.md`,
|
|
"OITVOIP / NetSapiens API Research"). Platform identified, auth shapes
|
|
documented. **No API key created yet** — provisioning the key + storing it in
|
|
`msp-tools/oitvoip.sops.yaml` was the open TODO.
|
|
- 2026-06-02: `packetdial` skill created wrapping the v2 API (read-by-default,
|
|
gated writes). Confirmed `voip.` is portal-only and `pbx.` is the API host.
|
|
- 2026-06-22: **Reseller API key provisioned + vaulted** (`msp-tools/oitvoip.sops.yaml`,
|
|
key-id `nsr_hSGUB5Wo`, scope Reseller `91912.service`, read-write). Live-verified end to
|
|
end. RTFM pass over the v2 spec (v44.4.10, 239 paths / 354 ops) — capability map added to
|
|
SKILL.md. Added live-verified read wrappers: `callqueues`, `timeframes`, `sites`,
|
|
`contacts`, `autoattendants`, `billing`. Reseller territory = 3 domains today
|
|
(arizonacomputerguru + two `*.91912.service`).
|