Documentation

Quick Start

Five minutes from API key to your first intelligence output. This guide walks through creating a key, sending your first request, polling for results, and interpreting what comes back.

1. Create an API key

Sign in to BIE and go to Developer → API Keys. Click Add key, give it a name (e.g. Production), and copy the generated value. The full secret is shown exactly once, store it in your environment variables or a secrets manager immediately.

Caution
Keys start with bie_. Never commit them to source control and never expose them in client-side JavaScript. All API calls should happen from your server.

2. Send your first events

The /api/v1/ingest endpoint accepts an array of interaction events. An event is the atomic unit BIE analyzes, one message, one comment, one review. Every event needs three fields: actor_id, content, andtimestamp. Everything else is optional.

Using curl

bash
curl -X POST https://bieintel.com/api/v1/ingest \
  -H "Authorization: Bearer bie_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "actor_id": "reviewer_1",
        "content": "Great pizza, fast delivery, will order again",
        "timestamp": "2026-04-01T18:12:00Z",
        "metadata": { "rating": 5, "source": "google" }
      },
      {
        "actor_id": "reviewer_2",
        "content": "Arrived cold, waited 45 minutes, will not return",
        "timestamp": "2026-04-02T19:30:00Z",
        "metadata": { "rating": 2, "source": "google" }
      }
    ],
    "pipeline": "auto"
  }'

Using the TypeScript SDK

typescript
import { BIEClient } from '@bie/sdk'

const bie = new BIEClient(process.env.BIE_API_KEY!)

const intelligence = await bie.analyze([
  {
    actor_id: 'reviewer_1',
    content: 'Great pizza, fast delivery, will order again',
    timestamp: '2026-04-01T18:12:00Z',
  },
  {
    actor_id: 'reviewer_2',
    content: 'Arrived cold, waited 45 minutes, will not return',
    timestamp: '2026-04-02T19:30:00Z',
  },
])

console.log(intelligence.plain_summary)
console.log(intelligence.plain_recommendations)

The pipeline: "auto" option lets the engine characterize your data and pick the right analysis approach, Layer Z scoring for AI-mediated conversations, review analysis for static review datasets, or support-flow analysis for support tickets. You can override it explicitly when you already know.

3. Poll for results

POST /ingest returns a session_id immediately. Analysis happens asynchronously in our worker pool. Poll /api/v1/intelligence/:session_id until status iscomplete or failed. The SDK handles this loop for you via waitForIntelligence.

bash
curl https://bieintel.com/api/v1/intelligence/SESSION_ID \
  -H "Authorization: Bearer bie_your_key_here"

Webhooks (optional)

For production workloads, skip polling entirely. Register a webhook URL and BIE will POST the completed intelligence to your endpoint the moment analysis finishes. See the Webhooks guide.

4. Interpret the output

A completed intelligence response has the following top-level shape:

json
{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "complete",
  "event_count": 2,
  "environment_type": "review_dataset",
  "plain_summary": "The two reviews reveal a quality-of-service split...",
  "plain_recommendations": [
    "Late-delivery complaints are operational, not reputational.",
    "Protect packaging quality, it is your genuine differentiator."
  ],
  "full_output": { "pipeline": "review", "intelligence": { "...": "..." } }
}

Three fields are doing the real work:

  • environment_type, what the engine determined your data represents (e.g. review_dataset, community, comment_section). This drives the shape of full_output.
  • plain_summary, a senior-analyst voice describing what is happening in the environment. Surface this directly to your users.
  • plain_recommendations, specific, actionable next steps. Every item is tied to evidence in full_output.
Note
The quiet principle. If the data does not support a particular analysis, BIE returns no fields for it rather than fabricating. Always null-check optional fields before rendering.

Next steps