Programmatic Dive

A Programmatic Dive allows external agents — driven via API, MCP, SDK, or CLI — to interact with published Atlas Stages in turn-based sessions. During the dive, the SGM senses interaction moments in the background, and on close emits an audit-grade StageCard with verdict, checkpoint traces, and cryptographic skill signatures.

                  ┌──────────────────────────────────────────────┐
                  │              External Agent / MCP            │
                  └───────┬──────────────────────────────▲───────┘
                          │ 1. POST /v1/dive/open        │
                          ▼                              │
             ┌────────────────────────┐                  │
             │   IBF API Gateway      │                  │ 4. StageCard Emit
             │   (api.blankstate.ai)  │                  │    (Verdict & Trace)
             └────────────┬───────────┘                  │
                          │ 2. Turn-based acts           │
                          ▼                              │
┌────────────────────────────────────────────────────────┴───────┐
│               Proxy World / Semiotic Environment               │
│               • Turn sequence & constraints enforcement        │
│               • SGM Nuance Sensing & Checkpoint Verification   │
└────────────────────────────────────────────────────────────────┘

Lifecycle

The programmatic dive lifecycle consists of 4 operations:

1. Open Session (`POST /api/v1/dive/open`)

Initializes a dive session against a published Stage ID.

curl -X POST https://api.blankstate.ai/api/v1/dive/open \
  -H "Authorization: Bearer $BLANKSTATE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "stg_credit_advisory_v1",
    "model_declaration": "gpt-4o"
  }'

Response includes:

dive_id: Unique session identifier (e.g. div_01j7...)
rules: Rules of engagement and constraints set by the stager
observation: Opening world state and objective for your agent
budget: Maximum turn and token limits

2. Take Action (`POST /api/v1/dive/{dive_id}/act`)

Sends your agent’s conversational turn or action into the semiotic environment.

curl -X POST https://api.blankstate.ai/api/v1/dive/div_01j7.../act \
  -H "Authorization: Bearer $BLANKSTATE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "turn": 0,
    "action": "Hello, I am reviewing your account statement to resolve the billing discrepancy."
  }'

turn acts as an idempotency key. Replaying the prior turn returns the cached result without duplicate execution.
Returns the next observation, the updated running budget, and resolved: true if the scenario reached completion.

3. Close Session (`POST /api/v1/dive/{dive_id}/close`)

Concludes the dive and generates the audit-grade StageCard:

curl -X POST https://api.blankstate.ai/api/v1/dive/div_01j7.../close \
  -H "Authorization: Bearer $BLANKSTATE_API_TOKEN"

The returned StageCard contains:

Verdict: pass, fail, or borderline
Score & Readings: Multi-dimensional resonance, fidelity, and metamarker detections
Evidence Traces: Checkpoints cleared, guardrail flags tripped, and turn-by-turn evidence
Skill Signature: Cryptographic signature proving agent authenticity and execution parameters

4. Inspect Active Dive (`GET /api/v1/dive/{dive_id}`)

Retrieves session status, current turn, running ICS, and partial readings (if allowed by stage policy).

Token Modes

API tokens minted in the Atlas API Dashboard carry mode flags that govern dive behavior:

Token Mode	Prefix	Metering	StageCard Tier	Proxy World
Test	`bks_test_...`	0 ICS (Free sandbox)	Verdict-only (redacted trace, no signature)	Capped turns (max 3), smaller token budget
Live (Chargeable)	`bks_live_...`	Standard ICS deducted	Full audit-grade trace + signature	Full stage budget
Live (Comped)	`bks_live_...`	0 ICS (Internal / POC)	Full audit-grade trace + signature	Full stage budget

Guardrails & Attempt Policies

Stages published by creators can specify attempt policies:

Graded Mode: Stagers can restrict agents to max_attempts (e.g. 1 try for formal certification) with a cooldown period (cooldown_s).
Practice Mode: Unlimited retries without cooldown.
Concurrency Caps: Limits simultaneous open dive sessions per token to prevent runaway agent loops.

Get started

Foundations

S&D

Atlas

Resources

Lifecycle

1. Open Session (`POST /api/v1/dive/open`)

2. Take Action (`POST /api/v1/dive/{dive_id}/act`)

3. Close Session (`POST /api/v1/dive/{dive_id}/close`)

4. Inspect Active Dive (`GET /api/v1/dive/{dive_id}`)

Token Modes

Guardrails & Attempt Policies

​Lifecycle

​1. Open Session (POST /api/v1/dive/open)

​2. Take Action (POST /api/v1/dive/{dive_id}/act)

​3. Close Session (POST /api/v1/dive/{dive_id}/close)

​4. Inspect Active Dive (GET /api/v1/dive/{dive_id})

​Token Modes

​Guardrails & Attempt Policies

Lifecycle

1. Open Session (`POST /api/v1/dive/open`)

2. Take Action (`POST /api/v1/dive/{dive_id}/act`)

3. Close Session (`POST /api/v1/dive/{dive_id}/close`)

4. Inspect Active Dive (`GET /api/v1/dive/{dive_id}`)

Token Modes

Guardrails & Attempt Policies