> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API for the Nex context layer — ingest, query, and ground AI agents in your organization

## 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.

<Card title="Nex API Specification" icon="database" href="/api-reference/openapi.json">
  View the complete OpenAPI specification
</Card>

## Authentication

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

```http theme={null}
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, `Incident`, `Vendor`, or `Contract` — 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:**

```json theme={null}
{
  "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):

1. Call `POST /v1/integrations/{type}/{provider}/connect` to get an `auth_url` and `connect_id`
2. Open the `auth_url` in a browser for the user to authorize
3. 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](/api-reference/graph/get-knowledge-graph).

### Compounding

The compounding pipeline continuously refines your workspace's intelligence by consolidating duplicate insights, detecting patterns, synthesizing reusable action rules, and decaying stale data. Use the [Trigger compounding job](/api-reference/compounding/trigger-job) endpoint to start these intelligence jobs on demand, then poll [Get compounding job status](/api-reference/compounding/get-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:

```json theme={null}
{
  "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 — incidents, vendors, contracts, 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 reusable rules 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.