v1 data

Ingest data for processing with memory integration

Ingest data for asynchronous processing

Accepts various content types (text, messages, files) and processes them to extract information
and integrate it into the user's memory system. Returns a job_id for tracking status.

**Entity Resolution:**
- user_id (str, required): Always required - the main user identifier
- persona_id (str, optional): If provided, data is ingested to this persona instead of user
- project_id (str, optional): If provided, data is ingested to this project (inherits from user)

Priority: persona_id > project_id > user_id

**Request Parameters:**
- content_type (str, required): One of: "text", "messages", "pdf", "word", "image", "video", "audio", "file"
- payload (str|dict|list, required): Content data (text string, message list, or base64 for files)
- content_description (str, optional): Description of the content being ingested (e.g., 'Logo design concepts', 'Meeting notes')
- session_id (str, optional): Groups related content for session-based retrieval
- timestamp (str, optional): ISO-8601 timestamp for historical data
- filename (str, optional): Original filename for file uploads

**Response:**
- job_id (str): Unique identifier for tracking the processing job
- user_id (str): Confirmed entity ID (user, persona, or project)
- content_type (str): Confirmed content type
- status (str): Job status ('queued', 'accepted')
- message (str): Status message
- created_at (str): ISO-8601 timestamp
- success (bool): True if accepted

**Example:**
```json
{
    "user_id": "user-123",
    "persona_id": null,
    "project_id": "project-456",
    "content_type": "text",
    "payload": "Meeting notes from today's discussion",
    "content_description": "Meeting notes from today's discussion"
}
```

Returns 202 Accepted with job_id. Use /job/status to check processing status.
Max payload: 5MB (JSON), 20MB (multipart). Requires JWT authentication.

post/v1/data/ingest

Request body

user_idstring required

User ID (always required)

persona_idstring nullable

Optional persona ID. If provided, data is ingested to this persona instead of the user

project_idstring nullable

Optional project ID. If provided, data is ingested to this project (inherits from user)

content_typestring nullable

Content category: 'text', 'image', 'video', 'pdf', 'audio', 'messages', 'file'. If omitted, the category is auto-detected from the uploaded file bytes.

content_descriptionstring nullable

Optional description of the content being ingested (e.g., 'Logo design concepts', 'Meeting notes')

session_idstring nullable

Session ID for grouping related ingested content and enabling session-based retrieval

timestampstring nullable

ISO-8601 timestamp to preserve original data moment

filenamestring nullable

Filename of the uploaded file

callback_urlstring nullable

Optional URL the server will POST to when the job reaches a terminal state (done, error, cancelled). The payload will match the /v1/data/job/status response shape.

notification_emailstring email nullable

Optional email address to notify when the job reaches a terminal state.

Example request

{
  "content_description": "Email correspondence about project updates",
  "content_type": "text",
  "payload": "From: john@example.com\nTo: jane@example.com\nSubject: Hello\n\nHello Jane!",
  "timestamp": "2024-01-01T12:00:00Z",
  "user_id": "user-123"
}

Response

Successful Response

job_idstring required

Unique job identifier for tracking

statusstring required

Processing status ('accepted', 'queued', 'failed')

messagestring nullable

Additional status or error message

successboolean

Whether the request was accepted successfully

Example response

{
  "content_type": "text",
  "created_at": "2024-01-01T12:00:00Z",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Content successfully uploaded and queued for processing",
  "status": "queued",
  "success": true,
  "user_id": "abc-123"
}

Changes

Changed in 6 of the 29 revisions of this API.323

Mar 23, 202627701839a0702See the full diff
- ○
  added the new optional request property callback_url
  new-optional-request-property
- ○
  added the new optional request property notification_email
  new-optional-request-property
Feb 21, 20266e8acd7c094d2See the full diff
- ○
  the request property content_type became optional
  request-property-became-optional
- ○
  request property content_type list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
Feb 9, 2026bb6f89ac9cd33See the full diff
- ▲
  removed the required property content_type from the response with the 202 status
  response-required-property-removed
- ▲
  removed the required property created_at from the response with the 202 status
  response-required-property-removed
- ▲
  removed the required property user_id from the response with the 202 status
  response-required-property-removed
This revision also has 20 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 26, 20263db04235dc221See the full diff
- ○
  added the new optional request property content_description
  new-optional-request-property
Jan 21, 20261660d0b2cbd92See the full diff
- ○
  added the new optional request property persona_id
  new-optional-request-property
- ○
  added the new optional request property project_id
  new-optional-request-property
Dec 10, 20255a9a6b9cb07a16See the full diff
- ○
  added the non-success response with the status 404
  response-non-success-status-added
- ○
  added the optional property details to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 401 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 413 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 401 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 413 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 500 status
  response-optional-property-added
- ○
  added the required property error_code to the response with the 400 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 401 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 413 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 422 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 500 status
  response-required-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history