Human API Guide

What is Human API?

Human API is a memory-enhanced endpoint that automatically injects yours or Onairos user's context/memories that are relevant to any LLM call.

Human API is a key addition to Onairos's vision to make the personalised internet a reality.

Key Features

• Compatible Interface: Use the OpenAI SDK with the Human API base URL
• Memory Injection: Add {onairos_memory} to prompts for instant personalization
• Developer Context: Pass request-local app context in onairos.userContext
• Zero Infrastructure: No databases, embeddings, or RAG pipelines to manage
• Privacy Built-in: Automatic PII removal and isolated user data

Quick Example

// Standard OpenAI call
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{
    role: 'user',
    content: 'What should I work out today?'
  }]
});
// Returns: Generic workout advice

// Configure Human API with your developer key and the user's JWT:
const onairos_client = new OpenAI({
  apiKey: process.env.ONAIROS_API_KEY,       // Your developer key
  baseURL: 'https://human-api.onairos.io/v1',
  defaultHeaders: {
    'x-jwt-token': onairosUserJWT            // User JWT from Onairos consent flow
  }
});

// Human API call with memory and current app context
const response = await onairos_client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{
    role: 'user',
    content: 'Use {onairos_memory} and the current app context. What should I work out today?'
  }],
  onairos: {
    userContext: {
      currentPage: 'workout_builder',
      currentGoal: 'improve cardio endurance',
      availableTimeMinutes: 25
    }
  }
});
// Returns: "Since you did legs yesterday and prefer morning cardio..."

Getting Started

1. Get Your API Keys

• Sign up at developer.onairos.uk
• Create an application (choose your type: fitness, dating, productivity, etc.)
• Generate your API key from the dashboard

2. Update Your Code

import OpenAI from 'openai';

// Configure Human API with your developer key and the user's JWT:
const onairos_client = new OpenAI({
  apiKey: process.env.ONAIROS_API_KEY,       // Your developer key
  baseURL: 'https://human-api.onairos.io/v1',
  defaultHeaders: {
    'x-jwt-token': onairosUserJWT            // User JWT from Onairos consent flow
  }
});

3. Add Memory to Prompts

// Before: Generic responses
'Help me plan my day'

// After: Personalized with memory
'Based on {onairos_memory}, help me plan my day'

// Onairos automatically injects relevant user context

4. Add Developer Context

Use onairos.userContext when your app already knows useful current-session details, such as the active page, selected goal, cart state, lesson state, filters, or recent in-app actions.

const response = await onairos_client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{
    role: 'user',
    content: 'Use the current app context to answer in one sentence.'
  }],
  onairos: {
    userContext: 'The user is on a finance dashboard with conservative risk selected.'
  }
});

userContext can be a string or a JSON object:

const response = await onairos_client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{
    role: 'user',
    content: 'Use {onairos_memory} and the current app context to recommend the next step.'
  }],
  onairos: {
    userContext: {
      currentPage: 'nutrition_planner',
      goal: 'high protein vegetarian meal',
      timeAvailableMinutes: 20
    }
  }
});

Supported Models

Human API supports OpenAI-style model routing. Use provider-prefixed model IDs such as openai/gpt-4o-mini or openai/gpt-4o. Additional providers are available through the same OpenAI-compatible request shape.

Debug Response Headers

Human API returns standard chat completion responses. It also includes optional debug headers that can help during integration:

• X-Onairos-Memory-Injected: whether {onairos_memory} was replaced with retrieved memories
• X-Onairos-Memory-Count: number of memory matches used
• X-Onairos-User-Namespace: memory namespace used for the request
• X-Onairos-Messages-Enriched: number of messages enriched
• X-Onairos-User-Context-Injected: whether developer-provided user context was injected
• X-Onairos-User-Context-Source: whether context came from the request, message history, or neither
• X-Onairos-User-Context-Type: string, json, or none
• X-Onairos-User-Context-Deduped: whether duplicate user-context injection was skipped
• X-Onairos-Provider: model provider used for completion
• X-Onairos-Auth-Method: authentication mode used by Human API

Real-World Examples

Fitness App Integration

const response = await onairos_client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{
    role: 'user',
    content: 'Based on {onairos_memory}, what should I focus on in my workout today?'
  }]
});

Without memory: "Try a full-body workout with cardio and strength training..."

With memory: "Your progress shows you've been consistent with cardio. Since you did legs yesterday and prefer 30-minute sessions, let's focus on upper body strength training today."

Dating App Example

const response = await onairos_client.chat.completions.create({
  model: 'openai/gpt-4o-mini',
  messages: [{
    role: 'user',
    content: 'Based on {onairos_memory}, suggest conversation starters for my matches'
  }]
});

Without memory: "Try asking about their hobbies, favorite movies, or travel experiences."

With memory: "Based on your interest in jazz music and weekend hiking, try asking about their favorite concert or outdoor adventures."