Neura API

External brain for AI agents — persistent memory and state via HTTP. Designed so agents can use it without human help.

Authentication

Authorization: Bearer sk-xxx

All requests require this header. Generate API keys via the dashboard.

Endpoints

POST/api/memory

Store Memory

Store a fact with auto-embedding via OpenAI. The content is vectorized and indexed for semantic search.

Request body:
{
  "content": "User prefers dark mode in all apps",
  "tags": ["preference", "ui"],
  "importance": 8,
  "metadata": { "source": "conversation" }
}
Response:
{
  "data": {
    "id": "uuid",
    "content": "...",
    "tags": ["preference", "ui"],
    "importance": 8,
    "created_at": "2026-05-14T..."
  }
}
GET/api/memory?query=...&limit=10

Search Memories

Semantic search. Returns memories ranked by cosine similarity (0-1). Omitting query returns most recent.

Response:
{
  "data": [
    {
      "id": "uuid",
      "content": "...",
      "score": 0.92,
      "tags": ["preference"],
      "created_at": "2026-05-14T..."
    }
  ],
  "meta": { "total": 5, "query": "..." }
}
POST/api/memory/search

Advanced Search

Filter by tags, importance, date range, and metadata. Give agents precision control.

Request body:
{
  "query": "user preferences",
  "filters": {
    "tags": ["preference"],
    "importance_min": 5,
    "date_from": "2026-01-01"
  },
  "limit": 20,
  "min_score": 0.5
}
Response:
{
  "data": [...],
  "meta": { "total": 12 }
}
PATCH/api/memory/:id

Update Memory

Update fields. Content changes auto-regenerate the embedding.

Request body:
{ "importance": 9 }
Response:
{ "data": { ... } }
DELETE/api/memory/:id

Delete Memory

Remove a memory permanently.

Response:
{ "data": { "id": "uuid", "deleted": true } }
POST/api/state

Set State

Persistent key-value storage. Survives context loss. Use for goals, settings, flags.

Request body:
{
  "key": "current_goal",
  "value": { "task": "Build API", "priority": "high" }
}
Response:
{ "data": { "key": "current_goal", "value": {...}, "updated_at": "..." } }
GET/api/state/:key

Get State

Retrieve a single value by key. Returns 404 if key doesn't exist.

Response:
{ "data": { "key": "current_goal", "value": {...} } }
GET/api/state

List State

Return all state entries for this agent.

Response:
{ "data": [{ "key": "...", "value": ... }] }
DELETE/api/state/:key

Delete State

Remove a state entry.

Response:
{ "data": { "key": "...", "deleted": true } }

Error Format

Every error is machine-readable. Agents use the code and action fields to self-heal.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "action": "wait_and_retry",
    "retry_after": 5,
    "docs_url": "https://neura.sh/docs/..."
  }
}
CodeStatusAgent Action
unauthorized401provide_valid_api_key
validation_error400fix_request_body
not_found404check_resource_id
rate_limited429wait_and_retry
payment_required402send_payment
internal_error500retry

Rate Limiting

100 requests per 60 seconds per API key. Exceeded requests return 429.

X-RateLimit-Limit — max requests per window

X-RateLimit-Remaining — requests left in window

Retry-After — seconds to wait on 429

Idempotency

POST and PATCH endpoints accept an Idempotency-Key header. If a request is retried with the same key, the original response is returned. Cached for 24 hours. Use this for safe retries.

SDKs

TypeScript

import { Neura } from 'neura-api'

const neura = new Neura({ apiKey: 'sk-...' })
await neura.memory.create({ content: '...' })
const r = await neura.memory.search('...')

0 deps, ESM + CJS, auto-retry

npm install neura-api

Python

from neura import Neura

neura = Neura(api_key="sk-...")
neura.memory.create(content="...")
r = neura.memory.search("...")

0 deps, stdlib only, auto-retry

pip install neura-api