API Reference

Welcome

The Nex Developer API provides programmatic access to your workspace’s context graph — the unified knowledge base Nex builds from your connected tools and ingested context. Use it to ingest new context, query the graph, manage entities and relationships, and stream AI-derived insights back into your own systems. Generate API keys from the Nex web UI and use them to authenticate requests.

Nex API Specification

View the complete OpenAPI specification

Authentication

All API endpoints are authenticated using API keys. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

All API requests should be made to:

https://app.nex.ai/api/developers

All versioned endpoints are prefixed with /v1/. For example, listing objects is GET https://app.nex.ai/api/developers/v1/objects.

Scopes

Each API key has specific scopes that control what operations it can perform. Request the scopes you need when generating your API key.

Scope	Description
`object.read`	Read object definitions and their attributes
`object.write`	Create, update, and delete object definitions, attributes, and lists
`record.read`	Read records, search, view timelines, and access knowledge graph
`record.write`	Create, update, and delete records and list memberships
`list.read`	Read list definitions
`list.member.read`	Read list members and records
`list.member.write`	Add, update, and remove list members
`relationship.read`	Read relationship definitions
`relationship.write`	Create and delete relationship definitions and instances
`task.read`	Read tasks
`task.write`	Create, update, and delete tasks
`note.read`	Read notes
`note.write`	Create, update, and delete notes
`integration.read`	List integrations and check connection status
`integration.write`	Connect and disconnect integrations
`notification.read`	Read notification preferences and custom notification rules
`notification.write`	Create, update, and delete notification preferences and custom rules
`insight.stream`	SSE insight streaming

Data Model Overview

Nex models your workspace as a knowledge graph. Entities are the nodes, relationships are the edges, and both are typed by definitions you control. The API lets you:

Define object types and their attributes (the graph’s schema)
Create records — the actual entities in the graph
Connect entities with typed relationships
Attach tasks, notes, and timeline events to any entity
Ingest unstructured context that is parsed, linked, and compounded into the graph over time

Core Resources

Objects (Entity Definitions)

Objects define the schema of entities in your graph. Think of them as the blueprints for the nodes Nex will store, query, and connect. Starter object types:

Person: individuals with attributes like name, email, job title, and links to other entities
Company: organizations with attributes like name, domain, and industry

Every workspace can extend the graph with its own object types via the Schema endpoints — for example, Project, Incident, or Playbook — each with their own attributes and relationships.

Records (Entities)

Records are instances of your object definitions - the actual data entries in your workspace. Example Person Record Response:

{
  "id": "789",
  "object_id": "123",
  "type": "person",
  "workspace_id": "456",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z",
  "attributes": {
    "name": "John Smith",
    "email_addresses": ["john@example.com", "j.smith@company.com"],
    "job_title": "Software Engineer"
  }
}

Note: For many attribute types like full_name, phone, and location, you can use either simple string values (e.g., "John Smith") or structured objects (e.g., {"first_name": "John", "last_name": "Smith"}). The API accepts both formats.

Relationships

Relationships define how object types relate to each other (e.g., Person → Company). You can create relationship definitions between any two object types, then create instances linking specific records. Relationship types: one_to_one, one_to_many, many_to_many

Lists

Lists group records into working sets — the slices of the graph your agents, workflows, or external systems need to operate on. Each list is associated with a specific object type.

Tasks

Tasks are actionable items that can be associated with records and assigned to users. Tasks support priorities (low, medium, high, urgent), due dates, and completion tracking. Deleting a task archives it (soft delete).

Notes

Notes are free-form text entries that can be associated with records. Deleting a note archives it (soft delete).

Timeline

The timeline provides a chronological activity feed for any record, including tasks, notes, attribute changes, and relationship events. Supports cursor-based pagination.

Integrations

Integrations are how the context layer pulls in signal. Connect your workspace to the tools where work happens — email, calendar, messaging, and other systems listed below — and Nex continuously ingests, parses, and links that activity into your knowledge graph. Supported integrations:

Type	Provider	Name	Connect method
`email`	`google`	Gmail	Direct OAuth
`calendar`	`google`	Google Calendar	Direct OAuth
`email`	`microsoft`	Outlook	Direct OAuth
`calendar`	`microsoft`	Outlook Calendar	Direct OAuth
`messaging`	`slack`	Slack	Direct OAuth
`crm`	`attio`	Attio	Direct OAuth
`crm`	`hubspot`	HubSpot	Nango-brokered OAuth
`crm`	`salesforce`	Salesforce	Nango-brokered OAuth
`messaging`	`whatsapp`	WhatsApp Business	Config-based

