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

# API Reference

> Complete reference for the Neode REST API

## Overview

The Neode API allows you to programmatically store, query, and generate knowledge triples. Use it to build LLM memory systems, research tools, or any application that needs structured knowledge.

## Base URL

```
https://neode.ai/api
```

For local development:

```
http://localhost:5173/api
```

## Authentication

All API requests require authentication using a Bearer token or API key.

### Bearer Token

Include your API key in the `Authorization` header:

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

### Getting an API Key

1. Sign in to your [Neode dashboard](https://neode.ai/dashboard)
2. Go to [Settings → API Keys](https://neode.ai/dashboard/settings/api-keys)
3. Create a new API key
4. Copy and securely store your key

<Warning>
  Keep your API key secret. Don't commit it to version control or expose it in client-side code.
</Warning>

## Request Format

All POST/PUT requests should use JSON:

```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": "founded_by", "object": "Elon Musk"}'
```

## Response Format

All responses return JSON with a consistent structure:

### Success Response

```json theme={null}
{
  "success": true,
  "data": { ... },
  "count": 10
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": "Error message",
  "details": "Additional context"
}
```

## HTTP Status Codes

| Code  | Description                               |
| ----- | ----------------------------------------- |
| `200` | Success                                   |
| `400` | Bad request - invalid parameters          |
| `401` | Unauthorized - invalid or missing API key |
| `402` | Payment required - insufficient credits   |
| `404` | Not found - resource doesn't exist        |
| `500` | Server error                              |

## Rate Limits

* **Standard**: 100 requests per minute
* **Generation**: 10 requests per minute (AI endpoints)

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706400000
```

## Credits

AI generation endpoints consume credits:

| Operation                             | Credits |
| ------------------------------------- | ------- |
| Generate triples (without web search) | 2¢      |
| Generate triples (with web search)    | 5¢      |
| Generate entity description           | 1¢      |

Check your balance at [Settings → Billing](https://neode.ai/dashboard/settings/billing).

When credits are insufficient, you'll receive a `402` response:

```json theme={null}
{
  "success": false,
  "error": "Insufficient credits",
  "balance_cents": 5,
  "required_cents": 10,
  "buy_credits_url": "https://neode.ai/dashboard/settings/billing"
}
```

## API Endpoints

<CardGroup cols={2}>
  <Card title="Triples" icon="share-nodes" href="/api-reference/endpoint/triples/query">
    Store and query knowledge facts
  </Card>

  <Card title="Entities" icon="cube" href="/api-reference/endpoint/entities/list">
    Manage entities in your knowledge graph
  </Card>

  <Card title="Graphs" icon="diagram-project" href="/api-reference/endpoint/graphs/list">
    Organize triples into graphs
  </Card>

  <Card title="Indexes" icon="folder-tree" href="/api-reference/endpoint/indexes/list">
    Create and manage indexes
  </Card>

  <Card title="Generation" icon="sparkles" href="/api-reference/endpoint/generation/generate">
    AI-powered triple extraction
  </Card>

  <Card title="Embeddings" icon="brain" href="/api-reference/endpoint/embeddings/create">
    Generate vector embeddings
  </Card>
</CardGroup>

## SDKs and Libraries

Official SDKs coming soon. For now, use the REST API directly or with any HTTP client.

### Example with fetch (JavaScript)

```javascript theme={null}
const neode = {
  baseUrl: 'https://neode.ai/api',
  apiKey: 'YOUR_API_KEY',
  
  async request(endpoint, options = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
        ...options.headers
      }
    });
    return response.json();
  },
  
  async createTriple(triple) {
    return this.request('/triples', {
      method: 'POST',
      body: JSON.stringify(triple)
    });
  },
  
  async queryTriples(params) {
    const query = new URLSearchParams(params).toString();
    return this.request(`/triples?${query}`);
  }
};
```

### Example with requests (Python)

```python theme={null}
import requests

class Neode:
    def __init__(self, api_key):
        self.base_url = 'https://neode.ai/api'
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}'
        }
    
    def create_triple(self, triple):
        response = requests.post(
            f'{self.base_url}/triples',
            headers=self.headers,
            json=triple
        )
        return response.json()
    
    def query_triples(self, **params):
        response = requests.get(
            f'{self.base_url}/triples',
            headers=self.headers,
            params=params
        )
        return response.json()

# Usage
neode = Neode('YOUR_API_KEY')
result = neode.create_triple({
    'subject': 'Tesla',
    'predicate': 'founded_by',
    'object': 'Elon Musk',
    'object_type': 'entity',
    'index_id': 'YOUR_INDEX_ID'
})
```