Skip to main content

Quickstart

The shortest path from nothing to a personality-modulated response. Three steps: install an SDK, set your API key, make a call.

Before you start​

You need two things:

  • An API key. Create one in the uniqOS dashboard. Keys are prefixed uniq_test_ (sandbox) or uniq_live_ (production); the SDKs detect the environment from the prefix automatically. Keep keys server-side — never ship them in a browser bundle.
  • A personality_id. Pick one from the catalog or build your own in the designer, then copy its id (it looks like pers_…).

1. Install​

npm install @uniq-os/[email protected]
# or: pnpm add @uniq-os/[email protected] · yarn add @uniq-os/[email protected] · bun add @uniq-os/[email protected]

2. Set your API key​

Keep the key in the environment, not in source:

export UNIQOS_API_KEY="uniq_test_..."

3. Make your first call​

import { UniqOS } from '@uniq-os/sdk'

const client = new UniqOS({ apiKey: process.env.UNIQOS_API_KEY })

const result = await client.respond({
  personality_id: 'pers_...',
  message: 'Hello!',
})

console.log(result.response) // the agent's reply
console.log(result.inferred_emotional_state.primary) // e.g. "curious"

That call runs stateless — uniqOS adds personality and emotional intelligence for this one turn and persists nothing. To remember the user across turns, see Stateless vs stateful turns.

What comes back​

A successful /v1/respond (text format) returns the reply plus the structured signals uniqOS inferred for the turn:

{
  "return_format": "text",
  "interaction_id": "intr_...",
  "response": "Hi there — good to meet you. What brings you here today?",
  "inferred_emotional_state": {
    "primary": "curious",
    "confidence": 0.62,
    "secondary": ["calm"],
    "intensity": "low",
    "valence": 0.3,
    "arousal": 0.4
  },
  "memory": { "consulted": false },
  "guardrails": { "applied": [] },
  "usage": {
    "turns_consumed": 1,
    "active_relationship_counted": false,
    "llm_provider": "anthropic",
    "llm_model": "..."
  },
  "latency_ms": 0
}

Values above are illustrative. The API Reference carries the authoritative request and response schema, with an interactive console you can call with your own key.

Next steps​

  • SDKs — configuration, streaming, error handling.
  • Concepts — what the personality, emotional state, and memory signals mean.
  • Errors — the error envelope and how the SDKs treat each code.