Overview

Introduction

The Personalization API provides a unified interface to register users, ingest activity data, and retrieve personal context — enabling AI assistants, copilots, and intelligent systems to learn from real user behavior.

Each user becomes a dynamic world-model that updates continuously from documents, emails, and events.
This guide walks you through setup, authentication, and your first API call.

How It Works

The API has four primary layers:

1. Register – Create or update a user profile with traits like name, timezone, and URLs.
Endpoint: PUT /register

2. Ingest – Feed events and documents to update the user’s memory.
Endpoint: POST /ingest

3. Query – Ask natural-language questions about the user’s preferences or behavior.
Endpoint: POST /query

4. Retrieve – Get summaries or top-k snippets for grounding model responses.
Endpoint: GET /summary

Before You Start

Requirements

• API access token

• JSON-capable HTTP client (curl, Postman, or Python requests)

• ISO 8601 UTC timestamps

• Internet access to https://api.fastino.ai

Authorization

All requests must include the following headers:

Keep your API keys private — never expose them in frontend code or public repos.

Creating Your Account

Step 1: Sign Up for API Access

Visit the Fastino Developer Portal and create your workspace.

Provide:

• Email address and organization name

• Intended use case (e.g., calendar assistant, productivity agent)

• Default region and timezone

Once complete, you can create an API key.

Connecting Your First User

Register a User

curl -X PUT "https://api.fastino.ai/register" \
  -H "Authorization: x-api-key: pk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_42af7c",
    "traits": {
      "name": "Ash Lewis",
      "timezone": "America/Los_Angeles",
      "notes": "Founder/engineer; prefers concise comms"
    }
  }'

Response

{
  "user_id": "usr_42af7c",
  "created_at": "2025-10-11T16:05:00Z",
  "status": "active"
}

Ingesting User Data

You can send events (emails, messages, actions) and documents (notes, traits, preferences) for contextual learning.

curl -X POST "https://api.fastino.ai/ingest" \
  -H "Authorization: x-api-key: pk-..." \
  -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."
      }
    ]
  }'

Response

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

Querying the User Profile

Ask natural-language questions about the user’s memory or preferences.

curl -X POST "https://api.fastino.ai/query" \
  -H "Authorization: x-api-key: pk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_42af7c",
    "question": "When does Ash prefer to schedule meetings?"
  }'

Response

{
  "user_id": "usr_42af7c",
  "answer": "Ash prefers meetings after 1 PM, following morning focus blocks."
}

Example Python Integration

import requests

BASE_URL = "https://api.fastino.ai"
headers = {
  "Authorization": "x-api-key: pk-...",
  "Content-Type": "application/json"
}

# Register a user
requests.put(f"{BASE_URL}/register", json={
  "user_id": "usr_42af7c",
  "traits": {"name": "Ash Lewis", "timezone": "America/Los_Angeles"}
}, headers=headers)

# Ask a question
response = requests.post(f"{BASE_URL}/query", json={
  "user_id": "usr_42af7c",
  "question": "What time of day does Ash prefer meetings?"
}, headers=headers)

print(response.json()["answer"])