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

# Working with Triples

> Create, query, update, and delete knowledge triples

## What are Triples?

Triples are the building blocks of your knowledge graph. Each triple represents a fact in the form:

```
Subject → Predicate → Object
```

For example:

* "Tesla" → "headquarters\_in" → "Austin, Texas"
* "Elon Musk" → "founded" → "SpaceX"
* "SpaceX" → "founded\_year" → "2002"

## Creating Triples

### Single Triple

```bash theme={null}
curl -X POST https://neode.ai/api/triples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subject": "Tesla",
    "predicate": "headquarters_in",
    "object": "Austin, Texas",
    "object_type": "entity",
    "confidence": 0.95,
    "source": "https://wikipedia.org/wiki/Tesla",
    "index_id": "YOUR_INDEX_ID"
  }'
```

### Batch Creation

Create multiple triples in one request:

```bash theme={null}
curl -X POST https://neode.ai/api/triples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "triples": [
      {
        "subject": "Tesla",
        "predicate": "founded_year",
        "object": "2003",
        "object_type": "literal"
      },
      {
        "subject": "Tesla",
        "predicate": "industry",
        "object": "Electric Vehicles",
        "object_type": "entity"
      },
      {
        "subject": "Tesla",
        "predicate": "ceo",
        "object": "Elon Musk",
        "object_type": "entity"
      }
    ],
    "index_id": "YOUR_INDEX_ID",
    "confidence": 0.9
  }'
```

<Tip>
  Batch creation is more efficient than individual requests. Use it when storing multiple facts at once.
</Tip>

## Querying Triples

### By Subject

Get all facts about a specific entity:

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

### By Predicate

Get all facts of a specific type:

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

### By Entity ID

Query using the resolved entity IDs:

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

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

### Full-Text Search

Search across subject, predicate, and object:

```bash theme={null}
curl "https://neode.ai/api/triples?search=electric%20vehicle" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Filter by Graph

Get triples from a specific graph:

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

### Combining Filters

```bash theme={null}
curl "https://neode.ai/api/triples?subject=Tesla&predicate=founded_by&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Updating Triples

Update an existing triple by ID:

```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",
    "confidence": 0.99,
    "source": "https://updated-source.com"
  }'
```

You can update:

* `subject`, `predicate`, `object`
* `confidence`
* `source`
* `graph_id`

## Deleting Triples

### Single Delete

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

### Batch Delete

```bash theme={null}
curl -X DELETE "https://neode.ai/api/triples?ids=UUID1,UUID2,UUID3" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Best Practices

### Predicate Naming

Use consistent, lowercase, snake\_case predicates:

| Good              | Avoid                     |
| ----------------- | ------------------------- |
| `founded_by`      | `FoundedBy`, `Founded By` |
| `headquarters_in` | `headquartersIn`, `HQ`    |
| `birth_date`      | `birthDate`, `DOB`        |

### Confidence Scores

Be realistic with confidence scores:

```json theme={null}
{
  "confidence": 0.95  // Verified from authoritative source
}
```

```json theme={null}
{
  "confidence": 0.7   // From news article, may change
}
```

### Sources

Always include sources when possible:

```json theme={null}
{
  "source": "https://wikipedia.org/wiki/Tesla",
  "confidence": 0.95
}
```

### Entity vs Literal

Use the correct object type:

```json theme={null}
// Entity - references another thing
{
  "object": "Elon Musk",
  "object_type": "entity"
}

// Literal - a value
{
  "object": "2003",
  "object_type": "literal"
}
```

## Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "subject": "Tesla",
    "predicate": "founded_by",
    "object": "Elon Musk",
    "object_type": "entity",
    "confidence": 0.95,
    "source": "https://wikipedia.org/wiki/Tesla",
    "subject_entity_id": "entity-uuid-1",
    "object_entity_id": "entity-uuid-2",
    "index_id": "index-uuid",
    "created_at": "2026-01-27T10:00:00Z"
  }
}
```

<Card title="API Reference" icon="code" href="/api-reference/endpoint/triples/query">
  See the complete Triples API documentation.
</Card>