{ "openapi": "3.1.0", "info": { "title": "Nextora API", "version": "2026-10-10", "summary": "REST API of a Nextora workspace.", "description": "The Nextora REST API: contacts, companies, deals, pipelines, tasks, leads, notes, users, custom fields, the sales forecast and webhook subscriptions of one workspace.\n\nBase URL: `https://{workspace}.nextora.co/api/v1` (custom domains work the same). HTTPS only; JSON in and out (UTF-8); snake_case fields; timestamps are ISO 8601 UTC, dates `YYYY-MM-DD`.\n\nAuthenticate with `Authorization: Bearer sk_live_…` (Settings → Developers → API keys). A key acts as its owner — the same records and role permissions as in the app — narrowed by its scopes.\n\nEvery response carries `X-Request-Id`, `X-API-Version: 2026-10-10` and `X-RateLimit-*` headers. The default limit is 500 requests per minute per key (may change).\n\nWrites go through the same logic as the app: automations, the activity log and webhooks behave exactly as for edits made by a person. Deleting moves records to the Trash; `POST /{resource}/{id}/restore` brings them back.\n\nServer-to-server only: there is no CORS. This document itself is public at `GET /api/v1/openapi.json` (readable cross-origin), and `GET /api/v1/docs` redirects to the documentation.\n\nFull documentation: https://nextora.co/docs", "contact": { "name": "Nextora", "url": "https://nextora.co/docs" } }, "servers": [ { "url": "https://{workspace}.nextora.co/api/v1", "description": "Your workspace", "variables": { "workspace": { "default": "acme", "description": "Your workspace address: .nextora.co." } } } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Contacts", "description": "People you do business with." }, { "name": "Companies", "description": "Organisations your contacts belong to." }, { "name": "Deals", "description": "Opportunities moving through a pipeline." }, { "name": "Pipelines", "description": "Deal pipelines and their stages (read-only)." }, { "name": "Tasks", "description": "Work items on the workspace's task boards." }, { "name": "Leads", "description": "Incoming enquiries, before they become contacts and deals." }, { "name": "Notes", "description": "Notes on contacts, companies, deals and leads." }, { "name": "Users", "description": "Members of the workspace (read-only)." }, { "name": "Custom fields", "description": "Definitions of the custom fields each record type carries (read-only)." }, { "name": "Forecast", "description": "Sales forecast by category for a period." }, { "name": "Webhooks", "description": "Subscriptions that push events to your HTTPS endpoint." } ], "paths": { "/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Lists contacts the key owner can see, newest first. Contacts in the Trash are not listed.\n\nScope: `contacts:read`.", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" }, { "name": "sort", "in": "query", "description": "Sort field. Default `created_at`.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "first_name", "last_name", "email", "last_activity_at" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort direction. Default `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "q", "in": "query", "description": "Search: first and last name, email and phone (digits match any formatting).", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/filter" }, { "name": "email", "in": "query", "description": "Email, case-insensitive. `like` matches a fragment. Pass `null` for empty. Operators: `email[neq]`, `email[like]`, `email[in]`.", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "description": "Phone as stored. Pass `null` for empty. Operators: `phone[neq]`, `phone[like]`, `phone[in]`.", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Linked company; `null` = no company. Pass `null` for empty. Operators: `company_id[neq]`, `company_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "owner_id", "in": "query", "description": "Primary owner. Operators: `owner_id[neq]`, `owner_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "query", "description": "Source, case-insensitive. Pass `null` for empty. Operators: `source[neq]`, `source[like]`, `source[in]`.", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Has this tag (by name); `tags[in]=a,b` = has any of them. Operators: `tags[in]`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "Creation time. Operators: `created_at[neq]`, `created_at[gt]`, `created_at[gte]`, `created_at[lt]`, `created_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "description": "Last change. Operators: `updated_at[neq]`, `updated_at[gt]`, `updated_at[gte]`, `updated_at[lt]`, `updated_at[lte]`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:read" ], "x-nextora-list": { "filters": [ { "field": "email", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Email, case-insensitive. `like` matches a fragment." }, { "field": "phone", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Phone as stored." }, { "field": "company_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Linked company; `null` = no company." }, { "field": "owner_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": false, "description": "Primary owner." }, { "field": "source", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Source, case-insensitive." }, { "field": "tags", "type": "tags", "operators": [ "eq", "in" ], "nullable": false, "description": "Has this tag (by name); `tags[in]=a,b` = has any of them." }, { "field": "created_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Creation time." }, { "field": "updated_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Last change." } ], "sortable": [ "created_at", "updated_at", "first_name", "last_name", "email", "last_activity_at" ], "default_sort": "created_at", "default_order": "desc", "search": "first and last name, email and phone (digits match any formatting)", "advanced_filter": true } }, "post": { "operationId": "createContact", "summary": "Create a contact", "description": "Creates a contact exactly like the app does: on-create automations run, the activity log records it and the owner is notified. `owner_id` defaults to the API key's owner.\n\nScope: `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" }, "example": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@analytical-engines.example", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "tags": [ "VIP" ], "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" } } } } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Retrieve a contact", "description": "Returns one contact. A contact in the Trash answers 404 — restore it first.\n\nScope: `contacts:read`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:read" ] }, "put": { "operationId": "updateContactPut", "summary": "Update a contact (PUT)", "description": "Same as `PATCH /contacts/{id}` — both are partial updates.\n\nPartial update — only the fields you send change (PUT behaves the same). Field-change automations run and the activity log records the change, as for an edit in the app. `custom_fields` is merged; `tags` replaces the tags.\n\nScope: `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" }, "example": { "position": "CTO", "tags": [ "VIP", "Partner" ], "custom_fields": { "linkedin": null } } } } } }, "patch": { "operationId": "updateContact", "summary": "Update a contact", "description": "Partial update — only the fields you send change (PUT behaves the same). Field-change automations run and the activity log records the change, as for an edit in the app. `custom_fields` is merged; `tags` replaces the tags.\n\nScope: `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" }, "example": { "position": "CTO", "tags": [ "VIP", "Partner" ], "custom_fields": { "linkedin": null } } } } } }, "delete": { "operationId": "deleteContact", "summary": "Delete a contact", "description": "Moves the contact to the workspace Trash, exactly like deleting it in the app: automations listening for deletions run, and it can be brought back with POST /contacts/{id}/restore until the Trash is emptied.\n\nScope: `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ] } }, "/contacts/{id}/restore": { "post": { "operationId": "restoreContact", "summary": "Restore a contact from the Trash", "description": "Brings a deleted contact back from the Trash, the same way the Trash screen does. Restoring a contact that is not in the Trash is a no-op that returns it.\n\nScope: `contacts:write`.", "tags": [ "Contacts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Contact" } } }, "example": { "data": { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ] } }, "/companies": { "get": { "operationId": "listCompanies", "summary": "List companies", "description": "Lists companies the key owner can see, newest first. Companies in the Trash are not listed.\n\nScope: `companies:read`.", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" }, { "name": "sort", "in": "query", "description": "Sort field. Default `created_at`.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "industry" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort direction. Default `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "q", "in": "query", "description": "Search: name.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/filter" }, { "name": "name", "in": "query", "description": "Name, case-insensitive. `like` matches a fragment. Operators: `name[neq]`, `name[like]`, `name[in]`.", "schema": { "type": "string" } }, { "name": "industry", "in": "query", "description": "Industry, case-insensitive. Pass `null` for empty. Operators: `industry[neq]`, `industry[like]`, `industry[in]`.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "description": "Primary owner. Operators: `owner_id[neq]`, `owner_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "created_at", "in": "query", "description": "Creation time. Operators: `created_at[neq]`, `created_at[gt]`, `created_at[gte]`, `created_at[lt]`, `created_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "description": "Last change. Operators: `updated_at[neq]`, `updated_at[gt]`, `updated_at[gte]`, `updated_at[lt]`, `updated_at[lte]`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:read" ], "x-nextora-list": { "filters": [ { "field": "name", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": false, "description": "Name, case-insensitive. `like` matches a fragment." }, { "field": "industry", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Industry, case-insensitive." }, { "field": "owner_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": false, "description": "Primary owner." }, { "field": "created_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Creation time." }, { "field": "updated_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Last change." } ], "sortable": [ "created_at", "updated_at", "name", "industry" ], "default_sort": "created_at", "default_order": "desc", "search": "name", "advanced_filter": true } }, "post": { "operationId": "createCompany", "summary": "Create a company", "description": "Creates a company exactly like the app does (on-create automations, activity log). `owner_id` defaults to the API key's owner. Industry and address must contain letters (no emoji).\n\nScope: `companies:write`.", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreate" }, "example": { "name": "Analytical Engines Ltd", "industry": "Computing", "website": "analytical-engines.example", "size": "51-200" } } } } } }, "/companies/{id}": { "get": { "operationId": "getCompany", "summary": "Retrieve a company", "description": "Returns one company. A company in the Trash answers 404 — restore it first.\n\nScope: `companies:read`.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:read" ] }, "put": { "operationId": "updateCompanyPut", "summary": "Update a company (PUT)", "description": "Same as `PATCH /companies/{id}` — both are partial updates.\n\nPartial update — only the fields you send change (PUT behaves the same). Field-change automations run as for an edit in the app. `custom_fields` is merged; `tags` replaces the tags.\n\nScope: `companies:write`.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdate" }, "example": { "size": "201-500", "tags": [ "Enterprise", "Renewal 2027" ] } } } } }, "patch": { "operationId": "updateCompany", "summary": "Update a company", "description": "Partial update — only the fields you send change (PUT behaves the same). Field-change automations run as for an edit in the app. `custom_fields` is merged; `tags` replaces the tags.\n\nScope: `companies:write`.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdate" }, "example": { "size": "201-500", "tags": [ "Enterprise", "Renewal 2027" ] } } } } }, "delete": { "operationId": "deleteCompany", "summary": "Delete a company", "description": "Moves the company to the workspace Trash, exactly like deleting it in the app: automations listening for deletions run, and it can be brought back with POST /companies/{id}/restore until the Trash is emptied.\n\nScope: `companies:write`.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ] } }, "/companies/{id}/restore": { "post": { "operationId": "restoreCompany", "summary": "Restore a company from the Trash", "description": "Brings a deleted company back from the Trash, the same way the Trash screen does. Restoring a company that is not in the Trash is a no-op that returns it.\n\nScope: `companies:write`.", "tags": [ "Companies" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Company" } } }, "example": { "data": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ] } }, "/deals": { "get": { "operationId": "listDeals", "summary": "List deals", "description": "Lists deals the key owner can see, newest first. Deals in the Trash are not listed.\n\nScope: `deals:read`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" }, { "name": "sort", "in": "query", "description": "Sort field. Default `created_at`.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title", "value", "probability", "expected_close_date", "closed_at" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort direction. Default `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "q", "in": "query", "description": "Search: title.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/filter" }, { "name": "status", "in": "query", "description": "Outcome. Operators: `status[neq]`, `status[in]`.", "schema": { "type": "string", "enum": [ "in_progress", "won", "lost", "on_hold" ] } }, { "name": "pipeline_id", "in": "query", "description": "Pipeline. Operators: `pipeline_id[neq]`, `pipeline_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "stage_id", "in": "query", "description": "Stage. Operators: `stage_id[neq]`, `stage_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "contact_id", "in": "query", "description": "Linked contact. Pass `null` for empty. Operators: `contact_id[neq]`, `contact_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "company_id", "in": "query", "description": "Linked company. Pass `null` for empty. Operators: `company_id[neq]`, `company_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "owner_id", "in": "query", "description": "Primary owner; `null` = unassigned. Pass `null` for empty. Operators: `owner_id[neq]`, `owner_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "value", "in": "query", "description": "Amount. Operators: `value[neq]`, `value[gt]`, `value[gte]`, `value[lt]`, `value[lte]`, `value[in]`.", "schema": { "type": "number" } }, { "name": "expected_close_date", "in": "query", "description": "Expected close date. Pass `null` for empty. Operators: `expected_close_date[neq]`, `expected_close_date[gt]`, `expected_close_date[gte]`, `expected_close_date[lt]`, `expected_close_date[lte]`.", "schema": { "type": "string", "format": "date" } }, { "name": "created_at", "in": "query", "description": "Creation time. Operators: `created_at[neq]`, `created_at[gt]`, `created_at[gte]`, `created_at[lt]`, `created_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "description": "Last change. Operators: `updated_at[neq]`, `updated_at[gt]`, `updated_at[gte]`, `updated_at[lt]`, `updated_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "closed_at", "in": "query", "description": "When the deal was won or lost. Pass `null` for empty. Operators: `closed_at[neq]`, `closed_at[gt]`, `closed_at[gte]`, `closed_at[lt]`, `closed_at[lte]`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:read" ], "x-nextora-hub": "sales", "x-nextora-list": { "filters": [ { "field": "status", "type": "enum", "operators": [ "eq", "neq", "in" ], "nullable": false, "values": [ "in_progress", "won", "lost", "on_hold" ], "description": "Outcome." }, { "field": "pipeline_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": false, "description": "Pipeline." }, { "field": "stage_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": false, "description": "Stage." }, { "field": "contact_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Linked contact." }, { "field": "company_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Linked company." }, { "field": "owner_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Primary owner; `null` = unassigned." }, { "field": "value", "type": "number", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte", "in" ], "nullable": false, "description": "Amount." }, { "field": "expected_close_date", "type": "date", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": true, "description": "Expected close date." }, { "field": "created_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Creation time." }, { "field": "updated_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Last change." }, { "field": "closed_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": true, "description": "When the deal was won or lost." } ], "sortable": [ "created_at", "updated_at", "title", "value", "probability", "expected_close_date", "closed_at" ], "default_sort": "created_at", "default_order": "desc", "search": "title", "advanced_filter": true } }, "post": { "operationId": "createDeal", "summary": "Create a deal", "description": "Creates a deal exactly like the app does: it gets a card on its pipeline board, on-create automations run and the owners are notified. Without `pipeline_id` / `stage_id` it lands on the first stage of the default pipeline. `status` is honoured (create a deal already won or lost); `currency` defaults to the workspace currency; `probability` defaults to 10.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealCreate" }, "example": { "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "expected_close_date": "2026-11-30", "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e" } } } } } }, "/deals/{id}": { "get": { "operationId": "getDeal", "summary": "Retrieve a deal", "description": "Returns one deal. A deal in the Trash answers 404 — restore it first.\n\nScope: `deals:read`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:read" ], "x-nextora-hub": "sales" }, "put": { "operationId": "updateDealPut", "summary": "Update a deal (PUT)", "description": "Same as `PATCH /deals/{id}` — both are partial updates.\n\nPartial update — only the fields you send change (PUT behaves the same). Changing `stage_id` within the deal's pipeline moves it like dragging the card on the board: the stage entry time resets and stage automations and events run. `pipeline_id` moves the deal to another pipeline (first stage unless `stage_id` is given). `status` is the outcome and is independent of the stage; setting it to won/lost stamps `closed_at`.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdate" }, "example": { "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "probability": 60, "forecast_category": "commit" } } } } }, "patch": { "operationId": "updateDeal", "summary": "Update a deal", "description": "Partial update — only the fields you send change (PUT behaves the same). Changing `stage_id` within the deal's pipeline moves it like dragging the card on the board: the stage entry time resets and stage automations and events run. `pipeline_id` moves the deal to another pipeline (first stage unless `stage_id` is given). `status` is the outcome and is independent of the stage; setting it to won/lost stamps `closed_at`.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdate" }, "example": { "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "probability": 60, "forecast_category": "commit" } } } } }, "delete": { "operationId": "deleteDeal", "summary": "Delete a deal", "description": "Moves the deal to the workspace Trash, exactly like deleting it in the app: automations listening for deletions run, and it can be brought back with POST /deals/{id}/restore until the Trash is emptied.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales" } }, "/deals/{id}/restore": { "post": { "operationId": "restoreDeal", "summary": "Restore a deal from the Trash", "description": "Brings a deleted deal back from the Trash, the same way the Trash screen does. Restoring a deal that is not in the Trash is a no-op that returns it.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Deals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deal" } } }, "example": { "data": { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales" } }, "/pipelines": { "get": { "operationId": "listPipelines", "summary": "List deal pipelines", "description": "The workspace's deal pipelines with their stages in board order, oldest pipeline first. `is_default` marks the pipeline a deal lands in when it is created without `pipeline_id`. Archived pipelines are not listed.\n\nScope: `deals:read`. Part of the **sales** hub.", "tags": [ "Pipelines" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales", "is_default": true, "currency": null, "stages": [ { "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "name": "Lead", "position": 0, "type": "open", "probability": null, "color": "#6B7280" }, { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "position": 1, "type": "open", "probability": null, "color": "#F97316" }, { "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a", "name": "Won", "position": 2, "type": "won", "probability": null, "color": "#10B981" }, { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "name": "Lost", "position": 3, "type": "lost", "probability": null, "color": "#EF4444" } ] } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:read" ], "x-nextora-hub": "sales", "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "asc", "advanced_filter": false } } }, "/pipelines/{id}": { "get": { "operationId": "getPipeline", "summary": "Retrieve a pipeline", "description": "One deal pipeline with its stages.\n\nScope: `deals:read`. Part of the **sales** hub.", "tags": [ "Pipelines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The pipeline's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Pipeline" } } }, "example": { "data": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales", "is_default": true, "currency": null, "stages": [ { "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "name": "Lead", "position": 0, "type": "open", "probability": null, "color": "#6B7280" }, { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "position": 1, "type": "open", "probability": null, "color": "#F97316" }, { "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a", "name": "Won", "position": 2, "type": "won", "probability": null, "color": "#10B981" }, { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "name": "Lost", "position": 3, "type": "lost", "probability": null, "color": "#EF4444" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:read" ], "x-nextora-hub": "sales" } }, "/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "description": "Lists tasks the key owner can see, newest first — subtasks included (filter `parent_task_id=null` for top-level tasks only). Archived tasks and tasks in the Trash are not listed; an archived task is still readable by id.\n\nScope: `tasks:read`.", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" }, { "name": "sort", "in": "query", "description": "Sort field. Default `created_at`.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "title", "due_date", "start_date", "priority", "completed_at" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort direction. Default `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "q", "in": "query", "description": "Search: title.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/filter" }, { "name": "status", "in": "query", "description": "Workflow state. Operators: `status[neq]`, `status[in]`.", "schema": { "type": "string", "enum": [ "todo", "in_progress", "done" ] } }, { "name": "priority", "in": "query", "description": "Priority key; `null` = no priority. Pass `null` for empty. Operators: `priority[neq]`, `priority[like]`, `priority[in]`.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "description": "Primary responsible user. Operators: `owner_id[neq]`, `owner_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "contact_id", "in": "query", "description": "Linked contact. Pass `null` for empty. Operators: `contact_id[neq]`, `contact_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "deal_id", "in": "query", "description": "Linked deal. Pass `null` for empty. Operators: `deal_id[neq]`, `deal_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "description": "Project. Pass `null` for empty. Operators: `project_id[neq]`, `project_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "space_id", "in": "query", "description": "Task space (board). Pass `null` for empty. Operators: `space_id[neq]`, `space_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "parent_task_id", "in": "query", "description": "Parent task; `null` = top-level tasks only. Pass `null` for empty. Operators: `parent_task_id[neq]`, `parent_task_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "due_date", "in": "query", "description": "Due date. Pass `null` for empty. Operators: `due_date[neq]`, `due_date[gt]`, `due_date[gte]`, `due_date[lt]`, `due_date[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "start_date", "in": "query", "description": "Start date. Pass `null` for empty. Operators: `start_date[neq]`, `start_date[gt]`, `start_date[gte]`, `start_date[lt]`, `start_date[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_at", "in": "query", "description": "Creation time. Operators: `created_at[neq]`, `created_at[gt]`, `created_at[gte]`, `created_at[lt]`, `created_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "description": "Last change. Operators: `updated_at[neq]`, `updated_at[gt]`, `updated_at[gte]`, `updated_at[lt]`, `updated_at[lte]`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:read" ], "x-nextora-list": { "filters": [ { "field": "status", "type": "enum", "operators": [ "eq", "neq", "in" ], "nullable": false, "values": [ "todo", "in_progress", "done" ], "description": "Workflow state." }, { "field": "priority", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Priority key; `null` = no priority." }, { "field": "owner_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": false, "description": "Primary responsible user." }, { "field": "contact_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Linked contact." }, { "field": "deal_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Linked deal." }, { "field": "project_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Project." }, { "field": "space_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Task space (board)." }, { "field": "parent_task_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Parent task; `null` = top-level tasks only." }, { "field": "due_date", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": true, "description": "Due date." }, { "field": "start_date", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": true, "description": "Start date." }, { "field": "created_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Creation time." }, { "field": "updated_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Last change." } ], "sortable": [ "created_at", "updated_at", "title", "due_date", "start_date", "priority", "completed_at" ], "default_sort": "created_at", "default_order": "desc", "search": "title", "advanced_filter": true } }, "post": { "operationId": "createTask", "summary": "Create a task", "description": "Creates a task exactly like the app does: it lands in its space's board column for `status`, on-create automations run and a new owner is notified. Without `space_id` it goes to the workspace's default space (a subtask goes to its parent's space). A task created with `status: done` is completed at once.\n\nScope: `tasks:write`.", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreate" }, "example": { "title": "Send the licence proposal", "due_date": "2026-10-15", "priority": "high", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b" } } } } } }, "/tasks/{id}": { "get": { "operationId": "getTask", "summary": "Retrieve a task", "description": "Returns one task. A task in the Trash answers 404 — restore it first.\n\nScope: `tasks:read`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:read" ] }, "put": { "operationId": "updateTaskPut", "summary": "Update a task (PUT)", "description": "Same as `PATCH /tasks/{id}` — both are partial updates.\n\nPartial update — only the fields you send change (PUT behaves the same). `status` moves the task to the matching column of its space; setting `done` completes it (completion automations, goals and notifications follow, as in the app). `assignee_ids` replaces the whole Responsible set; the owner always stays in it.\n\nScope: `tasks:write`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdate" }, "example": { "status": "done" } } } } }, "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Partial update — only the fields you send change (PUT behaves the same). `status` moves the task to the matching column of its space; setting `done` completes it (completion automations, goals and notifications follow, as in the app). `assignee_ids` replaces the whole Responsible set; the owner always stays in it.\n\nScope: `tasks:write`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdate" }, "example": { "status": "done" } } } } }, "delete": { "operationId": "deleteTask", "summary": "Delete a task", "description": "Moves the task to the workspace Trash, exactly like deleting it in the app: automations listening for deletions run, and it can be brought back with POST /tasks/{id}/restore until the Trash is emptied. Its subtasks go to the Trash with it and come back with it.\n\nScope: `tasks:write`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:write" ] } }, "/tasks/{id}/restore": { "post": { "operationId": "restoreTask", "summary": "Restore a task from the Trash", "description": "Brings a deleted task back from the Trash, the same way the Trash screen does. Restoring a task that is not in the Trash is a no-op that returns it.\n\nScope: `tasks:write`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The task's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } }, "example": { "data": { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "tasks:write" ] } }, "/leads": { "get": { "operationId": "listLeads", "summary": "List leads", "description": "Lists leads the key owner can see, newest first. Leads in the Trash are not listed.\n\nScope: `leads:read`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" }, { "name": "sort", "in": "query", "description": "Sort field. Default `created_at`.", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "name", "status", "score" ], "default": "created_at" } }, { "name": "order", "in": "query", "description": "Sort direction. Default `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "q", "in": "query", "description": "Search: name.", "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/filter" }, { "name": "name", "in": "query", "description": "Name, case-insensitive. `like` matches a fragment. Operators: `name[neq]`, `name[like]`, `name[in]`.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Email, case-insensitive. `like` matches a fragment. Pass `null` for empty. Operators: `email[neq]`, `email[like]`, `email[in]`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Status key. Operators: `status[neq]`, `status[like]`, `status[in]`.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "description": "Source key. Pass `null` for empty. Operators: `source[neq]`, `source[like]`, `source[in]`.", "schema": { "type": "string" } }, { "name": "owner_id", "in": "query", "description": "Owner; `null` = unassigned. Pass `null` for empty. Operators: `owner_id[neq]`, `owner_id[in]`.", "schema": { "type": "string", "format": "uuid" } }, { "name": "company_name", "in": "query", "description": "Company name, case-insensitive. Pass `null` for empty. Operators: `company_name[neq]`, `company_name[like]`, `company_name[in]`.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "Creation time. Operators: `created_at[neq]`, `created_at[gt]`, `created_at[gte]`, `created_at[lt]`, `created_at[lte]`.", "schema": { "type": "string", "format": "date-time" } }, { "name": "updated_at", "in": "query", "description": "Last change. Operators: `updated_at[neq]`, `updated_at[gt]`, `updated_at[gte]`, `updated_at[lt]`, `updated_at[lte]`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:read" ], "x-nextora-hub": "sales", "x-nextora-list": { "filters": [ { "field": "name", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": false, "description": "Name, case-insensitive. `like` matches a fragment." }, { "field": "email", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Email, case-insensitive. `like` matches a fragment." }, { "field": "status", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": false, "description": "Status key." }, { "field": "source", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Source key." }, { "field": "owner_id", "type": "uuid", "operators": [ "eq", "neq", "in" ], "nullable": true, "description": "Owner; `null` = unassigned." }, { "field": "company_name", "type": "string", "operators": [ "eq", "neq", "like", "in" ], "nullable": true, "description": "Company name, case-insensitive." }, { "field": "created_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Creation time." }, { "field": "updated_at", "type": "datetime", "operators": [ "eq", "neq", "gt", "gte", "lt", "lte" ], "nullable": false, "description": "Last change." } ], "sortable": [ "created_at", "updated_at", "name", "status", "score" ], "default_sort": "created_at", "default_order": "desc", "search": "name", "advanced_filter": true } }, "post": { "operationId": "createLead", "summary": "Create a lead", "description": "Creates a lead exactly like the app does (on-create automations, activity log, lead scoring). This is the one write that keeps working while the workspace is read-only, so web-to-lead integrations never lose an enquiry. `owner_id` defaults to the API key's owner; send `null` to leave the lead unassigned.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCreate" }, "example": { "name": "Charles Babbage", "email": "charles@difference.example", "company_name": "Difference Engines", "source": "website", "custom_fields": { "budget": 20000 } } } } } } }, "/leads/{id}": { "get": { "operationId": "getLead", "summary": "Retrieve a lead", "description": "Returns one lead. A lead in the Trash answers 404 — restore it first.\n\nScope: `leads:read`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:read" ], "x-nextora-hub": "sales" }, "put": { "operationId": "updateLeadPut", "summary": "Update a lead (PUT)", "description": "Same as `PATCH /leads/{id}` — both are partial updates.\n\nPartial update — only the fields you send change (PUT behaves the same). Status changes notify the lead's audience and run field-change automations, as in the app. `custom_fields` is merged.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadUpdate" }, "example": { "status": "qualified", "custom_fields": { "budget": 25000 } } } } } }, "patch": { "operationId": "updateLead", "summary": "Update a lead", "description": "Partial update — only the fields you send change (PUT behaves the same). Status changes notify the lead's audience and run field-change automations, as in the app. `custom_fields` is merged.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadUpdate" }, "example": { "status": "qualified", "custom_fields": { "budget": 25000 } } } } } }, "delete": { "operationId": "deleteLead", "summary": "Delete a lead", "description": "Moves the lead to the workspace Trash, exactly like deleting it in the app: automations listening for deletions run, and it can be brought back with POST /leads/{id}/restore until the Trash is emptied.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales" } }, "/leads/{id}/restore": { "post": { "operationId": "restoreLead", "summary": "Restore a lead from the Trash", "description": "Brings a deleted lead back from the Trash, the same way the Trash screen does. Restoring a lead that is not in the Trash is a no-op that returns it.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Leads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } }, "example": { "data": { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales" } }, "/contacts/{id}/notes": { "get": { "operationId": "listContactNotes", "summary": "List a contact's notes", "description": "Notes on the contact, newest first.\n\nScope: `contacts:read`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "contact", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:read" ], "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "desc", "advanced_filter": false } }, "post": { "operationId": "createContactNote", "summary": "Add a note to a contact", "description": "Adds a note to the contact's feed, authored by the API key's owner, and logs it in the activity history.\n\nScope: `contacts:write`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The contact's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "contact", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" }, "example": { "body": "Called Ada — wants the volume discount in writing by Friday." } } } } } }, "/companies/{id}/notes": { "get": { "operationId": "listCompanyNotes", "summary": "List a company's notes", "description": "Notes on the company, newest first.\n\nScope: `companies:read`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "company", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:read" ], "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "desc", "advanced_filter": false } }, "post": { "operationId": "createCompanyNote", "summary": "Add a note to a company", "description": "Adds a note to the company's feed, authored by the API key's owner, and logs it in the activity history.\n\nScope: `companies:write`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The company's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "company", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "companies:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" }, "example": { "body": "Called Ada — wants the volume discount in writing by Friday." } } } } } }, "/deals/{id}/notes": { "get": { "operationId": "listDealNotes", "summary": "List a deal's notes", "description": "Notes on the deal, newest first.\n\nScope: `deals:read`. Part of the **sales** hub.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "deal", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:read" ], "x-nextora-hub": "sales", "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "desc", "advanced_filter": false } }, "post": { "operationId": "createDealNote", "summary": "Add a note to a deal", "description": "Adds a note to the deal's feed, authored by the API key's owner, and logs it in the activity history.\n\nScope: `deals:write`. Part of the **sales** hub.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The deal's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "deal", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "deals:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" }, "example": { "body": "Called Ada — wants the volume discount in writing by Friday." } } } } } }, "/leads/{id}/notes": { "get": { "operationId": "listLeadNotes", "summary": "List a lead's notes", "description": "Notes on the lead, newest first.\n\nScope: `leads:read`. Part of the **sales** hub.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "lead", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:read" ], "x-nextora-hub": "sales", "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "desc", "advanced_filter": false } }, "post": { "operationId": "createLeadNote", "summary": "Add a note to a lead", "description": "Adds a note to the lead's feed, authored by the API key's owner, and logs it in the activity history.\n\nScope: `leads:write`. Part of the **sales** hub.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The lead's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "lead", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "leads:write" ], "x-nextora-hub": "sales", "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreate" }, "example": { "body": "Called Ada — wants the volume discount in writing by Friday." } } } } } }, "/notes/{id}": { "get": { "operationId": "getNote", "summary": "Retrieve a note", "description": "Returns one note. Needs the read scope of the record it is attached to.\n\nThe read (GET) or write scope of the record the note is attached to, e.g. `contacts:read`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "contact", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:read", "companies:read", "deals:read", "leads:read" ] }, "patch": { "operationId": "updateNote", "summary": "Update a note", "description": "Replaces the note's text. Needs the write scope of the record it is attached to. Only the note's author or an admin can edit it — the same rule as for deleting.\n\nThe read (GET) or write scope of the record the note is attached to, e.g. `contacts:read`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Note" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "contact", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write", "companies:write", "deals:write", "leads:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdate" }, "example": { "body": "Called Ada — discount confirmed, proposal sent." } } } } }, "delete": { "operationId": "deleteNote", "summary": "Delete a note", "description": "Deletes the note permanently (notes do not go to the Trash, as in the app). Only the note's author or an admin can delete it.\n\nThe read (GET) or write scope of the record the note is attached to, e.g. `contacts:read`.", "tags": [ "Notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The note's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:write", "companies:write", "deals:write", "leads:write" ] } }, "/users": { "get": { "operationId": "listUsers", "summary": "List users", "description": "The users of the workspace, active and removed, oldest first — use their ids as `owner_id` and in `assignee_ids`. Assign records only to users with `is_active: true`.\n\nScope: `users:read`.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "full_name": "Grace Hopper", "email": "grace@acme.example", "role": "manager", "avatar_url": null, "is_active": true } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "users:read" ], "x-nextora-list": { "filters": [], "sortable": [ "created_at" ], "default_sort": "created_at", "default_order": "asc", "advanced_filter": false } } }, "/custom-fields": { "get": { "operationId": "listCustomFields", "summary": "List custom fields", "description": "The custom-field definitions of one record type, in display order. Not paginated. The Tags field of contacts and companies is their top-level `tags` array, so it is not listed for them.\n\nThe read scope of the record type: `contacts:read` for `contact`, `deals:read` for `deal`, and so on.", "tags": [ "Custom fields" ], "parameters": [ { "name": "entity", "in": "query", "required": true, "description": "The record type: contact, company, deal, lead or task.", "schema": { "type": "string", "enum": [ "contact", "company", "deal", "lead", "task" ] }, "example": "contact" } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "key": "budget_range", "label": "Budget range", "type": "select", "options": [ { "id": "50k_100k", "label": "50k–100k", "color": "#3B82F6" } ], "required": false, "entity": "deal" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "contacts:read", "companies:read", "deals:read", "leads:read", "tasks:read" ] } }, "/analytics/forecast": { "get": { "operationId": "getForecast", "summary": "Sales forecast", "description": "Open deals (status in_progress or on_hold) whose expected close date falls in the period, grouped by forecast category. Deals without a category count as `pipeline`; `omit` deals, won/lost deals and deals in the Trash are excluded. `owner_id` matches the deal's primary owner. Values are added as stored, without currency conversion. Accepts `analytics:read` (and `deals:read` for compatibility); the key's owner needs a role that may view deals and analytics.\n\nScope: `analytics:read` or `deals:read`. Part of the **analytics** hub.", "tags": [ "Forecast" ], "parameters": [ { "name": "period_start", "in": "query", "required": true, "description": "First day of the period.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "period_end", "in": "query", "required": true, "description": "Last day of the period (inclusive).", "schema": { "type": "string", "format": "date" }, "example": "2026-12-31" }, { "name": "owner_id", "in": "query", "required": false, "description": "Only deals owned by this user.", "schema": { "type": "string", "format": "uuid" } }, { "name": "pipeline_id", "in": "query", "required": false, "description": "Only deals in this pipeline.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Forecast" } } }, "example": { "data": { "period": { "start": "2026-10-01", "end": "2026-12-31" }, "categories": [ { "category": "commit", "deal_count": 3, "total_value": 96000, "weighted_value": 76800, "avg_probability": 80 }, { "category": "best_case", "deal_count": 2, "total_value": 40000, "weighted_value": 20000, "avg_probability": 50 }, { "category": "pipeline", "deal_count": 5, "total_value": 75000, "weighted_value": 15000, "avg_probability": 20 } ], "totals": { "commit": 96000, "best_case": 136000, "weighted": 111800, "pipeline": 211000, "deal_count": 10 }, "deals": [ { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "probability": 80, "expected_close_date": "2026-11-30", "forecast_category": "commit", "stage": "Negotiation", "company_name": "Analytical Engines Ltd" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "analytics:read", "deals:read" ], "x-nextora-hub": "analytics" } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook subscriptions", "description": "The workspace's webhook subscriptions the key owner can manage, newest first. Secrets are never included.\n\nScope: `webhooks:read`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100; default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-02T10:30:00.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:read" ] }, "post": { "operationId": "createWebhook", "summary": "Create a webhook subscription", "description": "Subscribes an HTTPS endpoint to events and returns its signing `secret` — the only time it is shown, apart from rotation. Verify every delivery's `Nextora-Signature` header with it. The URL must be `https://` on a public host: an address that is or resolves to a private, loopback, link-local or metadata network is refused. The secret is never stored for an `Idempotency-Key` replay: retrying with the same key answers 409 `idempotency_key_reused` (`details.reason`: `not_replayable`, `details.resource_id`: the subscription).\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": null, "last_success_at": null, "last_failure_at": null, "created_at": "2026-10-10T09:00:00.000Z", "updated_at": "2026-10-10T09:00:00.000Z", "secret": "whsec_9f3b7c1e5a2d8f4b6c0e3a7d1f5b9c2e8a4d6f0b3c7e1a5d" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-nextora-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreate" }, "example": { "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ] } } } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Retrieve a webhook subscription", "description": "One subscription, without its secret.\n\nScope: `webhooks:read`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-02T10:30:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:read" ] }, "put": { "operationId": "updateWebhookPut", "summary": "Update a webhook subscription (PUT)", "description": "Same as `PATCH /webhooks/{id}` — both are partial updates.\n\nChanges the fields you send (PUT behaves the same). To resume a subscription Nextora paused after three days of failures, send `is_active: true`: that clears `paused_at`, `paused_reason` and `failing_since`. A new `url` clears `failing_since` too, and is checked like on create.\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-02T10:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" }, "example": { "events": [ "deal.stage_changed", "deal.won", "deal.lost", "deal.created" ] } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook subscription", "description": "Changes the fields you send (PUT behaves the same). To resume a subscription Nextora paused after three days of failures, send `is_active: true`: that clears `paused_at`, `paused_reason` and `failing_since`. A new `url` clears `failing_since` too, and is checked like on create.\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-02T10:30:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:write" ], "requestBody": { "required": true, "description": "Unknown fields are ignored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionUpdate" }, "example": { "events": [ "deal.stage_changed", "deal.won", "deal.lost", "deal.created" ] } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook subscription", "description": "Deletes the subscription; Nextora stops sending its events. Cannot be undone.\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "deleted": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:write" ] } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Replaces the signing secret and returns the subscription with the new `secret`, once. The old secret stops working at once — there is no overlap window: every later delivery is signed with the new secret only. Deploy it to your endpoint straight away; deliveries your endpoint rejects meanwhile are retried. Like on create, the secret is never stored for an `Idempotency-Key` replay (409 `not_replayable`).\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" } } }, "example": { "data": { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-10T10:05:18.000Z", "secret": "whsec_2e8a4d6f0b3c7e1a5d9f3b7c1e5a2d8f4b6c0e3a7d1f5b9c" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-nextora-scopes": [ "webhooks:write" ] } }, "/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "description": "Sends a `webhook.test` event to the subscription's URL right away — signed, with the same headers as a real event — and returns the delivery, so you can check your endpoint end to end.\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "example": { "data": { "id": "a4c6e8f0-2b4d-4f6a-8c0e-2d4f6b8a0c19", "event": "webhook.test", "status": "success", "attempts": 1, "response_code": 200, "next_retry_at": null, "created_at": "2026-10-10T09:02:11.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:write" ] } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List deliveries", "description": "The subscription's deliveries, newest first: what was sent, whether it arrived, and when the next retry is due.\n\nScope: `webhooks:read`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The subscription's id.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100; default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.next_cursor` of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of results.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "d8e0f2a4-6b8c-4d1e-9f3a-7c9e1b3d5f82", "event": "deal.stage_changed", "status": "retrying", "attempts": 2, "response_code": 502, "next_retry_at": "2026-10-10T09:21:04.000Z", "created_at": "2026-10-10T09:15:02.000Z" } ], "meta": { "limit": 50, "has_more": false, "next_cursor": null, "total": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:read" ] } }, "/webhooks/deliveries/{id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a delivery", "description": "Sends a delivery again now — a `failed` one after you fixed your endpoint, or a `retrying` one without waiting for its next attempt — and returns it with the result of this attempt. The retry is the delivery's next attempt: `attempts` and `Nextora-Attempt` go up by one, so a delivery that failed after six attempts is retried as attempt 7.\n\nScope: `webhooks:write`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The delivery's id.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "OK.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "example": { "data": { "id": "c6e8a0b2-4d6f-4a8c-9e2b-6f8a0c2e4b31", "event": "deal.won", "status": "success", "attempts": 7, "response_code": 200, "next_retry_at": null, "created_at": "2026-10-08T17:30:45.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-nextora-scopes": [ "webhooks:write" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_…", "description": "An API key from Settings → Developers → API keys, sent as `Authorization: Bearer sk_live_…`. The key acts as its owner: same role permissions and record visibility as in the app, narrowed by the key's scopes." } }, "schemas": { "Company": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "industry": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ], "description": "Head-count band, e.g. `1-10`, `51-200`." }, "owner_id": { "type": "string", "format": "uuid", "description": "The primary owner — the user responsible for the company." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names." }, "custom_fields": { "$ref": "#/components/schemas/CustomFieldValues" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "industry", "website", "phone", "email", "address", "description", "size", "owner_id", "tags", "custom_fields", "created_at", "updated_at" ], "examples": [ { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd", "industry": "Computing", "website": "https://analytical-engines.example", "phone": "+44 20 7946 0000", "email": "hello@analytical-engines.example", "address": "12 St James's Square, London", "description": "Builds general-purpose calculating machines.", "size": "51-200", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "Enterprise" ], "custom_fields": { "annual_revenue": 12500000 }, "created_at": "2026-08-02T10:00:00.000Z", "updated_at": "2026-10-01T12:30:00.000Z" } ] }, "CompanyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "industry": { "type": [ "string", "null" ], "maxLength": 200 }, "website": { "type": [ "string", "null" ], "maxLength": 500, "description": "A web address; `https://` is added when missing." }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "address": { "type": [ "string", "null" ], "maxLength": 1000 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "size": { "type": [ "string", "null" ], "maxLength": 50 }, "owner_id": { "type": "string", "format": "uuid", "description": "Defaults to the API key's owner." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Tag names. Replaces the record's tags. A name the workspace has not used yet is created when the key owner may manage fields; otherwise it is rejected." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "required": [ "name" ], "examples": [ { "name": "Analytical Engines Ltd", "industry": "Computing", "website": "analytical-engines.example", "size": "51-200" } ] }, "CompanyUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "industry": { "type": [ "string", "null" ], "maxLength": 200 }, "website": { "type": [ "string", "null" ], "maxLength": 500, "description": "A web address; `https://` is added when missing." }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "address": { "type": [ "string", "null" ], "maxLength": 1000 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "size": { "type": [ "string", "null" ], "maxLength": 50 }, "owner_id": { "type": "string", "format": "uuid", "description": "Defaults to the API key's owner." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Tag names. Replaces the record's tags. A name the workspace has not used yet is created when the key owner may manage fields; otherwise it is rejected." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "examples": [ { "size": "201-500", "tags": [ "Enterprise", "Renewal 2027" ] } ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "first_name": { "type": "string" }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ], "description": "First and last name, computed by the server." }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ], "description": "Job title." }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "company": { "anyOf": [ { "$ref": "#/components/schemas/RecordRef" }, { "type": "null" } ], "description": "The linked company, if any." }, "owner_id": { "type": "string", "format": "uuid", "description": "The primary owner — the user responsible for the contact." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names." }, "source": { "type": [ "string", "null" ], "description": "Where the contact came from (free text)." }, "custom_fields": { "$ref": "#/components/schemas/CustomFieldValues" }, "last_activity_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last logged activity (call, email, note, task …)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "first_name", "last_name", "full_name", "email", "phone", "position", "company_id", "company", "owner_id", "tags", "source", "custom_fields", "last_activity_at", "created_at", "updated_at" ], "examples": [ { "id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "first_name": "Ada", "last_name": "Lovelace", "full_name": "Ada Lovelace", "email": "ada@analytical-engines.example", "phone": "+44 20 7946 0958", "position": "Head of Research", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "company": { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" }, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "tags": [ "VIP", "Partner" ], "source": "conference", "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" }, "last_activity_at": "2026-10-09T15:42:10.000Z", "created_at": "2026-09-14T08:12:44.000Z", "updated_at": "2026-10-09T15:42:10.000Z" } ] }, "ContactCreate": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "last_name": { "type": [ "string", "null" ], "maxLength": 200 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "position": { "type": [ "string", "null" ], "maxLength": 200 }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Link to a company the key owner can see." }, "owner_id": { "type": "string", "format": "uuid", "description": "Defaults to the API key's owner." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Tag names. Replaces the record's tags. A name the workspace has not used yet is created when the key owner may manage fields; otherwise it is rejected." }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "required": [ "first_name" ], "examples": [ { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@analytical-engines.example", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "tags": [ "VIP" ], "custom_fields": { "linkedin": "https://www.linkedin.com/in/ada-lovelace" } } ] }, "ContactUpdate": { "type": "object", "properties": { "first_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "last_name": { "type": [ "string", "null" ], "maxLength": 200 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "position": { "type": [ "string", "null" ], "maxLength": 200 }, "company_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Link to a company the key owner can see." }, "owner_id": { "type": "string", "format": "uuid", "description": "Reassign the contact (the new owner is notified, as in the app)." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 50, "description": "Tag names. Replaces the record's tags. A name the workspace has not used yet is created when the key owner may manage fields; otherwise it is rejected." }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "examples": [ { "position": "CTO", "tags": [ "VIP", "Partner" ], "custom_fields": { "linkedin": null } } ] }, "CustomField": { "type": "object", "properties": { "key": { "type": "string", "description": "Key in the records' `custom_fields`." }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "long_text", "number", "currency", "percent", "date", "datetime", "select", "multi_select", "checkbox", "url", "email", "phone", "user", "relation", "tags", "formula", "lookup" ], "description": "`formula` and `lookup` fields are computed and read-only." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldOption" }, "description": "Choices of `select`, `multi_select` and `tags` fields; empty for other types. Records store the option `id`." }, "required": { "type": "boolean" }, "entity": { "type": "string", "enum": [ "contact", "company", "deal", "lead", "task" ] } }, "required": [ "key", "label", "type", "options", "required", "entity" ], "examples": [ { "key": "budget_range", "label": "Budget range", "type": "select", "options": [ { "id": "under_50k", "label": "Under 50k", "color": "#9CA3AF" }, { "id": "50k_100k", "label": "50k–100k", "color": "#3B82F6" } ], "required": false, "entity": "deal" } ] }, "CustomFieldOption": { "type": "object", "properties": { "id": { "type": "string", "description": "The value stored on records." }, "label": { "type": "string" }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "label", "color" ], "examples": [ { "id": "50k_100k", "label": "50k–100k", "color": "#3B82F6" } ] }, "CustomFieldValues": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key (see GET /custom-fields). Select fields hold option ids; multi-selects hold arrays of option ids; dates are YYYY-MM-DD.", "examples": [ { "budget_range": "50k_100k", "renewal_date": "2027-01-31" } ] }, "Deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "value": { "type": "number", "description": "Amount in `currency`." }, "currency": { "type": "string", "description": "ISO 4217 code." }, "status": { "type": "string", "enum": [ "in_progress", "won", "lost", "on_hold" ], "description": "Outcome, independent of the stage." }, "pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "stage_id": { "type": [ "string", "null" ], "format": "uuid" }, "pipeline": { "anyOf": [ { "$ref": "#/components/schemas/RecordRef" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "$ref": "#/components/schemas/DealStageRef" }, { "type": "null" } ] }, "probability": { "type": "number", "description": "Win probability, 0–100." }, "expected_close_date": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set automatically when status becomes won or lost; cleared on reopen." }, "forecast_category": { "type": [ "string", "null" ], "enum": [ "commit", "best_case", "pipeline", "omit", null ], "description": "Null counts as `pipeline` in the forecast." }, "loss_reason": { "type": [ "string", "null" ] }, "competitor": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The primary owner; null when unassigned." }, "custom_fields": { "$ref": "#/components/schemas/CustomFieldValues" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "value", "currency", "status", "pipeline_id", "stage_id", "pipeline", "stage", "probability", "expected_close_date", "closed_at", "forecast_category", "loss_reason", "competitor", "contact_id", "company_id", "owner_id", "custom_fields", "created_at", "updated_at" ], "examples": [ { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "status": "in_progress", "pipeline_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "pipeline": { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales" }, "stage": { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" }, "probability": 60, "expected_close_date": "2026-11-30", "closed_at": null, "forecast_category": "commit", "loss_reason": null, "competitor": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "seats": 40 }, "created_at": "2026-09-20T09:00:00.000Z", "updated_at": "2026-10-03T11:20:00.000Z" } ] }, "DealCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217. Defaults to the workspace currency." }, "status": { "type": "string", "enum": [ "in_progress", "won", "lost", "on_hold" ] }, "pipeline_id": { "type": "string", "format": "uuid", "description": "Defaults to the default pipeline (see GET /pipelines)." }, "stage_id": { "type": "string", "format": "uuid", "description": "Defaults to the pipeline's first stage. Must belong to the pipeline." }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "closed_at": { "type": [ "string", "null" ] }, "forecast_category": { "type": [ "string", "null" ], "enum": [ "commit", "best_case", "pipeline", "omit", null ] }, "loss_reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "competitor": { "type": [ "string", "null" ], "maxLength": 300 }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." }, "owner_id": { "type": "string", "format": "uuid", "description": "Defaults to the API key's owner." } }, "required": [ "title" ], "examples": [ { "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "expected_close_date": "2026-11-30", "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "company_id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e" } ] }, "DealStageRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "`won` / `lost` for terminal columns, otherwise `open`." } }, "required": [ "id", "name", "type" ], "examples": [ { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "type": "open" } ] }, "DealUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO 4217. Defaults to the workspace currency." }, "status": { "type": "string", "enum": [ "in_progress", "won", "lost", "on_hold" ] }, "pipeline_id": { "type": "string", "format": "uuid", "description": "Move to another pipeline (lands on its first stage unless stage_id is given)." }, "stage_id": { "type": "string", "format": "uuid", "description": "Move the deal like a card on the board: stage entry time, stage automations and events follow." }, "probability": { "type": "integer", "minimum": 0, "maximum": 100 }, "expected_close_date": { "type": [ "string", "null" ], "format": "date" }, "closed_at": { "type": [ "string", "null" ] }, "forecast_category": { "type": [ "string", "null" ], "enum": [ "commit", "best_case", "pipeline", "omit", null ] }, "loss_reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "competitor": { "type": [ "string", "null" ], "maxLength": 300 }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "company_id": { "type": [ "string", "null" ], "format": "uuid" }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Reassign; null unassigns." } }, "examples": [ { "stage_id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "probability": 60, "forecast_category": "commit" } ] }, "Deleted": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "const": true, "type": "boolean" } }, "required": [ "id", "deleted" ], "examples": [ { "id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f", "deleted": true } ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "insufficient_scope", "forbidden", "not_found", "validation_failed", "invalid_json", "idempotency_key_reused", "rate_limited", "hub_not_in_plan", "workspace_read_only", "internal_error", "service_unavailable" ], "description": "Stable, machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation. May change; do not parse it." }, "details": { "type": "object", "additionalProperties": true, "description": "Structured context. For `validation_failed`: field → list of messages. For `rate_limited`: `retry_after`. For `insufficient_scope`: `required_scopes`. For `hub_not_in_plan`: `hub`, `upgrade_url`." }, "request_id": { "type": "string", "description": "The request's X-Request-Id — quote it when contacting support." } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ], "examples": [ { "error": { "code": "validation_failed", "message": "The request is invalid.", "details": { "email": [ "Must be a valid email address." ] }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } ] }, "Forecast": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string", "description": "First day, inclusive." }, "end": { "type": "string", "description": "Last day, inclusive." } }, "required": [ "start", "end" ] }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "commit", "best_case", "pipeline" ] }, "deal_count": { "type": "integer" }, "total_value": { "type": "number" }, "weighted_value": { "type": "number", "description": "Σ value × probability / 100." }, "avg_probability": { "type": "number" } }, "required": [ "category", "deal_count", "total_value", "weighted_value", "avg_probability" ] }, "description": "One line per forecast category, always all three." }, "totals": { "type": "object", "properties": { "commit": { "type": "number", "description": "Total value of commit deals." }, "best_case": { "type": "number", "description": "Commit + best case." }, "weighted": { "type": "number", "description": "Probability-weighted value of all open deals in the period." }, "pipeline": { "type": "number", "description": "Commit + best case + pipeline." }, "deal_count": { "type": "integer" } }, "required": [ "commit", "best_case", "weighted", "pipeline", "deal_count" ] }, "deals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string", "description": "ISO 4217 code." }, "probability": { "type": "integer", "description": "Win probability in percent." }, "expected_close_date": { "type": "string", "description": "YYYY-MM-DD, inside the period." }, "forecast_category": { "type": "string", "enum": [ "commit", "best_case", "pipeline" ], "description": "The category it counts in — `pipeline` when the deal has none." }, "stage": { "type": [ "string", "null" ], "description": "Name of the deal's stage." }, "company_name": { "type": [ "string", "null" ], "description": "Name of the deal's company." } }, "required": [ "id", "title", "value", "currency", "probability", "expected_close_date", "forecast_category", "stage", "company_name" ] }, "description": "The open deals behind the numbers, largest first." } }, "required": [ "period", "categories", "totals", "deals" ], "examples": [ { "period": { "start": "2026-10-01", "end": "2026-12-31" }, "categories": [ { "category": "commit", "deal_count": 3, "total_value": 96000, "weighted_value": 76800, "avg_probability": 80 }, { "category": "best_case", "deal_count": 2, "total_value": 40000, "weighted_value": 20000, "avg_probability": 50 }, { "category": "pipeline", "deal_count": 5, "total_value": 75000, "weighted_value": 15000, "avg_probability": 20 } ], "totals": { "commit": 96000, "best_case": 136000, "weighted": 111800, "pipeline": 211000, "deal_count": 10 }, "deals": [ { "id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "title": "Analytical Engines — annual licence", "value": 48000, "currency": "EUR", "probability": 80, "expected_close_date": "2026-11-30", "forecast_category": "commit", "stage": "Negotiation", "company_name": "Analytical Engines Ltd" } ] } ] }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`new`, `contacted`, `qualified`, `proposal`, `negotiation`, `won`, `lost`, or a custom status of the workspace." }, "source": { "type": [ "string", "null" ], "description": "E.g. `website`, `referral`, `cold_call`, `advertisement`, `social`, `event`, `email`, `other`." }, "score": { "type": "number", "description": "Lead score computed by the workspace's scoring rules. Read-only." }, "owner_id": { "type": [ "string", "null" ], "format": "uuid" }, "custom_fields": { "$ref": "#/components/schemas/CustomFieldValues" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "phone", "company_name", "status", "source", "score", "owner_id", "custom_fields", "created_at", "updated_at" ], "examples": [ { "id": "0f9e8d7c-6b5a-4f4e-8d3c-2b1a0f9e8d7c", "name": "Charles Babbage", "email": "charles@difference.example", "phone": "+44 20 7946 0101", "company_name": "Difference Engines", "status": "new", "source": "website", "score": 35, "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "custom_fields": { "budget": 20000 }, "created_at": "2026-10-10T07:45:00.000Z", "updated_at": "2026-10-10T07:45:00.000Z" } ] }, "LeadCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "company_name": { "type": [ "string", "null" ], "maxLength": 300 }, "status": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Defaults to `new`. Must be a status the workspace knows." }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Defaults to the API key's owner; null leaves the lead unassigned." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "required": [ "name" ], "examples": [ { "name": "Charles Babbage", "email": "charles@difference.example", "company_name": "Difference Engines", "source": "website", "custom_fields": { "budget": 20000 } } ] }, "LeadUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 300 }, "email": { "type": [ "string", "null" ], "maxLength": 320, "format": "email" }, "phone": { "type": [ "string", "null" ], "maxLength": 50 }, "company_name": { "type": [ "string", "null" ], "maxLength": 300 }, "status": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Defaults to `new`. Must be a status the workspace knows." }, "source": { "type": [ "string", "null" ], "maxLength": 100 }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Defaults to the API key's owner; null leaves the lead unassigned." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "examples": [ { "status": "qualified", "custom_fields": { "budget": 25000 } } ] }, "Note": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "description": "Plain text / Markdown." }, "record_type": { "type": "string", "enum": [ "contact", "company", "deal", "lead" ], "description": "Type of the record the note is attached to." }, "record_id": { "type": "string", "format": "uuid", "description": "Id of the record the note is attached to." }, "author_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "body", "record_type", "record_id", "author_id", "created_at", "updated_at" ], "examples": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "body": "Called Ada — wants the volume discount in writing by Friday.", "record_type": "contact", "record_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "author_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "created_at": "2026-10-10T10:15:00.000Z", "updated_at": "2026-10-10T10:15:00.000Z" } ] }, "NoteCreate": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 50000 } }, "required": [ "body" ], "examples": [ { "body": "Called Ada — wants the volume discount in writing by Friday." } ] }, "NoteUpdate": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 50000 } }, "required": [ "body" ], "examples": [ { "body": "Called Ada — discount confirmed, proposal sent." } ] }, "PageMeta": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Page size used." }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to get the next page; null on the last page." }, "total": { "type": "integer", "description": "Number of matching records. Returned on the first page (no cursor) and in offset mode." }, "offset": { "type": "integer", "description": "Echoed in offset mode." } }, "required": [ "limit", "has_more", "next_cursor" ], "examples": [ { "limit": 50, "has_more": true, "next_cursor": "eyJzIjoiY3JlYXRlZF9hdCIsIm8iOiJkZXNjIiwidiI6IjIwMjYtMTAtMDlUMTQ6MDA6MDAuMDAwWiIsImkiOiIwYjJm...", "total": 132 } ] }, "Pipeline": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_default": { "type": "boolean", "description": "The pipeline a new deal lands in when no pipeline_id is given." }, "currency": { "type": [ "string", "null" ], "description": "The pipeline's own currency (ISO 4217) when one is set; null — deals use their own `currency`." }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" }, "description": "Stages in board order." } }, "required": [ "id", "name", "is_default", "currency", "stages" ], "examples": [ { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Sales", "is_default": true, "currency": null, "stages": [ { "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "name": "Lead", "position": 0, "type": "open", "probability": null, "color": "#6B7280" }, { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "position": 1, "type": "open", "probability": null, "color": "#F97316" }, { "id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a", "name": "Won", "position": 2, "type": "won", "probability": null, "color": "#10B981" }, { "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c", "name": "Lost", "position": 3, "type": "lost", "probability": null, "color": "#EF4444" } ] } ] }, "PipelineStage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "position": { "type": "integer", "description": "Order on the board, from 0." }, "type": { "type": "string", "enum": [ "open", "won", "lost" ], "description": "`won` / `lost` for terminal columns, otherwise `open`." }, "probability": { "type": [ "integer", "null" ], "description": "Default win probability of deals in this stage, in percent; null when the stage sets none." }, "color": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "position", "type", "probability", "color" ], "examples": [ { "id": "9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f", "name": "Negotiation", "position": 3, "type": "open", "probability": null, "color": "#F97316" } ] }, "RecordRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "examples": [ { "id": "2b0c1d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "name": "Analytical Engines Ltd" } ] }, "Task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Workflow state; kept in sync with the task's board column." }, "status_category": { "type": [ "string", "null" ], "enum": [ "backlog", "unstarted", "started", "completed", "canceled", null ], "description": "Category of the board column (`completed` vs `canceled` tells finished work from dropped work). Null in spaces without custom columns." }, "priority": { "type": [ "string", "null" ], "description": "Priority key: `low`, `medium`, `high`, or a custom priority of the workspace. Null = none." }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "When work starts (the left end of the Gantt bar)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "space_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The task space (board) the task lives in." }, "parent_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set on subtasks." }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "owner_id": { "type": "string", "format": "uuid", "description": "The primary responsible user." }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Everyone responsible for the task (the app's Responsible set), primary owner first." }, "custom_fields": { "$ref": "#/components/schemas/CustomFieldValues" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "description", "status", "status_category", "priority", "due_date", "start_date", "completed_at", "project_id", "space_id", "parent_task_id", "contact_id", "deal_id", "owner_id", "assignee_ids", "custom_fields", "created_at", "updated_at" ], "examples": [ { "id": "7b6a5f4e-3d2c-4b1a-9f8e-7d6c5b4a3f2e", "title": "Send the licence proposal", "description": "Include the volume discount discussed on the call.", "status": "in_progress", "status_category": "started", "priority": "high", "due_date": "2026-10-15T17:00:00.000Z", "start_date": "2026-10-10T09:00:00.000Z", "completed_at": null, "project_id": null, "space_id": "4c3b2a1f-0e9d-4c8b-8a7f-6e5d4c3b2a1f", "parent_task_id": null, "contact_id": "8d3f2a1b-6c4e-4f7a-9b2d-1e0c3a5b7d9f", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b", "owner_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "assignee_ids": [ "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d" ], "custom_fields": { "effort": 3 }, "created_at": "2026-10-09T16:00:00.000Z", "updated_at": "2026-10-10T09:05:00.000Z" } ] }, "TaskCreate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Moves the task to the matching column of its space." }, "priority": { "type": [ "string", "null" ], "maxLength": 100, "description": "A priority key or name (`low`, `medium`, `high` or a custom one); null clears it." }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "space_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Defaults to the workspace's default space." }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "owner_id": { "type": "string", "format": "uuid", "description": "Primary responsible user. Defaults to the API key's owner." }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Replace the whole Responsible set. The owner is always part of it." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." }, "parent_task_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Create as a subtask of this task (one level of nesting)." } }, "required": [ "title" ], "examples": [ { "title": "Send the licence proposal", "due_date": "2026-10-15", "priority": "high", "deal_id": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b" } ] }, "TaskUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": { "type": [ "string", "null" ], "maxLength": 10000 }, "status": { "type": "string", "enum": [ "todo", "in_progress", "done" ], "description": "Moves the task to the matching column of its space." }, "priority": { "type": [ "string", "null" ], "maxLength": 100, "description": "A priority key or name (`low`, `medium`, `high` or a custom one); null clears it." }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "space_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Defaults to the workspace's default space." }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "deal_id": { "type": [ "string", "null" ], "format": "uuid" }, "owner_id": { "type": "string", "format": "uuid", "description": "Primary responsible user. Defaults to the API key's owner." }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Replace the whole Responsible set. The owner is always part of it." }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values keyed by the field key. MERGED into the stored values: keys you omit stay as they are, `null` clears a key. Unknown keys are rejected. Select options may be given by id or by label." } }, "examples": [ { "status": "done" } ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Use as `owner_id` / in `assignee_ids`." }, "full_name": { "type": "string", "description": "Name as shown in the app (the email when the member has not set a name)." }, "email": { "type": "string", "description": "Sign-in email." }, "role": { "type": "string", "description": "The member's role: `admin`, `manager`, `user`, or the name of a custom role." }, "avatar_url": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean", "description": "`false` once the member has been removed from the workspace. Assign records only to active users." } }, "required": [ "id", "full_name", "email", "role", "avatar_url", "is_active" ], "examples": [ { "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "full_name": "Grace Hopper", "email": "grace@acme.example", "role": "manager", "avatar_url": null, "is_active": true } ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "description": "The event type delivered (`webhook.test` for a test event)." }, "status": { "type": "string", "enum": [ "pending", "retrying", "success", "failed" ], "description": "`success` after a 2xx; `retrying` while automatic attempts remain; `failed` after the sixth; `pending` before the first." }, "attempts": { "type": "integer", "description": "The number of the latest attempt, as sent in `Nextora-Attempt`. Automatic retries stop at 6; each manual retry adds one, so it can go past 6." }, "response_code": { "type": [ "integer", "null" ], "description": "The HTTP status your endpoint returned on the last attempt; null when it did not answer within 10 seconds." }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt is due, while `status` is `retrying`." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event was queued for this subscription." } }, "required": [ "id", "event", "status", "attempts", "response_code", "next_retry_at", "created_at" ], "examples": [ { "id": "d8e0f2a4-6b8c-4d1e-9f3a-7c9e1b3d5f82", "event": "deal.stage_changed", "status": "retrying", "attempts": 2, "response_code": 502, "next_retry_at": "2026-10-10T09:21:04.000Z", "created_at": "2026-10-10T09:15:02.000Z" } ] }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "A name for your own reference." }, "url": { "type": "string", "description": "Where Nextora sends events: an `https://` URL without a username or password." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.updated", "task.completed", "task.deleted", "lead.created", "lead.updated", "lead.deleted", "note.created" ] }, "description": "The event types sent to this subscription." }, "is_active": { "type": "boolean", "description": "Whether events are sent. Nextora sets it to `false` when it pauses a subscription whose deliveries have failed for three days; set it back to `true` to resume." }, "paused_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Nextora paused the subscription; null when it is not paused. Changing `is_active` yourself clears it." }, "paused_reason": { "type": [ "string", "null" ], "enum": [ "failing", null ], "description": "`failing` when Nextora paused the subscription because its deliveries kept failing; null otherwise." }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current run of failed attempts began. Cleared by a successful delivery, by resuming, and by a new `url`. Three days of it pause the subscription." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery last succeeded." }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery attempt last failed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "url", "events", "is_active", "paused_at", "paused_reason", "failing_since", "last_success_at", "last_failure_at", "created_at", "updated_at" ], "examples": [ { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": "2026-10-10T09:15:03.000Z", "last_success_at": "2026-10-10T08:47:31.000Z", "last_failure_at": "2026-10-10T09:16:04.000Z", "created_at": "2026-10-02T10:30:00.000Z", "updated_at": "2026-10-02T10:30:00.000Z" } ] }, "WebhookSubscriptionCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "An `https://` URL on a public host, without a username or password." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.updated", "task.completed", "task.deleted", "lead.created", "lead.updated", "lead.deleted", "note.created" ] }, "minItems": 1, "maxItems": 20 }, "is_active": { "type": "boolean", "description": "Default true. `false` creates the subscription switched off." } }, "required": [ "name", "url", "events" ], "examples": [ { "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ] } ] }, "WebhookSubscriptionUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "An `https://` URL on a public host. A new URL clears `failing_since`." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.updated", "task.completed", "task.deleted", "lead.created", "lead.updated", "lead.deleted", "note.created" ] }, "minItems": 1, "maxItems": 20 }, "is_active": { "type": "boolean", "description": "`false` stops deliveries without deleting the subscription; `true` resumes it — after an automatic pause too, which clears `paused_at`, `paused_reason` and `failing_since`." } }, "examples": [ { "events": [ "deal.stage_changed", "deal.won", "deal.lost", "deal.created" ] } ] }, "WebhookSubscriptionWithSecret": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "A name for your own reference." }, "url": { "type": "string", "description": "Where Nextora sends events: an `https://` URL without a username or password." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.updated", "task.completed", "task.deleted", "lead.created", "lead.updated", "lead.deleted", "note.created" ] }, "description": "The event types sent to this subscription." }, "is_active": { "type": "boolean", "description": "Whether events are sent. Nextora sets it to `false` when it pauses a subscription whose deliveries have failed for three days; set it back to `true` to resume." }, "paused_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When Nextora paused the subscription; null when it is not paused. Changing `is_active` yourself clears it." }, "paused_reason": { "type": [ "string", "null" ], "enum": [ "failing", null ], "description": "`failing` when Nextora paused the subscription because its deliveries kept failing; null otherwise." }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current run of failed attempts began. Cleared by a successful delivery, by resuming, and by a new `url`. Three days of it pause the subscription." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery last succeeded." }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery attempt last failed." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "The signing secret (`whsec_…`). Returned only when the subscription is created and when the secret is rotated — store it then, and verify every delivery's `Nextora-Signature` with it." } }, "required": [ "id", "name", "url", "events", "is_active", "paused_at", "paused_reason", "failing_since", "last_success_at", "last_failure_at", "created_at", "updated_at", "secret" ], "examples": [ { "id": "f3a5c7e9-2b4d-4f6a-8c1e-5d7f9b1a3c60", "name": "Deal sync to billing", "url": "https://hooks.example.com/nextora", "events": [ "deal.stage_changed", "deal.won", "deal.lost" ], "is_active": true, "paused_at": null, "paused_reason": null, "failing_since": null, "last_success_at": null, "last_failure_at": null, "created_at": "2026-10-10T09:00:00.000Z", "updated_at": "2026-10-10T09:00:00.000Z", "secret": "whsec_9f3b7c1e5a2d8f4b6c0e3a7d1f5b9c2e8a4d6f0b3c7e1a5d" } ] } }, "parameters": { "limit": { "name": "limit", "in": "query", "description": "Page size, 1–100. Default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "cursor": { "name": "cursor", "in": "query", "description": "Opaque cursor from `meta.next_cursor` of the previous page. Keep `sort`, `order` and filters unchanged.", "schema": { "type": "string" } }, "offset": { "name": "offset", "in": "query", "description": "Skip this many records instead of using a cursor (accepted for compatibility; cursors are faster and stable).", "schema": { "type": "integer", "minimum": 0 } }, "filter": { "name": "filter", "in": "query", "description": "Advanced filter: a JSON object `{\"conjunction\":\"and\"|\"or\",\"conditions\":[{\"field\",\"operator\",\"value\"}]}`, URL-encoded or base64url. Fields: the filterable fields of this list or a custom field key. Operators: eq, neq, is_empty, is_not_empty, contains, not_contains, starts_with, ends_with, any_of, none_of, gt, gte, lt, lte, between, last_n_days, checked, not_checked.", "schema": { "type": "string" }, "example": "{\"conjunction\":\"and\",\"conditions\":[{\"field\":\"created_at\",\"operator\":\"last_n_days\",\"value\":30}]}" }, "Idempotency-Key": { "name": "Idempotency-Key", "in": "header", "description": "Any string up to 255 characters. Retrying with the same key and the same request within 24 hours replays the original response (with `Idempotent-Replayed: true`) instead of acting twice; the same key with a different request answers 409.", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "X-Request-Id": { "description": "Unique id of this request — quote it when contacting support.", "schema": { "type": "string" } }, "X-API-Version": { "description": "Date version of the API (`2026-10-10`).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requests allowed per window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "The request is invalid. Codes: `validation_failed`, `invalid_json`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "summary": "validation_failed", "value": { "error": { "code": "validation_failed", "message": "The request is invalid.", "details": { "email": [ "Must be a valid email address." ], "custom_fields.budget": [ "Must be a number." ] }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } }, "invalid_json": { "summary": "invalid_json", "value": { "error": { "code": "invalid_json", "message": "The request body is not valid JSON.", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "Unauthorized": { "description": "Missing, invalid, revoked or expired API key. Codes: `unauthorized`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthorized": { "summary": "unauthorized", "value": { "error": { "code": "unauthorized", "message": "Invalid, revoked or expired API key.", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "Forbidden": { "description": "The key may not do this: a missing scope, the owner's role, the plan, or a read-only workspace. Codes: `insufficient_scope`, `forbidden`, `hub_not_in_plan`, `workspace_read_only`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "code": "insufficient_scope", "message": "This API key lacks the required scope: contacts:write.", "details": { "required_scopes": [ "contacts:write" ] }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } }, "forbidden": { "summary": "forbidden", "value": { "error": { "code": "forbidden", "message": "The key owner's role does not allow this (contacts.delete).", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } }, "hub_not_in_plan": { "summary": "hub_not_in_plan", "value": { "error": { "code": "hub_not_in_plan", "message": "The \"sales\" hub is not part of this workspace's plan.", "details": { "hub": "sales", "upgrade_url": "https://account.nextora.co/i/acme/upgrade?hub=sales" }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } }, "workspace_read_only": { "summary": "workspace_read_only", "value": { "error": { "code": "workspace_read_only", "message": "This workspace is read-only: changes are disabled.", "details": { "lifecycle": "read_only" }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "NotFound": { "description": "Not found, in the Trash, or not visible to the key's owner. Codes: `not_found`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "Contact not found.", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "Conflict": { "description": "The Idempotency-Key belongs to another request, or that request is still running. Codes: `idempotency_key_reused`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with a different request.", "details": { "reason": "different_request" }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "TooManyRequests": { "description": "Rate limit exceeded: 500 requests a minute per API key. Requests without a valid key have small budgets of their own (30 a minute per address without a well-formed key, 30 a minute per key that is not valid). Codes: `rate_limited`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "summary": "rate_limited", "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry after the number of seconds in Retry-After.", "details": { "retry_after": 12 }, "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "InternalError": { "description": "Unexpected server error. Codes: `internal_error`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "code": "internal_error", "message": "An internal error occurred. Quote the request_id when contacting support.", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } }, "ServiceUnavailable": { "description": "A dependency of this endpoint is unavailable. Codes: `service_unavailable`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "service_unavailable", "value": { "error": { "code": "service_unavailable", "message": "This feature is temporarily unavailable.", "request_id": "5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05" } } } } } } } } }, "x-nextora": { "api_version": "2026-10-10", "documentation": "https://nextora.co/docs", "rate_limits": { "per_api_key": 500, "without_api_key": 60, "without_well_formed_key_per_address": 30, "invalid_key_lookups_per_key": 30, "invalid_key_lookups_per_address": 300, "window_seconds": 60 }, "pagination": { "default_limit": 50, "max_limit": 100, "max_in_values": 100 }, "filter_operators": [ "eq", "neq", "gt", "gte", "lt", "lte", "like", "in" ], "advanced_filter_operators": [ "eq", "neq", "is_empty", "is_not_empty", "contains", "not_contains", "starts_with", "ends_with", "any_of", "none_of", "gt", "gte", "lt", "lte", "between", "last_n_days", "checked", "not_checked" ], "idempotency": { "header": "Idempotency-Key", "max_length": 255, "ttl_hours": 24 }, "scopes": [ { "scope": "contacts:read", "description": "Read contacts and the notes on them." }, { "scope": "contacts:write", "description": "Create, update, delete and restore contacts; write their notes." }, { "scope": "companies:read", "description": "Read companies and the notes on them." }, { "scope": "companies:write", "description": "Create, update, delete and restore companies; write their notes." }, { "scope": "deals:read", "description": "Read deals, pipelines and stages, and the notes on deals." }, { "scope": "deals:write", "description": "Create, update, delete and restore deals; write their notes." }, { "scope": "tasks:read", "description": "Read tasks." }, { "scope": "tasks:write", "description": "Create, update, delete and restore tasks." }, { "scope": "leads:read", "description": "Read leads and the notes on them." }, { "scope": "leads:write", "description": "Create, update, delete and restore leads; write their notes." }, { "scope": "users:read", "description": "Read the members of the workspace." }, { "scope": "analytics:read", "description": "Read the sales forecast." }, { "scope": "webhooks:read", "description": "Read webhook subscriptions and their delivery log." }, { "scope": "webhooks:write", "description": "Create, change and delete webhook subscriptions; test, retry, rotate secrets." }, { "scope": "admin", "description": "Every scope. Only an admin of the workspace can create a key with it." } ], "errors": [ { "code": "unauthorized", "status": 401, "description": "The Authorization header is missing, or the API key is invalid, revoked or expired." }, { "code": "insufficient_scope", "status": 403, "description": "The API key is valid but lacks the scope this endpoint needs. `details.required_scopes` lists the accepted scopes." }, { "code": "forbidden", "status": 403, "description": "The key owner's role does not allow this action, or the record cannot be changed by them." }, { "code": "not_found", "status": 404, "description": "The record does not exist, is in the Trash, or is not visible to the key owner." }, { "code": "validation_failed", "status": 400, "description": "The request is well-formed JSON but a field, query parameter or filter is invalid. `details` maps each field to its messages." }, { "code": "invalid_json", "status": 400, "description": "The request body is not a valid JSON object." }, { "code": "idempotency_key_reused", "status": 409, "description": "The Idempotency-Key was already used with a different request, or that request is still being processed." }, { "code": "rate_limited", "status": 429, "description": "Too many requests for this API key. Wait `details.retry_after` seconds (also in the Retry-After header)." }, { "code": "hub_not_in_plan", "status": 403, "description": "The endpoint belongs to a hub that is not part of this workspace's plan. `details.upgrade_url` links to the upgrade page." }, { "code": "workspace_read_only", "status": 403, "description": "The workspace is read-only (its subscription lapsed): data can be read and exported, not changed. Creating leads keeps working." }, { "code": "internal_error", "status": 500, "description": "Something failed on our side. Retry later; quote the request_id when contacting support." }, { "code": "service_unavailable", "status": 503, "description": "A dependency this endpoint needs is not configured or temporarily unavailable. Retry later." } ], "webhook_events": [ "contact.created", "contact.updated", "contact.deleted", "company.created", "company.updated", "company.deleted", "deal.created", "deal.updated", "deal.deleted", "deal.stage_changed", "deal.won", "deal.lost", "task.created", "task.updated", "task.completed", "task.deleted", "lead.created", "lead.updated", "lead.deleted", "note.created" ] } }