Getting started

Quickstart

Go from a blank account to structured, source-backed commercial records in your dashboard — and your first authenticated /v1 API call — in one sitting. No scraping, no source wrangling, no schema design.

Ballast is an autonomous commercial intelligence platform. You describe the slice of the commercial world you need to track — permits, bids, contractors, listings, prices — and Ballast turns it into an intelligence feed: a continuously monitored set of approved sources that a specialized data-agent pipeline reads, cross-checks, and distills into structured records (entities) and typed intelligence events, each carrying source evidence, a verification status, and a confidence score.

Everything a feed produces is delivered four ways: the dashboard, the public /v1 REST API, signed webhooks, and exports. This page walks the whole loop once — configure a feed, approve it, see records arrive, then read the same records over the API and subscribe a webhook.

Note

You do not need a live feed to start integrating. A blst_test_ API key returns synthetic demo data in exactly the production shape (every record is marked is_demo: true), so steps 5–7 work the moment your account exists.

1. Create your account

Sign up at ballastos.com and sign in to the console. A fresh workspace starts empty: no feeds, no keys, no webhooks. Everything below happens inside the console or against the API at https://api.ballastos.com.

2. Configure your first feed

Start the guided feed onboarding from the console and describe what you want to track in plain language — for example "commercial construction projects over $1M entering permitting in the Columbus metro". The onboarding walks you through the target, the geography, and what a useful record looks like for you.

From that description, Ballast assembles a feed proposal:

  • A record schema — the entity type and the attributes each record will carry
  • A source network — the concrete sources the pipeline will monitor, each with its permission status
  • The event types the feed can emit — e.g. permit_filed, permit_approved, contractor_identified

3. Approve the proposal

Nothing runs until you approve. Review the proposed schema, sources, and event types, adjust what you need, and approve the proposal. From that moment the data-agent pipeline monitors the approved sources continuously — you never re-trigger it, and it only reads sources you approved.

4. Watch records and events arrive

Open the feed in the dashboard. Two things accumulate:

  • Records — deduplicated, structured entities. Each one shows its attributes, its version history, its verification_status (from unverified up to multi_source_verified and human_reviewed), a 0–1 confidence score, and the source evidence behind every claim — which source, which URL, retrieved when
  • Intelligence events — typed moments worth acting on (permit_approved, bid_opened, price_reduced, …), each scored for relevance and opportunity and linked to the record it concerns

5. Create a scoped API key

In the console, open API & developers and create a key. You choose exactly what it can do:

  • Scopes — grant only what the integration needs: entities:read, events:read, feeds:read, sources:read, usage:read, exports:create, webhooks:read, webhooks:write
  • Optional expiry, an IP allowlist, and monthly request and data-credit allowances per key
  • Live vs test — blst_live_… keys read your real feeds; blst_test_… keys only ever see synthetic demo data, safe for CI and development

Note

The full secret is shown exactly once, at creation. Store it in your secret manager immediately — afterwards you can only revoke the key, never re-reveal it.

6. Make your first /v1 request

Every /v1 endpoint authenticates with the key as a bearer token and answers with the same envelope: data, pagination, and meta (request id, schema version, and the data credits the call consumed).

GET/v1/entities

List records across your feeds. Scope: entities:read. Costs 1 data credit per record returned.

Shell — first request
$ curl -s "https://api.ballastos.com/v1/entities?limit=1" \
    -H "Authorization: Bearer blst_test_4kd92m…"
Response
{
  "data": [
    {
      "id": "ent_7f3a2b9c",
      "feed_id": "feed_1d4e8a2f",
      "entity_type": "construction_project",
      "canonical_name": "Riverside Logistics Hub — Phase 2",
      "aliases": ["Riverside DC Phase II"],
      "attributes": { "project_value_usd": 14200000, "stage": "permitting" },
      "external_ids": { "permit_no": "BLD-2026-018443" },
      "geography": { "city": "Columbus", "region": "OH", "country": "US", "postal_code": "43215" },
      "status": "active",
      "verification_status": "multi_source_verified",
      "confidence": 0.94,
      "version": 3,
      "source_evidence": [
        { "source_id": "src_2c9b41ea", "source_name": "City permit portal",
          "url": "https://…", "retrieved_at": "2026-07-19T04:12:33Z", "synthetic": true }
      ],
      "first_observed_at": "2026-07-02T09:15:04Z",
      "last_observed_at": "2026-07-19T04:12:33Z",
      "last_verified_at": "2026-07-18T22:40:11Z",
      "is_demo": true
    }
  ],
  "pagination": { "next_cursor": "eyJhZnRlciI6…" },
  "meta": { "request_id": "req_9f21c4ab", "schema_version": "2026-07-01", "credits_consumed": 1 }
}

Swap the path for /v1/events to read the typed intelligence events instead, or /v1/changes to consume an attribute-level change stream. The full surface — filters, cursor pagination, credit costs, exports — is on the API reference.

7. Configure a webhook

Polling is optional. Register an endpoint and Ballast pushes signed deliveries the moment something happens — a record created or updated, an intelligence event detected or verified, a source failing or recovering. Creating a webhook needs the webhooks:write scope:

Shell — create a webhook
$ curl -s -X POST https://api.ballastos.com/v1/webhooks \
    -H "Authorization: Bearer blst_live_8n3xv1…" \
    -H "content-type: application/json" \
    -d '{"url": "https://example.com/hooks/ballast", "events": ["intelligence_event.created", "entity.updated"]}'
Response — the signing secret is shown once
{
  "data": {
    "id": "wh_4e2f9a1b",
    "url": "https://example.com/hooks/ballast",
    "events": ["intelligence_event.created", "entity.updated"],
    "secret": "whsec_Xh92mAq7…"
  },
  "pagination": { "next_cursor": null },
  "meta": { "request_id": "req_c02d81f7", "schema_version": "2026-07-01", "credits_consumed": 0 }
}

Every delivery is signed with that whsec_ secret via an X-Ballast-Signature header. Verify it before trusting a payload — the verification recipe, the full event-type list, and the retry policy are on the Webhooks page.

Test keys are a full sandbox

Point your integration at a blst_test_ key while your first feed is still in onboarding. The synthetic records and events have the exact production shape — envelope, cursors, credits, verification statuses — so switching to live is a one-line key swap.

What just happened

You described a slice of the market, approved the sources Ballast proposed, and got a continuously updated, evidence-backed dataset — readable in the dashboard, queryable over an authenticated REST API with per-key scopes and allowances, and pushed to you over signed webhooks. No scrapers to maintain, no schemas to design, no source permissions to negotiate yourself.

Where to go next

  • API reference — every /v1 endpoint: auth and scopes, the response envelope, cursor pagination, data credits, filters, exports, and error semantics
  • Webhooks — outbound intelligence webhooks: event types, payload shape, signature verification, and retries