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

# Managing Entities

> Work with entities - the subjects and objects in your knowledge graph

## What are Entities?

Entities are the nodes in your knowledge graph. They represent distinct things - people, companies, places, concepts - that can have facts (triples) about them.

When you create a triple like "Tesla → founded\_by → Elon Musk", Neode automatically:

1. Creates an entity for "Tesla" (if it doesn't exist)
2. Creates an entity for "Elon Musk" (if it doesn't exist)
3. Links the triple to both entities

## Listing Entities

### All Entities in an Index

```bash theme={null}
curl "https://neode.ai/api/entities?index_id=YOUR_INDEX_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Search by Name

```bash theme={null}
curl "https://neode.ai/api/entities?search=tesla" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Exact Name Match

```bash theme={null}
curl "https://neode.ai/api/entities?search=Tesla&exact=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### With Pagination

```bash theme={null}
curl "https://neode.ai/api/entities?index_id=YOUR_INDEX_ID&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Getting an Entity

Retrieve a specific entity by ID:

```bash theme={null}
curl "https://neode.ai/api/entities/ENTITY_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Tesla",
    "description": "American electric vehicle and clean energy company",
    "avatar_url": "https://example.com/tesla-logo.png",
    "index_id": "index-uuid",
    "index_name": "Technology Companies",
    "created_at": "2026-01-27T10:00:00Z",
    "updated_at": "2026-01-27T10:00:00Z"
  }
}
```

## Creating Entities

While entities are usually auto-created from triples, you can create them manually:

```bash theme={null}
curl -X POST https://neode.ai/api/entities \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "OpenAI",
    "description": "AI research and deployment company",
    "index_id": "YOUR_INDEX_ID"
  }'
```

<Tip>
  Manual entity creation is useful when you want to set a description or avatar before adding triples.
</Tip>

## Updating Entities

### Update Name or Description

```bash theme={null}
curl -X PUT "https://neode.ai/api/entities/ENTITY_UUID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Tesla, Inc.",
    "description": "American multinational automotive and clean energy company"
  }'
```

### Set Avatar

```bash theme={null}
curl -X PUT "https://neode.ai/api/entities/ENTITY_UUID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "avatar_url": "https://example.com/company-logo.png"
  }'
```

## Deleting Entities

<Warning>
  Deleting an entity also deletes all triples where it's the subject or object.
</Warning>

```bash theme={null}
curl -X DELETE "https://neode.ai/api/entities/ENTITY_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Entity Disambiguation

### How It Works

Within an index, Neode automatically links triples to existing entities by name:

1. You create triple: "Tesla → founded\_by → Elon Musk"
2. Neode checks: Does "Tesla" entity exist in this index?
3. If yes: Links the triple to existing entity
4. If no: Creates new entity, then links

### Managing Duplicates

If you have duplicate entities (e.g., "Tesla" and "Tesla, Inc."), you can:

**Option 1: Update the name**

```bash theme={null}
curl -X PUT "https://neode.ai/api/entities/DUPLICATE_UUID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Tesla"}'
```

**Option 2: Delete the duplicate** (after migrating triples)

### Separate Domains

Use different indexes to keep entities separate:

```bash theme={null}
# Tech companies index
curl -X POST https://neode.ai/api/indexes \
  -d '{"name": "Technology Companies"}'

# Food companies index  
curl -X POST https://neode.ai/api/indexes \
  -d '{"name": "Food & Beverage"}'
```

Now "Apple" in tech index is separate from "Apple" in food index.

## Entity Properties

| Property      | Description           | Editable |
| ------------- | --------------------- | -------- |
| `id`          | Unique identifier     | No       |
| `name`        | Canonical name        | Yes      |
| `description` | Text description      | Yes      |
| `avatar_url`  | Image URL             | Yes      |
| `index_id`    | Parent index          | Yes      |
| `created_at`  | Creation timestamp    | No       |
| `updated_at`  | Last update timestamp | No       |

## AI-Generated Descriptions

Generate a description using AI based on the entity's triples:

```bash theme={null}
curl -X POST "https://neode.ai/api/entities/ENTITY_UUID/generate-description" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This analyzes all triples about the entity and generates a natural language description.

<Note>
  Description generation costs 1¢ per request.
</Note>

## Querying Entity Triples

Get all triples related to an entity:

```bash theme={null}
# Triples where entity is the subject
curl "https://neode.ai/api/triples?subject_entity_id=ENTITY_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Triples where entity is the object (backlinks)
curl "https://neode.ai/api/triples?object_entity_id=ENTITY_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Card title="API Reference" icon="code" href="/api-reference/endpoint/entities/list">
  See the complete Entities API documentation.
</Card>