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

# Organizing with Graphs

> Group related triples together using graphs

## What are Graphs?

Graphs are a way to group related triples within an index. While indexes separate different knowledge domains, graphs organize triples within a domain.

Think of:

* **Index** = A database
* **Graph** = A table or collection within that database

## When to Use Graphs

### By Session

Group triples created in one research session:

```bash theme={null}
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "SpaceX Research - January 2026",
    "description": "Facts gathered about SpaceX Starship development",
    "index_id": "YOUR_INDEX_ID"
  }'
```

### By Source

Group triples from the same document or URL:

```bash theme={null}
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Wikipedia - Tesla Motors",
    "description": "Facts extracted from Tesla Wikipedia article",
    "index_id": "YOUR_INDEX_ID"
  }'
```

### By Topic

Group triples about a specific topic:

```bash theme={null}
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Starship Specifications",
    "description": "Technical specifications of SpaceX Starship",
    "index_id": "YOUR_INDEX_ID"
  }'
```

## Creating a Graph

```bash theme={null}
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Q1 2026 Research",
    "description": "Quarterly research findings",
    "index_id": "YOUR_INDEX_ID"
  }'
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Q1 2026 Research",
    "description": "Quarterly research findings",
    "index_id": "index-uuid",
    "triple_count": 0,
    "created_at": "2026-01-27T10:00:00Z",
    "updated_at": "2026-01-27T10:00:00Z"
  }
}
```

## Using Graphs

### Add Triples to a Graph

Include `graph_id` when creating triples:

```bash theme={null}
curl -X POST https://neode.ai/api/triples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": "Starship",
    "predicate": "height_meters",
    "object": "120",
    "object_type": "literal",
    "index_id": "YOUR_INDEX_ID",
    "graph_id": "YOUR_GRAPH_ID"
  }'
```

### Query Triples by Graph

```bash theme={null}
curl "https://neode.ai/api/triples?graph_id=YOUR_GRAPH_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Move Triple to Different Graph

Update the triple's graph:

```bash theme={null}
curl -X PUT https://neode.ai/api/triples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "id": "TRIPLE_UUID",
    "graph_id": "NEW_GRAPH_ID"
  }'
```

## Listing Graphs

### All Graphs

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

### Search Graphs

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

## Getting a Graph

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

Returns the graph with its triple count:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "SpaceX Research",
    "description": "Facts about SpaceX",
    "index_id": "index-uuid",
    "triple_count": 47,
    "created_at": "2026-01-27T10:00:00Z",
    "updated_at": "2026-01-27T10:00:00Z"
  }
}
```

## Deleting a Graph

### Delete Graph Only

Delete the graph but keep its triples (they become ungrouped):

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

### Delete Graph and Triples

Delete the graph and all its triples:

```bash theme={null}
curl -X DELETE "https://neode.ai/api/graphs/GRAPH_UUID?deleteTriples=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  Deleting with `deleteTriples=true` permanently removes all triples in the graph.
</Warning>

## Graph Properties

| Property       | Description           |
| -------------- | --------------------- |
| `id`           | Unique identifier     |
| `name`         | Display name          |
| `description`  | Optional description  |
| `index_id`     | Parent index          |
| `metadata`     | Custom JSON metadata  |
| `triple_count` | Number of triples     |
| `created_at`   | Creation timestamp    |
| `updated_at`   | Last update timestamp |

## Best Practices

### Descriptive Names

Use names that describe the content or context:

```json theme={null}
{
  "name": "Tesla Q4 2025 Earnings Call",
  "description": "Facts extracted from Tesla's Q4 2025 earnings call transcript"
}
```

### Use Metadata

Store additional context in metadata:

```bash theme={null}
curl -X POST https://neode.ai/api/graphs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Wikipedia Import",
    "index_id": "YOUR_INDEX_ID",
    "metadata": {
      "source_url": "https://wikipedia.org/wiki/Tesla",
      "imported_at": "2026-01-27",
      "version": "1.0"
    }
  }'
```

### Graphs are Optional

You don't have to use graphs. If organization isn't important, just use indexes without graphs.

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