# Nexus365Desk Public API

REST access to your Nexus365Desk service-desk data — tickets, comments, agents, and assets — for customers on the **Public API add-on** (`apiAccess` feature flag).

The Public API is Option B of our commercialization model: you do **not** call a Nexus365Desk-hosted proxy. Instead, the Nexus365Desk setup wizard provisions an **Entra application in your own tenant** with `Sites.Selected` write access on your Nexus365Desk SharePoint site only. You call Microsoft Graph directly using that app's client credentials.

Benefits:
- **No third-party holds your data.** Traffic goes tenant → Microsoft Graph, not tenant → Nexus365Desk → Microsoft Graph.
- **Least privilege.** The app has write access to one site — not the tenant.
- **No single point of failure.** Nexus365Desk being down does not stop your API calls.
- **Audit trail stays in your tenant.** Calls appear in your own Microsoft 365 audit logs.

## Quick start

1. **Enable the add-on.** In the ops portal → customer → Add-ons, toggle **Public API** on. Or contact sales.
2. **Run the setup wizard.** In the Nexus365Desk SPFx admin → Integrations → **Public API** → click *Set up Public API*. A tenant admin consents once; the wizard returns `clientId`, `tenantId`, `clientSecret`, and `siteUrl`.
3. **Save the client secret.** It is shown exactly once. You can rotate it later from the same admin panel.
4. **Call the API.** See [authentication.md](authentication.md) for the client-credential flow and [endpoints.md](endpoints.md) for paths.

Working code samples live in [`samples/public-api/`](../../samples/public-api/): `curl.sh`, `python.py`, `node.js`, and a ready-to-import Postman collection.

## Endpoints at a glance

All paths are relative to `https://graph.microsoft.com/v1.0/sites/{siteId}` where `{siteId}` is returned by the setup wizard.

| Resource | Path | Methods |
|----------|------|---------|
| Tickets | `/lists/SD_Tickets/items` | GET, POST |
| Ticket by id | `/lists/SD_Tickets/items/{itemId}` | GET, PATCH, DELETE |
| Comments | `/lists/SD_Comments/items` | GET, POST |
| Agents | `/lists/SD_Agents/items` | GET |
| Assets | `/lists/SD_Assets/items` | GET, POST |

Standard OData query options — `$select`, `$filter`, `$orderby`, `$top`, `$expand=fields` — all work. See the full OpenAPI 3.1 spec at `https://nexus365-api.azurewebsites.net/api/public-api/openapi.json`.

## Rate limits

Microsoft Graph enforces tenant-level throttling (commonly 150 requests / 20 seconds per app per tenant). The Nexus365Desk service does not add its own throttling — your app's only rate limiter is Graph.

## Pricing & quotas

The Public API add-on is **$3 per agent per month** (monthly) or **$2.50 per agent per month** when billed annually. There is no metered overage on Option B because calls go directly to Microsoft Graph.

## Support

- OpenAPI: `https://nexus365-api.azurewebsites.net/api/public-api/openapi.json`
- Samples: [`samples/public-api/`](../../samples/public-api/)
- Status check: `GET https://nexus365-api.azurewebsites.net/api/public-api/status?tenantId={your-tenant-id}`
- Email: support@nexus365desk.io