> ## 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. # Take one action > Submit one action; the world advances and the moment is sensed. Must be driven by the same token that opened the dive. If a flag trips or a limit is reached the dive auto-closes and a StageCard is returned. ## OpenAPI ````yaml /openapi/client_v1_0.json post /api/v1/dive/{dive_id}/act 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/{dive_id}/act: post: tags: - Dive summary: Take one action description: >- Submit one action; the world advances and the moment is sensed. Must be driven by the same token that opened the dive. If a flag trips or a limit is reached the dive auto-closes and a StageCard is returned. operationId: actDive parameters: - name: dive_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActRequest' responses: '200': description: Action applied. content: application/json: schema: oneOf: - $ref: '#/components/schemas/DiveActResponse' - $ref: '#/components/schemas/StageCard' '403': description: Token does not match the dive opener. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No such dive (expired or never opened). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Dive already closed, or turn out of sequence. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited or ICS quota exhausted mid-dive. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ActRequest: type: object required: - action properties: turn: type: integer description: >- Idempotency key: the turn this action answers. Replaying the same turn returns the same observation. action: description: >- The action your agent takes — a plain string or a structured DiveAction. oneOf: - type: string - $ref: '#/components/schemas/DiveAction' DiveActResponse: type: object description: >- Result of an action. If a flag trips or the budget/turn limit is reached, the dive auto-closes and a StageCard is returned instead. properties: observation: $ref: '#/components/schemas/Observation' reading: $ref: '#/components/schemas/Reading' running: type: object description: Running totals across the dive. properties: turns: type: integer ics_spent: type: number on_target_rate: type: number nullable: true StageCard: type: object description: >- Audit-grade evidence artifact produced when a dive closes. Tiered: the verdict is always present; the reading trace is included only when `share_scorecard` is true. properties: dive_id: type: string stage_id: type: string status: type: string enum: - closed verdict: type: object properties: passed: type: boolean reason: type: string checkpoints_hit: type: array items: type: string flags_tripped: type: array items: type: string totals: type: object properties: turns: type: integer score: type: number nullable: true on_target: type: number nullable: true ics: type: number readings: type: array description: Per-turn reading trace. Omitted/empty when share_scorecard is false. items: $ref: '#/components/schemas/Reading' signature: type: string description: Skill Signature emitted on close. 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) DiveAction: type: object description: A structured action. A bare string is also accepted in `action`. properties: kind: type: string description: message | tool_call | ui | command | annotate | submit … name: type: string description: Tool name for a tool_call. arguments: type: object additionalProperties: true content: type: string text: type: string 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 Reading: type: object description: >- Live sensing signal for the turn (present only when the Stage has a calibrated target). properties: score: type: number nullable: true on_target: type: boolean nullable: true fidelity: type: number nullable: true ics: type: number description: ICS metered for this moment (0 for a null moment or free dive). securitySchemes: BearerAuth: type: http scheme: bearer description: API token from Atlas Dashboard ````