> ## 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. # Compare two interactions > Measure two interactions against the same protocol and return the differential. **Use cases:** - Before/after training assessment - A/B testing of interaction approaches - Agent version comparison - Quality trend analysis across time periods ## OpenAPI ````yaml /openapi/client_v1_0.json post /api/v1/sense/compare 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/compare: post: tags: - Sense summary: Compare two interactions description: >- Measure two interactions against the same protocol and return the differential. **Use cases:** - Before/after training assessment - A/B testing of interaction approaches - Agent version comparison - Quality trend analysis across time periods operationId: senseCompare requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SenseCompareRequest' examples: training_comparison: summary: Before/after training value: target: type: protocol id: customer-service-quality interaction_a: label: Before training content: >- Your complaint has been noted. Someone will get back to you. interaction_b: label: After training content: >- I completely understand how frustrating this must be. Let me personally ensure this is resolved by end of day. responses: '200': description: Comparison complete content: application/json: example: target: type: protocol id: customer-service-quality version: '1.0' interaction_a: label: Before training score: 0.31 resonance: Empathetic Acknowledgment: 0.15 Clear Resolution: 0.42 metamarkers_triggered: 1 interaction_b: label: After training score: 0.91 resonance: Empathetic Acknowledgment: 0.95 Clear Resolution: 0.88 metamarkers_triggered: 2 delta: score_change: 0.6 direction: improvement resonance_shifts: Empathetic Acknowledgment: a: 0.15 b: 0.95 change: 0.8 Clear Resolution: a: 0.42 b: 0.88 change: 0.46 metamarker_change: 1 ics: consumed: 3 cost_usd: 0.009 '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 components: schemas: SenseCompareRequest: type: object required: - target - interaction_a - interaction_b properties: target: type: object required: - type - id properties: type: type: string enum: - protocol - metric id: type: string version: type: string interaction_a: type: object required: - content properties: label: type: string description: Optional label for this interaction (e.g. 'Before training') content: type: string segments: type: array items: type: object interaction_b: type: object required: - content properties: label: type: string content: type: string segments: type: array items: type: object 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 securitySchemes: BearerAuth: type: http scheme: bearer description: API token from Atlas Dashboard ````