Ingest API

Send typed connector payloads to one endpoint. Neuralbase normalizes them into memory and runs the existing chunking and retrieval pipeline for you.

Base URLhttps://api.neuralbase.cloud

Connector-style ingestion

Use /v1/ingest when you already have conversations, support tickets, events, profiles, or documents in your app and want Neuralbase to turn them into searchable memory without hand-formatting each payload yourself.

bash

BASE_URL=https://api.neuralbase.cloud
API_KEY=nb_live_...

# Every request still uses Bearer auth
Authorization: Bearer $API_KEY

Safe retries with idempotency keys

All ingest write endpoints support the Idempotency-Key header. Re-send the exact same body with the same key and Neuralbase will replay the original queued response instead of creating another memory.

bash

curl -X POST "$BASE_URL/v1/ingest" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: conv-987-v1" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Response headers
Idempotency-Key: conv-987-v1
Idempotency-Status: created | replayed | processing

POST/v1/ingest— Ingest a conversation

Conversation payloads are ideal for chat histories, support transcripts, or agent handoffs. Neuralbase will flatten the transcript into one high-quality memory string before chunking.

bash

curl -X POST "$BASE_URL/v1/ingest" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "conversation",
    "userId": "user_123",
    "source": "intercom",
    "externalId": "conv_987",
    "metadata": { "team": "support", "channel": "chat" },
    "data": {
      "title": "Refund request",
      "participants": ["user", "agent"],
      "messages": [
        { "role": "user", "content": "I need help with a refund." },
        { "role": "assistant", "content": "User requested refund on annual plan." }
      ]
    }
  }'

POST/v1/ingest— Ingest a support ticket

Ticket payloads keep subject, priority, status, and comment timeline together in one memory entry.

json

{
  "type": "ticket",
  "userId": "user_123",
  "source": "zendesk",
  "externalId": "ticket_431",
  "metadata": { "workspace": "billing" },
  "data": {
    "subject": "Invoice mismatch",
    "status": "open",
    "priority": "high",
    "comments": [
      { "author": "user", "content": "The amount on my invoice is wrong." },
      { "author": "agent", "content": "Billing team is reviewing the invoice." }
    ]
  }
}

POST/v1/ingest/batch— Batch ingest multiple connector records

Batch ingest accepts multiple typed records in one request. Each accepted item is queued independently and returned with its own memory id.

json

{
  "items": [
    {
      "type": "event",
      "userId": "user_123",
      "source": "product",
      "externalId": "evt_991",
      "data": {
        "name": "checkout_completed",
        "description": "User upgraded to pro plan"
      }
    },
    {
      "type": "profile",
      "userId": "user_123",
      "source": "crm",
      "externalId": "profile_42",
      "data": {
        "summary": "High-value customer",
        "attributes": { "plan": "pro", "region": "ng" }
      }
    }
  ]
}

Source-specific wrapper routes

If you do not want to send a type field manually, use the thin wrappers on top of /v1/ingest. They inject the correct connector type for chat, support, and document payloads.

.post /v1/ingest/chat.post /v1/ingest/support.post /v1/ingest/document

Supported types

Start with whichever source best matches the data you already have in your product.

.conversation.event.profile.ticket.document

Example response

The ingest API returns the queued memory id immediately so you can poll /v1/memories/:id/status just like the standard store endpoint.

json

{
  "memoryId": "mem_abc123",
  "status": "processing",
  "connectorType": "conversation",
  "source": "intercom",
  "externalId": "conv_987",
  "acceptedAs": "memory",
  "normalized": {
    "title": "Refund request",
    "messageCount": 2,
    "participants": ["user", "agent"],
    "tags": [],
    "hasSummary": false
  },
  "estimatedMs": 1200,
  "webhookScheduled": false
}