> ## 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. # Sense interaction > Measure an interaction against a protocol or metric. The protocol defines what gets measured. The API delivers the result. No user-configurable parameters affect the measurement itself, only the output detail level (via `profile`). ## OpenAPI ````yaml /openapi/client_v1_0.json post /api/v1/sense openapi: 3.1.0 info: title: Blankstate IBF API version: 0.2.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 Version The API currently runs against SGM **0.2** in production. The API URL stays `/api/v1/` across model iterations. Existing Protocols continue to run against the same URL as the underlying model advances; version pinning lives on the Protocol itself. ### Base URL ``` https://ibf.blankstate.ai ``` ### 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://ibf.blankstate.ai description: Production 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 paths: /api/v1/sense: post: tags: - Sense summary: Sense interaction description: >- Measure an interaction against a protocol or metric. The protocol defines what gets measured. The API delivers the result. No user-configurable parameters affect the measurement itself, only the output detail level (via `profile`). operationId: sense requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SenseRequest' examples: text_raw: summary: Text input (raw) value: target: type: protocol id: customer-service-quality interaction: content: >- Thank you for calling. I understand your concern about the billing discrepancy. Let me look into this right away and find a resolution for you. text_detailed: summary: Text input (detailed profile) value: target: type: protocol id: customer-service-quality interaction: content: >- Thank you for calling. I understand your concern about the billing discrepancy. options: profile: detailed transcript: summary: Transcript (multi-turn) value: target: type: protocol id: advisor-suitability interaction: segments: - role: advisor content: What's your investment horizon? - role: client content: About 10 years, for retirement. - role: advisor content: >- That gives us flexibility. Let me explain the risk considerations. audio: summary: Audio file (speech-to-sense) value: target: type: protocol id: customer-service-quality interaction: url: https://storage.example.com/calls/call-20260206-001.mp3 language: en document: summary: Document (PDF/OCR) value: target: type: protocol id: disclosure-compliance interaction: url: https://storage.example.com/docs/disclosure-form.pdf metric: summary: Sense against metric value: target: type: metric id: overall-quality interaction: content: >- Your capital is at risk. Past performance is not indicative of future results. v1_5_actant: summary: With actant flow (v1.5 protocol) value: target: type: protocol id: advisor-suitability version: '1.5' interaction: segments: - role: advisor content: What's your risk tolerance? - role: client content: I'm fairly conservative. v1_5: actant: primary: advisor analyze_flow: true v1_5_temporal: summary: With temporal dynamics (v1.5 protocol) value: target: type: protocol id: customer-service-quality version: '1.5' interaction: segments: - role: agent content: How can I help you today? timestamp: 0 - role: customer content: I've been waiting 20 minutes! timestamp: 5 - role: agent content: >- I apologize for the wait. Let me resolve this immediately. timestamp: 12 v1_5: temporal: analyze_dynamics: true window_seconds: 30 with_callback: summary: With webhook callback (async) value: target: type: protocol id: disclosure-compliance interaction: url: https://storage.example.com/docs/large-report.pdf callback: url: https://yourapp.example.com/webhooks/blankstate events: - complete - error responses: '200': description: Sensing complete content: application/json: examples: v1_0_raw: summary: v1.0, raw value: target: type: protocol id: customer-service-quality version: '1.0' score: 0.87 resonance: Empathetic Acknowledgment: 0.92 Clear Resolution: 0.88 evidence: - metamarker: Empathetic Acknowledgment score: 0.92 source: >- I understand your concern about the billing discrepancy - metamarker: Clear Resolution score: 0.88 source: Let me look into this right away and find a resolution fidelity: index: 0.78 sufficient: true ics: consumed: 2 cost_usd: 0.006 sgm_version: '1.0' v1_0_detailed: summary: v1.0, detailed profile value: target: type: protocol id: customer-service-quality version: '1.0' profile: detailed score: 0.87 resonance: Empathetic Acknowledgment: 0.92 Clear Resolution: 0.88 evidence: - metamarker: Empathetic Acknowledgment score: 0.92 source: >- I understand your concern about the billing discrepancy reconstruction: segment_text: >- Thank you for calling. I understand your concern about the billing discrepancy. attribution: Direct empathy language, acknowledges specific issue actant: agent fidelity: index: 0.78 sufficient: true ics: consumed: 2 cost_usd: 0.006 sgm_version: '1.0' v1_0_discovery: summary: v1.0, discovery profile value: target: type: protocol id: customer-service-quality version: '1.0' profile: discovery score: 0.87 resonance: Empathetic Acknowledgment: 0.92 Clear Resolution: 0.88 evidence: - metamarker: Empathetic Acknowledgment score: 0.92 source: >- I understand your concern about the billing discrepancy weak_signals: - metamarker: Proactive Follow-up proximity: 0.41 hint: >- Near-threshold activation, content approaches this pattern but does not fully satisfy it fidelity: index: 0.78 sufficient: true ics: consumed: 2 cost_usd: 0.006 sgm_version: '1.0' v1_5_enhanced: summary: v1.5, with signal analysis + actant flow value: target: type: protocol id: advisor-suitability version: '1.5' score: 0.85 resonance: Suitability Check: 0.91 Risk Disclosure: 0.79 evidence: - metamarker: Suitability Check score: 0.91 source: What's your risk tolerance? actant: advisor signal: spread: 0.73 coherence: 0.85 dominant_mode: Suitability Check fidelity: index: 0.72 sufficient: true density: 0.68 clarity: 0.81 actant_flow: primary_driven: - Suitability Check - Risk Disclosure secondary_driven: - Client Understanding direction: advisor → client balance: 0.65 temporal: trend: stable phase_shifts: 0 ics: consumed: 2 cost_usd: 0.007 sgm_version: '1.5' '202': description: >- Accepted, processing asynchronously (large files or when callback is provided) content: application/json: example: job_id: job_8f3a2b1c status: processing estimated_seconds: 45 poll_url: /api/v1/jobs/job_8f3a2b1c callback_registered: true '400': $ref: '#/components/responses/BadRequest' description: Invalid request format or missing required fields '401': $ref: '#/components/responses/Unauthorized' description: Invalid or missing authentication token '402': $ref: '#/components/responses/QuotaExhausted' description: ICS quota exhausted for current period '404': $ref: '#/components/responses/TargetNotFound' description: Protocol, metric, or blueprint not found '422': $ref: '#/components/responses/InsufficientFidelity' description: Content lacks sufficient signal for reliable measurement components: schemas: SenseRequest: type: object required: - target - interaction properties: target: type: object required: - type - id description: What to measure against properties: type: type: string enum: - protocol - metric description: Target type id: type: string description: Target identifier version: type: string description: 'Target version (default: latest published)' interaction: type: object description: The interaction content to sense properties: type: type: string enum: - text - transcript - audio - document description: >- Optional, the sensor infers modality from content shape (content → text, segments → transcript, url → file). Provide explicitly only when needed. content: type: string description: 'Text content (for type: text)' segments: type: array description: 'Structured segments (for type: transcript)' items: type: object properties: role: type: string description: Speaker role (e.g. advisor, client, agent) content: type: string description: Segment text content timestamp: type: number description: Offset in seconds from interaction start url: type: string format: uri description: 'File URL (for type: audio or document)' language: type: string default: en description: ISO 639-1 language code options: type: object description: >- Output configuration. Does not affect the measurement, only the detail level of the response. properties: profile: type: string enum: - raw - detailed - discovery default: raw description: >- Sensing profile: raw (default, raw sensor output), detailed (+ deep evidence chains), discovery (+ weak signal indicators) v1_5: type: object description: >- Engine v1.5 features. Only applied when the target protocol is version 1.5. properties: actant: type: object description: Actant flow analysis properties: primary: type: string description: Primary role to evaluate (e.g. advisor, agent) analyze_flow: type: boolean default: false description: Include directional flow analysis between actants temporal: type: object description: Temporal dynamics analysis properties: analyze_dynamics: type: boolean default: false description: Include temporal trend and phase shift detection window_seconds: type: integer description: Analysis window size in seconds (for streaming) signal: type: object description: Signal analysis output options properties: include_detail: type: boolean default: true description: Include signal spread and coherence metrics in response callback: type: object description: >- Webhook callback for asynchronous processing. When provided, the API returns 202 Accepted immediately and delivers results to the callback URL. properties: url: type: string format: uri description: HTTPS endpoint to receive the result events: type: array items: type: string enum: - complete - error - progress default: - complete - error description: Which events to deliver responses: BadRequest: description: Invalid request, missing required fields or invalid format content: application/json: example: error: code: invalid_request message: The 'interaction.content' field is required for type 'text' Unauthorized: description: Invalid or missing authentication token content: application/json: example: error: code: unauthorized message: >- Invalid or expired API token. Obtain a new token from atlas.blankstate.ai QuotaExhausted: description: ICS quota exhausted, free tier consumed and no payment method on file content: application/json: example: error: code: quota_exhausted message: >- Your free ICS quota for this period has been consumed. Add a payment method at atlas.blankstate.ai to continue. details: quota: 50 used: 50 reset: '2026-03-01T00:00:00Z' TargetNotFound: description: The specified protocol, metric, or blueprint was not found content: application/json: example: error: code: target_not_found message: >- Protocol 'non-existent-protocol' not found or not available to your organization InsufficientFidelity: description: Content has insufficient signal for reliable sensing content: application/json: example: error: code: insufficient_fidelity message: >- Content does not meet minimum fidelity threshold for reliable sensing. Use /fidelity/check to pre-validate. details: fidelity_index: 0.12 minimum_required: 0.3 recommendation: >- Provide at least 100 characters of substantive interaction content securitySchemes: BearerAuth: type: http scheme: bearer description: API token from Atlas Dashboard ````