Nutan API Overview
Explore Nutan's REST API — endpoints, authentication, rate limits, and OpenAPI documentation.
Overview
Nutan provides a REST API for integrations, automation, and advanced workflows. The API follows RESTful conventions with JSON request and response bodies.
Base URL
All API requests go to:
`
https://api.nutan.ai/v1
`
Authentication
API requests require a valid session token obtained through the authentication flow:
- Authenticate via Google OAuth or enterprise SSO.
- Exchange the callback code for access and refresh tokens.
- Include the access token in the Authorization header:
Authorization: Bearer <token>. - Tokens are short-lived and cryptographically signed. Refresh tokens are used to obtain new access tokens.
Available Endpoints
Contacts
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/contacts | List all contacts (supports pagination, filtering) |
| POST | /v1/contacts | Create a new contact |
| PATCH | /v1/contacts/:id | Update a contact |
| DELETE | /v1/contacts/:id | Soft-delete a contact |
Deals
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/deals | List all deals (filter by stage, status) |
| POST | /v1/deals | Create a new deal |
| PATCH | /v1/deals/:id | Update a deal |
| DELETE | /v1/deals/:id | Soft-delete a deal |
Meetings
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/meetings | List all meetings |
| POST | /v1/meetings | Create a meeting record |
| DELETE | /v1/meetings/:id | Delete a meeting |
Meeting Participants
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/meetings/:id/participants | List participants for a meeting |
| POST | /v1/meetings/:id/participants | Add a participant |
Action Items
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/action-items | List action items |
| POST | /v1/action-items | Create an action item |
| PATCH | /v1/action-items/:id | Update an action item |
| DELETE | /v1/action-items/:id | Delete an action item |
Signals & Objections
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/deals/:id/signals | List signals for a deal |
| GET | /v1/deals/:id/objections | List objections for a deal |
Sync
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/sync | Batch upsert/delete across tables (desktop sync) |
| DELETE | /v1/sync | GDPR full data erasure |
Usage Metering
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/tokens | Record token usage metrics |
Pagination
List endpoints support pagination via query parameters:
limit— Number of results per page (default varies by endpoint)offset— Number of results to skip
Response includes pagination metadata: total, limit, offset.
Rate Limits
| Tier | Limit |
|---|---|
| Global | 100 requests per minute per IP |
| Strict endpoints (auth, sync) | 3–10 requests per minute per IP |
Rate limit headers are included in every response.
Error Handling
Errors return structured JSON:
400— Validation error (seedetailsfield)401— Authentication required or token expired403— Insufficient permissions404— Resource not found429— Rate limit exceeded
Error responses never contain PII.
OpenAPI Specification
Full API documentation is available in OpenAPI format:
- YAML: https://api.nutan.ai/openapi.yaml
- JSON: https://api.nutan.ai/openapi.json
- Interactive docs: https://api.nutan.ai/docs
The OpenAPI spec is auto-generated from the API source code and always reflects the current API surface.