Ingestion

Ingest user data

Feed user activity, communications, or documents into Fastino’s personalization system. This endpoint allows agents to ingest raw events and documents, enabling the API to continuously learn and refine each user’s world model.

POST /ingest

Purpose

Use this endpoint to send contextual data — such as emails, notes, or task events — associated with a registered user.
Ingested data is embedded, indexed, and made retrievable via the /query, /summary, and /chunks endpoints.

You can call this endpoint anytime new user interactions occur (e.g., sending an email, updating a doc, completing a task).

Endpoint

Headers

Request Body

Field	Type	Required	Description
`user_id`	string	Yes	Unique ID of the user receiving the new data.
`source`	string	Optional	The origin of the data (e.g. `gmail`, `notion`, `slack`, or `workspace`).
`events`	array	Optional	List of events such as messages, emails, or activity logs.
`documents`	array	Optional	List of documents or text artifacts for indexing and retrieval.
`options.dedupe`	boolean	Optional	Prevent duplicates by skipping previously ingested records. Default: `false`.

Event Object

Field	Type	Required	Description
`event_id`	string	Yes	Unique identifier for the event.
`type`	string	Yes	Category of event (e.g. `email`, `message`, `note`, `task`).
`timestamp`	string	Yes	ISO 8601 UTC timestamp for when the event occurred.
`metadata`	object	Optional	Optional metadata (e.g. sender, subject, recipients).
`content`	string	Yes	Text content of the event.

Document Object

Field	Type	Required	Description
`doc_id`	string	Yes	Unique identifier for the document.
`kind`	string	Optional	Type of document (`note`, `summary`, `report`, etc.).
`title`	string	Optional	Human-readable title for the document.
`created_at`	string	Optional	ISO 8601 UTC timestamp for when it was created.
`content`	string	Yes	The main text content.

Example Request

{
  "user_id": "usr_42af7c",
  "source": "gmail",
  "events": [
    {
      "event_id": "evt_1",
      "type": "email",
      "timestamp": "2025-10-10T09:00:00Z",
      "metadata": {
        "from": "ceo@company.com",
        "to": ["ash@example.com"],
        "subject": "Shift weekly to afternoons"
      },
      "content": "Let's move stand-up to 2 PM starting next week."
    }
  ],
  "documents": [
    {
      "doc_id": "doc_7",
      "kind": "note",
      "title": "Work style",
      "created_at": "2025-09-29T18:00:00Z",
      "content": "Typical focus blocks 9–12 PT; meetings after 1 PM preferred."
    }
  ],
  "options": { "dedupe": true }
}

Example cURL

curl -X POST "https://api.fastino.ai/ingest" \
  -H "Authorization: x-api-key: sk_test_123" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_42af7c",
    "source": "gmail",
    "events": [
      {
        "event_id": "evt_1",
        "type": "email",
        "timestamp": "2025-10-10T09:00:00Z",
        "content": "Let’s move stand-up to 2 PM starting next week."
      }
    ]
  }'

Example Response

{
  "ingested": { "events": 1, "documents": 1 },
  "skipped": [],
  "updated_at": "2025-10-11T16:05:05Z"
}

Response Fields

Field	Type	Description
`ingested`	object	Number of successfully stored events and documents.
`skipped`	array	List of records skipped due to deduplication.
`updated_at`	string	Timestamp of the latest update.

Behavior

The ingestion process is synchronous — responses confirm how many items were stored.
If "dedupe": true is set, any duplicate event_id or doc_id is skipped.
Ingested records are indexed and available immediately for RAG and query retrieval.
The same endpoint supports batch ingestion (multiple events or docs per call).

Error Responses

HTTP Code	Error Code	Description
`400`	`INVALID_REQUEST`	Malformed JSON or missing fields like `user_id`.
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`404`	`USER_NOT_FOUND`	The user has not been registered yet.
`500`	`SERVER_ERROR`	Internal error — retry with exponential backoff.

Example:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user found with ID usr_42af7c"
  }
}

Best Practices

Always provide a consistent user_id matching the profile registered with /register.
Use structured metadata fields where possible for better context retrieval.
Enable options.dedupe to prevent redundant storage when syncing from external systems.
Ingest in small batches (max 100 events or 25 documents per call) for optimal performance.
Avoid sending empty content fields — each record should contain meaningful text.

Related Endpoints

Endpoint	Description
PUT `/register`	Register or update a user.
POST `/query`	Query user memory for natural-language answers.
GET `/summary`	Retrieve a summary of user context.

Summary:
Use POST /ingest to feed user data into Fastino.
Each ingested event or document becomes part of the user’s evolving memory — powering retrieval, reasoning, and adaptive summaries across the Fastino ecosystem.

Delete user data

Generate a summary

Join our Discord Community

On this page

Title