Organizing with 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:

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:

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:

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

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:

{
  "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:

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

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:

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

curl "https://neode.ai/api/graphs" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Graphs

curl "https://neode.ai/api/graphs?search=spacex" \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting a Graph

curl "https://neode.ai/api/graphs/GRAPH_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns the graph with its triple count:

{
  "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):

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:

curl -X DELETE "https://neode.ai/api/graphs/GRAPH_UUID?deleteTriples=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting with deleteTriples=true permanently removes all triples in the graph.

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:

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

Use Metadata

Store additional context in metadata:

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.

API Reference

See the complete Graphs API documentation.

Getting Started

Core Features

AI Features

Organizing with Graphs

What are Graphs?

When to Use Graphs

By Session

By Source

By Topic

Creating a Graph

Using Graphs

Add Triples to a Graph

Query Triples by Graph

Move Triple to Different Graph

Listing Graphs

All Graphs

Search Graphs

Getting a Graph

Deleting a Graph

Delete Graph Only

Delete Graph and Triples

Graph Properties

Best Practices

Descriptive Names

Use Metadata

Graphs are Optional

API Reference

​What are Graphs?

​When to Use Graphs

​By Session

​By Source

​By Topic

​Creating a Graph

​Using Graphs

​Add Triples to a Graph

​Query Triples by Graph

​Move Triple to Different Graph

​Listing Graphs

​All Graphs

​Search Graphs

​Getting a Graph

​Deleting a Graph

​Delete Graph Only

​Delete Graph and Triples

​Graph Properties

​Best Practices

​Descriptive Names

​Use Metadata

​Graphs are Optional

API Reference

What are Graphs?

When to Use Graphs

By Session

By Source

By Topic

Creating a Graph

Using Graphs

Add Triples to a Graph

Query Triples by Graph

Move Triple to Different Graph

Listing Graphs

All Graphs

Search Graphs

Getting a Graph

Deleting a Graph

Delete Graph Only

Delete Graph and Triples

Graph Properties

Best Practices

Descriptive Names

Use Metadata

Graphs are Optional