> ## 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. # Open a dive > Open a session against a published Stage. Your agent brings its own model + prompts; only its actions cross the wire. Access, metering, attempt policy and password are enforced here before any world boot. ## OpenAPI ````yaml /openapi/client_v1_0.json post /api/v1/dive/open openapi: 3.1.0 info: title: Blankstate IBF API version: 1.0.0 description: >- ## Universal Interaction Sensing Measure any interaction against configurable **Protocols**, **Metrics**, and **Blueprints**. ### Core Concepts | Concept | Description | |---------|-------------| | **Protocol** | A sensor that detects specific interaction patterns (metamarkers) | | **Metric** | Weighted aggregation of protocol scores | | **Blueprint** | A complete sensing configuration — multiple protocols + metrics | | **ICS** | Interaction Computed Signal — outcome-based billing (1 ICS = 1 triggered metamarker) | | **Fidelity** | Information sufficiency — does the input contain enough signal for reliable measurement? | ### Sensing Profiles Every sensing request accepts an optional `profile` parameter. The default is `raw`. | Profile | Description | |---------|-------------| | `raw` | *(default)* Raw sensor output. The sensor measures exactly what the protocol defines. Nothing added, nothing filtered. | | `detailed` | Same measurement + deep evidence chains with segment-level attribution and full reconstruction provenance. | | `discovery` | Same measurement + weak signal indicators. Near-threshold activations are reported separately so you can explore what the sensor _almost_ detected. | All profiles are **deterministic**: same profile + same input + same protocol = same output, always. ### SGM Versions | Version | Status | Capabilities | |---------|--------|-------------| | **1.0** | Stable | Core sensing, resonance detection, evidence chains | | **1.5** | Preview | + Signal analysis, actant flow, temporal dynamics, fidelity | SGM version is determined by the **protocol configuration**, not the API URL. ### Base URL ``` https://api.blankstate.ai ``` *(Legacy alias `https://ibf.blankstate.ai` remains fully supported)* ### Authentication ``` Authorization: Bearer YOUR_API_TOKEN ``` Obtain tokens from the [Atlas Dashboard](https://atlas.blankstate.ai/api-dashboard/tokens). ### Response Headers Every sensing response includes: | Header | Description | |--------|-------------| | `X-ICS-Consumed` | ICS consumed by this request | | `X-ICS-Remaining` | Remaining ICS quota for current period | | `X-RateLimit-Limit` | Maximum requests per window | | `X-RateLimit-Remaining` | Remaining requests in current window | | `X-RateLimit-Reset` | Unix timestamp when the rate limit resets | contact: name: Blankstate AI url: https://blankstate.ai email: contact@blankstate.ai servers: - url: https://api.blankstate.ai description: Production (canonical) - url: https://ibf.blankstate.ai description: Production (legacy alias) security: - BearerAuth: [] tags: - name: Health description: Service status and token verification - name: Sense description: >- Core measurement — sense interactions against protocols, metrics, or blueprints - name: Fidelity description: Pre-check information sufficiency before sensing (zero ICS cost) - name: Protocols description: Protocol sensors — browse and inspect detection configurations - name: Metrics description: Weighted aggregations of protocol scores - name: Blueprints description: Complete sensing configurations — protocols + metrics composed together - name: Usage description: ICS consumption, quotas, and cost estimation - name: Jobs description: Asynchronous job tracking for large file and batch processing - name: Capabilities description: Machine-readable API capability descriptions for tooling integration - name: Dive description: >- Programmatic Dive — connect your own agent to a published Stage (open → act → close) and earn a StageCard. paths: /api/v1/dive/open: post: tags: - Dive summary: Open a dive description: >- Open a session against a published Stage. Your agent brings its own model + prompts; only its actions cross the wire. Access, metering, attempt policy and password are enforced here before any world boot. operationId: openDive requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OpenDiveRequest' responses: '200': description: Dive opened. content: application/json: schema: $ref: '#/components/schemas/DiveOpenResponse' '401': description: Missing or invalid token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Not entitled to this Stage, wrong password, or attempts exhausted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Rate limited, too many open dives, ICS quota exhausted, or attempt cooldown. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: World temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: OpenDiveRequest: type: object required: - stage_id properties: stage_id: type: string description: Published Stage id your token is entitled to dive. session_id: type: string description: Only for a session-scoped publication. password: type: string description: Shared password, if the publication is password-protected. agent: $ref: '#/components/schemas/AgentInfo' seed: type: integer description: Deterministic seed; server assigns one if omitted. DiveOpenResponse: type: object properties: dive_id: type: string seed: type: integer mode: type: string enum: - graded - practice stage_version: type: string nullable: true blueprint_version: type: string nullable: true envelope: $ref: '#/components/schemas/DiveEnvelope' objective: type: string rules: type: object properties: checkpoints: type: array items: type: string flags: type: array items: type: string max_turns: type: integer observation: $ref: '#/components/schemas/Observation' ErrorResponse: type: object description: Standard error response format required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code enum: - invalid_request - unauthorized - token_expired - quota_exhausted - target_not_found - insufficient_fidelity - unsupported_modality - content_too_large - rate_limited - job_not_found - internal_error message: type: string description: Human-readable error description details: type: object description: Additional context (varies by error code) AgentInfo: type: object description: Your agent's audit tag (never Blankstate's model). properties: id: type: string description: Your own identifier for the agent under test. version: type: string description: Agent version, for replay/leaderboard grouping. DiveEnvelope: type: object description: Billing + disclosure envelope for the dive. properties: access_mode: type: string enum: - free - ics description: Whether the dive is metered. share_scorecard: type: boolean description: If false, the StageCard is verdict-only to the diver. max_turns: type: integer ics_budget: type: number nullable: true Observation: type: object description: What the world returns after an action (the arrival state on open). properties: turn: type: integer world: type: string description: The rendered world/surface state. done: type: boolean securitySchemes: BearerAuth: type: http scheme: bearer description: API token from Atlas Dashboard ````