Documents API

Upload any file and extract structured text. Parsed content can be stored directly as searchable memory.

Base URLhttps://api.neuralbase.cloud

POST/v1/documents/parse— Parse a document

Upload a file and extract its text content. Returns synchronously for small files.

bash

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

curl -X POST "$BASE_URL/v1/documents/parse" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@report.pdf" \
  -F "extractTables=true" \
  -F "extractEntities=false" \
  -F "generateSummary=false"

Example sync response (HTTP 200)

Small files return the parsed payload directly, including extracted text and document metadata.

json

{
  "documentId": "doc_abc123",
  "fileName": "report.pdf",
  "fileType": "pdf",
  "fileSize": 1024000,
  "pageCount": 12,
  "wordCount": 3420,
  "characterCount": 18500,
  "language": "en",
  "processingMs": 1240,
  "text": "full extracted text...",
  "summary": "Sentence one. Sentence two.",
  "keyPoints": ["Point 1", "Point 2", "Point 3"],
  "documentType": "report",
  "structure": { "headings": [], "sections": [] },
  "tables": [],
  "entities": {
    "people": [],
    "organizations": [],
    "locations": [],
    "dates": [],
    "amounts": [],
    "emails": [],
    "urls": [],
    "phoneNumbers": []
  },
  "documentMetadata": {
    "title": null,
    "author": null,
    "createdAt": null,
    "modifiedAt": null,
    "subject": null
  },
  "ocrApplied": false,
  "ocrConfidence": null,
  "aiExtraction": false,
  "createdAt": 1772735000000,
  "stored": false
}

POST/v1/documents/parse— Parse and store as memory

Set store=true and a userId to automatically chunk and index the document as searchable memories.

bash

curl -X POST "$BASE_URL/v1/documents/parse" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@policy.docx" \
  -F "store=true" \
  -F "userId=user_123"

Example parse + store response

When store=true, the same response includes memory fields so developers can search immediately.

json

{
  "documentId": "doc_store_123",
  "fileName": "policy.docx",
  "stored": true,
  "memoryId": "mem_789xyz",
  "chunksCreated": 6
}

GET/v1/documents/:id/status— Check async status

Large files return HTTP 202 immediately. Poll this endpoint until status is complete.

bash

# Initial parse response → 202 Accepted
{ "documentId": "doc_xxx", "status": "processing", "progress": 0 }

# Poll for completion
curl "$BASE_URL/v1/documents/doc_xxx/status" \
  -H "Authorization: Bearer $API_KEY"

Example async responses

Large files first return 202 processing, then status/result endpoints return the final payload.

json

// Initial parse response (HTTP 202)
{ "documentId": "doc_xxx", "status": "processing", "progress": 0 }

// Status while running (HTTP 200)
{ "status": "processing", "documentId": "doc_xxx", "progress": 40, "errorMessage": null }

// Status when complete (HTTP 200)
{
  "status": "complete",
  "documentId": "doc_xxx",
  "progress": 100,
  "errorMessage": null,
  "result": {
    "documentId": "doc_xxx",
    "text": "full extracted text...",
    "stored": false
  }
}

GET/v1/documents— List documents

Returns all parsed documents belonging to the authenticated API key.

bash

curl "$BASE_URL/v1/documents" \
  -H "Authorization: Bearer $API_KEY"

Store later & delete

Store a previously parsed document as memory at any point, or permanently delete it.

bash

# Store as memory
curl -X POST "$BASE_URL/v1/documents/doc_xxx/store" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_123"}'

# Delete document
curl -X DELETE "$BASE_URL/v1/documents/doc_xxx" \
  -H "Authorization: Bearer $API_KEY"

Supported file formats

NeuralBase can parse the following file types:

.pdf.docx.doc.pptx.ppt.xlsx.xls.csv.txt.md.html.json.png.jpg.jpeg.webp

Error codes

All error responses return a JSON body with a message field.

Code	Description
400	Unsupported file type or plan limit exceeded
413	File size exceeds the absolute maximum
422	Parsing failed — file may be corrupted
429	Rate limit exceeded