OAuth flow (applies to Direct OAuth and Nango-brokered providers):

Call POST /v1/integrations/{type}/{provider}/connect to get an auth_url and connect_id
Open the auth_url in a browser for the user to authorize
Poll GET /v1/integrations/connect/{connect_id}/status until status is "connected"

WhatsApp uses a config-based connect flow rather than OAuth — contact Nex support for setup.

Knowledge Graph

The knowledge graph is the unified view of every entity in your workspace and how they connect. It combines the typed relationships you define through the Schema API (e.g., person works_at company) with AI-extracted knowledge from ingested context — triplet relationships, entity insights, and semantic links between insights. The endpoint supports both JSON output for programmatic access and an interactive HTML visualization. See Get knowledge graph.

Compounding

The compounding pipeline continuously refines your workspace’s intelligence by consolidating duplicate insights, detecting patterns, synthesizing playbooks, and decaying stale data. Use the Trigger compounding job endpoint to start these intelligence jobs on demand, then poll Get compounding job status for completion and final metrics.

Search

Full-text search across all records in the workspace. Results are grouped by object type and include relevance scores.

Attribute Types

When creating attributes via the Schema endpoints, the following types are supported:

Type	Description
`text`	Free-form text
`number`	Numeric values (integer or decimal)
`email`	Email addresses
`phone`	Phone numbers
`url`	URLs
`date`	Dates
`boolean`	True/false values
`currency`	Currency amounts
`location`	Physical addresses
`select`	Predefined options (single or multi-select)
`social_profile`	Social media profiles
`domain`	Web domains
`full_name`	Structured names (first/last)

Pagination

The API uses two pagination styles:

Offset-based: Used by records, tasks, and list records. Responses include total, limit, offset, and has_more/next_offset fields.
Cursor-based: Used by timeline. Responses include has_next_page and next_cursor fields.

Error Handling

All error responses follow a consistent format:

{
  "code": 400,
  "message": "Description of what went wrong"
}

Status Code	Description
`400`	Bad request - Invalid input data
`401`	Unauthorized - Invalid or missing API key
`404`	Not found - Resource doesn’t exist
`429`	Too many requests - Rate limit exceeded
`500`	Internal server error

Common Use Cases

Ingest context: Push unstructured text, transcripts, or artifacts into the graph via the Context API so everything downstream can reason over them.
Query in natural language: Ask questions across every connected source and get grounded answers backed by the graph.
Ground your own agents: Build agents that read from the knowledge graph and Insights stream, so they act on the same context Nex itself does.
Shape the schema: Define the object types and relationships that match your domain — projects, incidents, playbooks, whatever your workflows need.
Model the graph: Create entities, connect them with typed relationships, and traverse the full graph for any node.
Stream insights: Subscribe to the Insights SSE stream to pipe AI-derived signal into your own systems in real time.
Compound intelligence: Trigger compounding jobs on demand to consolidate insights, detect patterns, and synthesize playbooks from accumulated context.
Full-text search: Find entities across the workspace with relevance scoring and type grouping.
Timeline audit: View the complete change history for any entity — tasks, notes, attribute changes, and relationship events.

API Documentation

Schema

Objects

Records

Relationships

Lists

Tasks

Notes

Timeline

Search

Context

Insights

Graph

Integrations

Notifications

AI Lists

Compounding

Lists

Objects

Schema

Records

Context

AI Lists

Relationships

Timeline

Tasks

Notes

Insights

Search

Graph

Integrations

Compounding

Notifications

​Welcome

Nex API Specification

​Authentication

​Base URL

​Scopes

​Data Model Overview

​Core Resources

​Objects (Entity Definitions)

​Records (Entities)

​Relationships

​Lists

​Tasks

​Notes

​Timeline

​Integrations

​Knowledge Graph

​Compounding

​Search

​Attribute Types

​Pagination

​Error Handling

​Common Use Cases

Welcome

Authentication

Base URL

Scopes

Data Model Overview

Core Resources

Objects (Entity Definitions)

Records (Entities)

Relationships

Lists

Tasks

Notes

Timeline

Integrations

Knowledge Graph

Compounding

Search

Attribute Types

Pagination

Error Handling

Common Use Cases