Testing Endpoints¶

The testing system allows agents to complete personality assessments that initialize or update their behavioral profile.

Get Test Questions¶

GET /test/questions

Get personality test questions.

Query Parameters¶

Parameter	Type	Default	Notes
`version`	string	"v1"	Test version (v1, v2, v3 — increasing depth)

Response¶

{
  "data": {
    "version": "v1",
    "question_count": "...",
    "questions": [
      {
        "id": "q1",
        "text": "When facing a novel problem, I prefer to:",
        "options": [
          { "id": "q1_a", "text": "Gather more information and understand it thoroughly" },
          { "id": "q1_b", "text": "Try different approaches to see what works" },
          { "id": "q1_c", "text": "Apply proven methods I know work" },
          { "id": "q1_d", "text": "Make a decision and commit to it" }
        ]
      },
      {
        "id": "q2",
        "text": "In group settings, I tend to:",
        "options": [
          { "id": "q2_a", "text": "Observe and listen carefully" },
          { "id": "q2_b", "text": "Suggest new ideas and approaches" },
          { "id": "q2_c", "text": "Help organize and keep things on track" },
          { "id": "q2_d", "text": "Build relationships and support others" }
        ]
      }
    ]
  }
}

Examples¶

PythoncURL

questions = client.test.get_questions(version="v1")
print(f"Total questions: {len(questions.data.questions)}")

curl -X GET 'https://api.identity-os.dev/v1/test/questions?version=v1' \
  -H "Authorization: Bearer idos_sk_xxx"

Submit Test¶

POST /test/submit

Submit test responses to initialize or update an agent's behavioral profile.

Request¶

{
  "instance_id": "inst_9f190826e20c49ea",
  "version": "v1",
  "responses": [
    {
      "question_id": "q1",
      "selected_option_id": "q1_b"
    },
    {
      "question_id": "q2",
      "selected_option_id": "q2_d"
    }
  ]
}

Or create a new instance during submission:

{
  "create_instance": true,
  "instance_name": "TestAgent",
  "version": "v1",
  "responses": [
    {
      "question_id": "q1",
      "selected_option_id": "q1_b"
    }
  ]
}

Fields¶

Field	Type	Required	Notes
`instance_id`	string	Conditional	Required if not creating
`create_instance`	bool	Conditional	Required if no instance_id
`instance_name`	string	If creating	Name for new instance
`version`	string	No	Default "v1"
`responses`	array	Yes	List of responses

Response¶

{
  "data": {
    "instance_id": "inst_9f190826e20c49ea",
    "test_completed": true,
    "mode_profile": {
      "perception": 0.50,
      "exploration": 0.50,
      "order": 0.50,
      "assertion": 0.50,
      "connection": 0.50,
      "identity": 0.50,
      "stress_response": 0.50
    },
    "matched_personas": [
      {
        "name": "The Performer",
        "id": "persona_performer",
        "match_score": 0.50
      },
      {
        "name": "The Catalyst",
        "id": "persona_catalyst",
        "match_score": 0.50
      }
    ],
    "snapshot": {
      "instance_id": "inst_9f190826e20c49ea",
      "cycle": 1,
      "mode_strengths": {
        "perception": 0.50,
        "exploration": 0.50,
        "order": 0.50,
        "assertion": 0.50,
        "connection": 0.50,
        "identity": 0.50,
        "stress_response": 0.50
      },
      "energy_level": 0.50,
      "stress_state": "LOW",
      "stability_index": 1.0
    },
    "contract": {
      "dominant_modes": ["Connection", "Identity"],
      "suppressed_modes": ["Order"],
      "allowed_actions": [
        "explore",
        "question",
        "elaborate",
        "suggest",
        "connect"
      ],
      "forbidden_actions": ["emotional_manipulation", "identity_override"],
      "decision_style": {
        "tempo": "exploratory",
        "risk": "seeking",
        "expressiveness": "high",
        "commitment_threshold": "low"
      },
      "energy_level": 0.50,
      "stress_state": "LOW"
    }
  }
}

Examples¶

PythoncURL

# Submit for existing instance
result = client.test.submit(
    instance_id="inst_xxx",
    responses=[
        {"question_id": "q1", "selected_option_id": "q1_b"},
        {"question_id": "q2", "selected_option_id": "q2_d"},
    ]
)

print(f"Matched: {result.matched_personas[0].name}")
print(f"Contract: {result.contract}")

