API Reference

Every public endpoint. Generated from the OpenAPI 3.1 spec available at /api/v1/openapi. All endpoints are rooted at https://bieintel.com/api/v1.

Authentication

Every request requires a Bearer token in the Authorization header. Keys start with bie_ and are created from Developer → API Keys in the app.

Authorization: Bearer bie_your_key_here

Error shape

Errors return a JSON object with a machine-readable code and human-readable message.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one event is required"
  }
}

POST /ingest

Submit interaction events for analysis. Returns a session ID to poll. The engine runs environmental assessment and selects the appropriate pipeline automatically.

Request body

BIEEvent schema

{
  "events": [
    {
      "actor_id": "user_jane",
      "content": "The new checkout broke, three customers called in already.",
      "timestamp": "2026-04-01T14:23:00Z",
      "context": "product-feedback",
      "metadata": { "source": "slack", "channel": "#support" }
    }
  ],
  "pipeline": "auto",
  "webhook_url": "https://yourapp.com/webhooks/bie"
}

Response, 202 Accepted

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_count": 1,
  "status": "received"
}

GET /intelligence/:sessionId

Poll for session status. When status is complete, the response includes plain_summary, plain_recommendations, and full_output.

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "complete",
  "event_count": 47,
  "environment_type": "review_dataset",
  "created_at": "2026-04-01T14:30:00Z",
  "completed_at": "2026-04-01T14:31:12Z",
  "plain_summary": "Delivery timing is the dominant negative signal...",
  "plain_recommendations": [
    "16 of 47 reviews reference late or unpredictable delivery windows.",
    "Three reviews mention the same courier, investigate the logistics change."
  ],
  "full_output": {
    "pipeline": "review",
    "intelligence": { "operational_signals": [], "sentiment_trajectory": {} }
  }
}

POST /drift

Compare two time periods. Submit a before and after event set; BIE classifies both, compares behavioral dimensions, and returns a drift analysis. Each period must contain 5–2000 events.

{
  "before": {
    "label": "Pre-launch (Jan–Mar)",
    "events": [ /* 5–2000 events */ ]
  },
  "after": {
    "label": "Post-launch (Apr–Jun)",
    "events": [ /* 5–2000 events */ ]
  },
  "question": "Did the product change affect customer frustration?"
}

Returns 202 Accepted with a session_id and poll_url. Poll GET /drift/:sessionId until complete. Rate limit: 10 drift sessions per hour per key.

GET /drift/:sessionId

Returns the drift analysis when complete, overall_drift, direction, plain_summary, plain_recommendations, key_findings, and dimension_drifts.

POST /webhooks

Register a URL to receive intelligence outputs via HTTP POST. The payload is signed with HMAC-SHA256 using the secret returned at creation.

{
  "url": "https://yourapp.com/webhooks/bie",
  "events": ["intelligence.ready"]
}

Response, 201 Created

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/bie",
  "secret": "whsec_a1b2c3d4e5f6...",
  "events": ["intelligence.ready"],
  "created_at": "2026-04-01T14:30:00Z"
}

GET /webhooks

Returns all active webhooks for the authenticated key: id, url, events, last_delivery_at, and failure_count.

Rate limits

Every response includes standard rate limit headers so you can back off gracefully:

Default limits are 1000 requests per hour and 10000 per day per key. Limits scale with your plan, see Billing & Rate Limits.

OpenAPI spec

The full OpenAPI 3.1 specification is served live at GET /api/v1/openapi. Feed it into Postman, Insomnia, or any OpenAPI code generator.