Graita API v1 & Cognitive Architecture Reference

Graita Documentation

Learn how Graita models human perception (*persepsi batin & intuisi kognitif*) using Stanford Generative Agent memory streams, 4-domain expert reflections, zero-sum budget constraints, and the `/v1` REST API.

1. Cognitive Architecture & Memory Retrieval

Every Digital Twin in Graita stores episodic observations, interview segments, and expert reflections in `memory_nodes`. When a stimulus $q$ is presented, Graita computes the stimulus embedding once and scores each memory node $m$ using a weighted combination of Recency, Poignancy (Importance), and Cosine Relevance:

Score(m, q) = 0.20 × (0.995 ^ Δhours) + 0.30 × (Importance(m) / 10.0) + 0.50 × CosineSimilarity(e_m, e_q)

4-Domain Expert Reflection

Each agent is synthesized with four distinct analytical lenses: Psychologist (Big Five OCEAN, anxieties, motivations), Behavioral Economist (loss aversion, elasticity, subscription fatigue), Sociologist (peer norms, reference groups), and Demographer (household lifecycle & dependents).

Two-Step Anti-Sycophancy Monologue

Before outputting `purchase_intent_score` (0–100) or `willingness_to_pay_idr`, every agent must generate an honest first-person `internal_monologue` weighing the offer against their actual monthly `discretionary_budget_idr`.

2. Authentication & Credit Metering

Create an API key in your dashboard under API Keys (`/settings?tab=tokens`). All programmatic requests authenticate via the standard `Authorization: Bearer gr_live_...` header.

Authorization: Bearer gr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Credit Metering: 1 simulation credit equals 1 Digital Twin evaluation round. Running an 8-agent cohort with 1 round of Social Graph Diffusion (Round 0 independent + Round 1 post-diffusion) consumes `8 × 2 = 16` credits.

3. REST API `/v1` Endpoints

GET/v1/cohorts

List Population Cohorts

Returns all Pre-Built Global Verified Panels (coh_global_id_urban, coh_global_b2b_sea) and custom workspace cohorts.

curl https://api.graita.com/v1/cohorts \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx"

POST/v1/cohorts

Synthesize Custom Population Cohort

Generates a custom Digital Twin cohort from natural language using the Hybrid 3-Tier Population Synthesizer, complete with 4-Domain Expert Reflections and Small-World social edges.

curl -X POST https://api.graita.com/v1/cohorts \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pemilik Warung & Grosir Jawa Timur",
    "region": "Indonesia (Surabaya & Malang)",
    "agent_count": 8,
    "generation_prompt": "Pemilik toko kelontong dan agen sembako dengan omzet Rp 30-120 juta/bulan."
  }'

POST/v1/cohorts/import-csv

Import Customer Panel from CSV

Compiles CSV rows (full_name, age, gender, location, occupation, monthly_income_idr, discretionary_budget_idr, backstory) into calibrated Digital Twins.

curl -X POST https://api.graita.com/v1/cohorts/import-csv \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Subscribers Q4",
    "region": "Indonesia",
    "csv_content": "full_name,age,gender,location,occupation,monthly_income_idr,discretionary_budget_idr,backstory\nDewi Lestari,32,Female,Jakarta,Brand Manager,18000000,3500000,Teliti membaca komposisi produk."
  }'

POST/v1/simulations

Run Behavioral Simulation

Queues and executes a concurrent multi-agent simulation (Round 0 independent evaluation + optional Small-World social diffusion rounds).

curl -X POST https://api.graita.com/v1/simulations \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cohort_id": "coh_global_id_urban",
    "title": "Uji Harga Langganan Kopi Pagi",
    "stimulus_type": "pricing_conjoint",
    "stimulus_context": "Paket langganan 20 cup kopi susu bebas pilih cabang Rp 249.000/bulan.",
    "stimulus_variants": [
      {"id": "v1", "name": "Paket Basic 20 Cup", "description": "Ambil di outlet", "price_idr": 249000},
      {"id": "v2", "name": "Paket Delivery Plus", "description": "Gratis antar pagi", "price_idr": 329000}
    ],
    "enable_social_diffusion": true,
    "diffusion_rounds": 1
  }'

GET/v1/simulations/{id}

Get Simulation Results & Verbatim Monologues

Returns aggregate metrics, AI Executive Summary, variant preference shares, social diffusion shifts, and every Digital Twin's verbatim internal_monologue.

curl https://api.graita.com/v1/simulations/sim_01J9XXXXXX \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx"

GET/v1/simulations/{id}/export?format=csv|json

Export Simulation Dataset (CSV / JSON)

Downloads all individual Digital Twin responses across rounds as a CSV spreadsheet or structured JSON bundle.

curl -L "https://api.graita.com/v1/simulations/sim_01J9XXXXXX/export?format=csv" \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx" \
  -o simulation-results.csv

POST/v1/focus-groups

Convene Virtual Focus Group or 1-on-1 Interview

Opens an interactive session with 1 to 6 Digital Twins to probe their objections or test counter-offers.

curl -X POST https://api.graita.com/v1/focus-groups \
  -H "Authorization: Bearer gr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cohort_id": "coh_global_id_urban",
    "title": "Deep Dive: Price Objections",
    "session_type": "focus_group",
    "scenario_context": "Menggali alasan keberatan harga langganan bulanan.",
    "participant_agent_ids": ["agt_id_01", "agt_id_02", "agt_id_03"]
  }'