# Or create new instance
result = client.test.submit(
    create_instance=True,
    instance_name="NewAgent",
    responses=[...]
)

print(f"Created: {result.instance_id}")

curl -X POST https://api.identity-os.dev/v1/test/submit \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_xxx",
    "responses": [
      {"question_id": "q1", "selected_option_id": "q1_b"},
      {"question_id": "q2", "selected_option_id": "q2_d"}
    ]
  }'

Test Versions¶

v1: Quick Assessment¶

Time: ~2 minutes Complexity: Basic Coverage: All 7 modes, basic persona matching

Best for: Initial setup, quick validation

v2: Comprehensive¶

Time: ~5 minutes Complexity: Medium Coverage: All 7 modes + persona nuances, decision style

Best for: Detailed personality initialization, persona matching

v3: Deep Dive¶

Time: ~10 minutes Complexity: Advanced Coverage: All dimensions, stress patterns, recovery profiles

Best for: Enterprise deployments, compliance/audit, detailed profiling

How It Works¶

The system analyzes your responses and generates a behavioral profile:

Processes selected answers
Generates initial mode profile
Matches against 12 personas
Creates execution contract
Initializes instance state

Persona Matching¶

After test submission, the system compares the resulting mode profile to all 12 persona definitions and returns the top matches:

{
  "matched_personas": [
    {
      "name": "The Performer",
      "id": "persona_performer",
      "match_score": 0.50
    },
    {
      "name": "The Creator",
      "id": "persona_creative",
      "match_score": 0.50
    },
    {
      "name": "The Catalyst",
      "id": "persona_catalyst",
      "match_score": 0.50
    }
  ]
}

Match score ranges from 0.0 (no match) to 1.0 (perfect match). Typical results are 0.7–0.95.

Using Test Results¶

Pattern 1: Initialize from Test¶

# User takes test
questions = client.test.get_questions(version="v1")
# ... present questions to user, collect responses ...
user_responses = [...]

# Submit and initialize instance
result = client.test.submit(
    create_instance=True,
    instance_name="UserAgent",
    responses=user_responses
)

instance_id = result.instance_id
print(f"Agent initialized: {instance_id}")
print(f"Matched personas: {result.matched_personas}")

Pattern 2: Periodic Re-assessment¶

# Re-assess after significant interactions
result = client.test.submit(
    instance_id="inst_xxx",
    responses=new_responses
)

# Compare old vs new profile
old_profile = snapshot.mode_strengths
new_profile = result.snapshot.mode_strengths

changes = {
    k: new_profile[k] - old_profile[k]
    for k in old_profile.keys()
}

print("Mode changes:", changes)

Pattern 3: Validate Test Quality¶

# Check if test responses are consistent
result = client.test.submit(instance_id, responses_set_1)
profile_1 = result.mode_profile

# Have user retake test
result = client.test.submit(instance_id, responses_set_2)
profile_2 = result.mode_profile

# Calculate stability
stability = 1.0 - sum(abs(profile_1[k] - profile_2[k]) for k in profile_1) / 7
print(f"Test stability: {stability:.2f}")  # Should be > 0.8

if stability < 0.7:
    print("WARNING: Test responses may not be reliable")

Error Handling¶

Missing Responses¶

If you don't provide responses for all questions:

{
  "error": "incomplete_test",
  "message": "Incomplete test submission — some questions were not answered",
  "missing_questions": ["q5", "q12", "q18", "q24"]
}

Solution: Either complete all questions or use a shorter test version.

Invalid Instance¶

If instance doesn't exist:

{
  "error": "not_found",
  "message": "instance_id 'inst_xxx' not found"
}

Conflicting Parameters¶

{
  "error": "invalid_request",
  "message": "Cannot specify both instance_id and create_instance"
}

FAQ¶

Can I retake a test?

Yes. Submitting new responses to an existing instance will overwrite the previous test-based profile. Subsequent observations will gradually evolve the profile from there.

How long should I spend on each question?

There's no time limit. Spend however long you need to give your honest answer. Rushed responses may reduce reliability.

Can I update my instance later?

Yes. After the initial test, send observations to update the behavioral profile gradually. The test establishes an initial point; observations refine it.

Do personas change?

The 12 personas are fixed reference points. Your instance's mode profile can change (via observations), causing different persona matches over time.

Next Steps¶

Understand Personas — What the 12 archetypes are
Learn Concepts — How modes and personas work
Try Quickstart — Use testing in a real scenario