Account Management REST API

Use the account-management API to manage assistants, knowledge, forms, contacts, widgets, and other supported resources from your own integration. The MCP server provides the same operations and permissions to MCP clients.

Create a key and check access

1. Select the company you want to manage, then open Settings → API Keys.
2. Create a key and assign the required BREAD permissions. For the examples below, assign all five permissions in Contact groups.
3. Save and copy the secret shown once. Keep it in your integration's secret storage.

Your account needs an active subscription with API integration access, company membership, and access to the resource operations you assign. Each request checks the key's current grants and its owner's current access. See API Settings for key creation, expiry, rotation, and migration.

The default API server is https://api.nviti.ng. For another installation, use the origin of the MCP endpoint displayed in API settings, without its /api/v1/account/mcp path.

export NVITI_API_BASE_URL='https://api.nviti.ng'
export NVITI_API_KEY='<YOUR_API_KEY>'

curl --fail-with-body --silent --show-error \
  "$NVITI_API_BASE_URL/api/v1/account/capabilities" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json'

Replace <YOUR_API_KEY> with the secret. The capabilities response contains a data array of the operations currently available to this credential, including each operation's permission, method, path, and MCP inputSchema. A valid key with no resource grants receives an empty array.

Authentication and company selection

Send these headers on every request:

Authorization: Bearer <API_KEY>
Accept: application/json

Add Content-Type: application/json for Add and Edit requests. The key supplies both the company and workspace context. Do not send company or workspace identifiers in the body. An X-Company-ID header is optional; if supplied, it must match the key's company ID or hash. It cannot switch companies.

Use a separate key for each company and integration. Account-management keys are accepted only by account-management routes. Other APIs, such as Outbound Messaging, have their own credential requirements.

BREAD endpoints

Replace {scope} with a supported scope and {id} with a positive integer resource ID.

Permissions are independent. Browse grants summary access; Read grants details. Edit and Add responses contain the submitted fields and resource identifiers, rather than all readable fields. Unsupported operations have no endpoint. Use the scope and field reference to check available operations and payloads.

Browse and search

curl --fail-with-body --silent --show-error \
  "$NVITI_API_BASE_URL/api/v1/account/contact_groups?page=1&per_page=20&search=Customers" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json'

Search matches a substring of the resource's summary field: name, or title for knowledge articles and documents. Results are ordered by ID. Unknown query parameters are rejected.

Example response, HTTP 200:

{
  "data": [
    {
      "id": 42,
      "name": "Customers",
      "created_at": "2026-10-02T09:00:00.000000Z",
      "updated_at": "2026-10-02T09:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Request each page through meta.last_page to collect all matches. Browse does not return a contact group's description; use Read for that detail.

Add, read, edit, and delete

The following example creates a contact group. It creates a real resource when run with your key.

curl --fail-with-body --silent --show-error \
  --request POST "$NVITI_API_BASE_URL/api/v1/account/contact_groups" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"name":"API demo group","description":"Created by an integration"}'

Add returns HTTP 201 with data.id, the supplied attributes, and created_at/updated_at. Save the returned ID for later operations:

export NVITI_RESOURCE_ID='<ID_FROM_ADD_RESPONSE>'

curl --fail-with-body --silent --show-error \
  "$NVITI_API_BASE_URL/api/v1/account/contact_groups/$NVITI_RESOURCE_ID" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json'

Read returns HTTP 200 with the permitted fields inside data. For a contact group, these are id, name, description, created_at, and updated_at.

Edit uses PATCH with a flat JSON object. Include only fields you want to change:

curl --fail-with-body --silent --show-error \
  --request PATCH "$NVITI_API_BASE_URL/api/v1/account/contact_groups/$NVITI_RESOURCE_ID" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Renamed API demo group"}'

Edit returns HTTP 200. This example returns id, name, and timestamps; it does not return the unchanged description. Sending a nested attributes object is an MCP convention and is invalid for REST.

Delete removes the addressed resource according to its existing deletion rules. To remove the group created above:

curl --fail-with-body --silent --show-error \
  --request DELETE "$NVITI_API_BASE_URL/api/v1/account/contact_groups/$NVITI_RESOURCE_ID" \
  -H "Authorization: Bearer $NVITI_API_KEY" \
  -H 'Accept: application/json'

Successful Delete returns HTTP 200:

{"data":{"id":42,"deleted":true}}

The example ID is illustrative. A later Read of a deleted resource returns 404. Check the exact resource ID before issuing Delete.

Validation and errors

Only the documented fields are accepted. Edit requires at least one attribute. Resource references, such as category_id or custom_agent_id, must belong to the same company and workspace as the key. Unknown attributes, invalid types, and unavailable references return 422. Existing resource business rules also apply.

For example, an invalid credential returns:

{"code":"UNAUTHENTICATED","message":"A valid account API key is required."}

Validation responses contain message and an errors map. Error paths can start with arguments.attributes. even for flat REST payloads, because REST and MCP share validation. For a key without API integration subscription access, the response includes code: SUBSCRIPTION_REQUIRED.

Rate limits and definition downloads

The default limit is 60 requests per minute per key, shared across REST, MCP, capabilities, and definition downloads. Subscription request allowances and tenant-wide API rate limits also apply. Derived tokens share their parent key's limit. Repeated invalid authentication is limited per IP address. A 429 response includes Retry-After.

The following GET endpoints require a valid, usable credential and API integration access, but do not require a separate BREAD grant:

See API Definition Exports for download commands and import instructions. Resource operations and key changes are audited without storing request contents or credentials.