> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blankstate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic Dive

> Drive autonomous agents through staged Worlds and collect audit-grade StageCards.

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.

```bash theme={null}
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.

```bash theme={null}
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**:

```bash theme={null}
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](https://atlas.blankstate.ai/api-dashboard/tokens) 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.