Ingestion

The Ingestion API allows you to import documents and web pages directly into Memsolus as memories. Submit a file upload or a URL, and the system processes it asynchronously — extracting text, splitting it into chunks, and storing each chunk as an individual memory.

Ingest endpoints require the hasIngest entitlement on your plan.

Endpoint Overview

Method	Path	Permission	Description
POST	/v1/memories/ingest	ingest.write	Create an ingestion job
GET	/v1/ingest-jobs	ingest.read	List ingestion jobs
GET	/v1/ingest-jobs/:id	ingest.read	Get ingestion job details

---

Ingest Job Object

Field	Type	Description
id	string	UUID of the ingest job
format	PDF | CSV | MARKDOWN | JSON | URL | TXT | DOCX | HTML	Input format
workspace_id	string	Target workspace UUID
user_id	string	User to associate ingested memories with
agent_id	string | null	Agent identifier
source_url	string | null	Source URL (for URL-based ingest)
categories	string[] | null	Categories applied to ingested memories
status	PENDING | PROCESSING | COMPLETED | FAILED	Current job status
error	string | null	Error message if status is FAILED
memories_created	number | null	Number of memories created on completion
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-update timestamp

---

Create Ingest Job

POST/v1/memories/ingest

API Key

Submit a file or URL for ingestion into memory

This endpoint accepts multipart/form-data. Either provide a file upload or a source_url — at least one is required.

Supported Formats

Format	MIME type	Max file size
PDF	application/pdf	20 MB
CSV	text/csv	10 MB
MARKDOWN	text/markdown, text/plain	5 MB
JSON	application/json	5 MB
TXT	text/plain	5 MB
DOCX	application/vnd.openxmlformats-officedocument.wordprocessingml.document	20 MB
HTML	text/html	5 MB
URL	—	—

Parameter	Type	Description
formatrequired	enum	Input format: `PDF`, `CSV`, `MARKDOWN`, `JSON`, `TXT`, `DOCX`, `HTML`, or `URL`
workspace_idrequired	string (UUID)	Target workspace to store ingested memories
user_idrequired	string	User to associate the ingested memories with (max 255 chars)
file	file	File upload (multipart). Required unless `source_url` is provided.
source_url	string (URL)	Public URL to fetch and ingest. Required unless `file` is provided.
agent_id	string	Agent identifier for the ingested memories (max 255 chars)
categories	string[]	Category tags applied to all ingested memories (max 20 items)
options	string (JSON)	Optional JSON string with additional processing options (max 4096 chars)

File upload example

curl -X POST https://api.memsolus.com/v1/memories/ingest \
  -H "X-Api-Key: msk_live_..." \
  -F "format=PDF" \
  -F "workspace_id=ws-uuid-here" \
  -F "user_id=user-123" \
  -F "categories=finance,reports" \
  -F "file=@/path/to/document.pdf"

URL ingest example

curl -X POST https://api.memsolus.com/v1/memories/ingest \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: multipart/form-data" \
  -F "format=URL" \
  -F "workspace_id=ws-uuid-here" \
  -F "user_id=user-123" \
  -F "source_url=https://example.com/article"

201Ingest job created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "format": "PDF",
  "workspace_id": "ws-uuid-here",
  "user_id": "user-123",
  "agent_id": null,
  "source_url": null,
  "categories": ["finance", "reports"],
  "status": "PENDING",
  "error": null,
  "memories_created": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:30:00.000Z"
}

The job is processed asynchronously. Poll GET /v1/ingest-jobs/:id until status is COMPLETED or FAILED.

---

List Ingest Jobs

GET/v1/ingest-jobs

API Key

List all ingestion jobs for the account

Parameter	Type	Description
page	number	Page number (default: 1)
page_size	number	Results per page, max 100 (default: 20)

curl "https://api.memsolus.com/v1/ingest-jobs?page=1" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "format": "PDF",
      "workspace_id": "ws-uuid-here",
      "user_id": "user-123",
      "status": "COMPLETED",
      "memories_created": 34,
      "categories": ["finance", "reports"],
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:35:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "format": "URL",
      "workspace_id": "ws-uuid-here",
      "user_id": "user-456",
      "source_url": "https://example.com/article",
      "status": "PROCESSING",
      "memories_created": null,
      "created_at": "2026-01-15T10:40:00.000Z",
      "updated_at": "2026-01-15T10:40:00.000Z"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

---

Get Ingest Job

GET/v1/ingest-jobs/:id

API Key

Get the full details and status of an ingestion job

curl "https://api.memsolus.com/v1/ingest-jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-Api-Key: msk_live_..."

200Completed job

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "format": "PDF",
  "workspace_id": "ws-uuid-here",
  "user_id": "user-123",
  "agent_id": null,
  "source_url": null,
  "categories": ["finance", "reports"],
  "status": "COMPLETED",
  "error": null,
  "memories_created": 34,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:35:00.000Z"
}

200Failed job

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "format": "PDF",
  "workspace_id": "ws-uuid-here",
  "user_id": "user-123",
  "status": "FAILED",
  "error": "File could not be parsed: corrupt or password-protected PDF",
  "memories_created": null,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-01-15T10:31:00.000Z"
}

---

Job Lifecycle

PENDING → PROCESSING → COMPLETED
                     → FAILED

Processing time depends on document size. A 20-page PDF typically completes in under 30 seconds.

---

API Overview

Authentication, permissions, and error codes

→

Memories

View and search the memories created by ingestion

→