DEVELOPER PREVIEW · API V1

Exact-product price intelligence, built for systems.

Give BALGRAD.AI a strong product identifier. Get current verified offers, genuine observed history, freshness and evidence — without silent fuzzy matching.

Open B2B portal Plans & pilot pricing

Authentication

Send your organization key as Authorization: Bearer bg_live_…. API keys are displayed once in the B2B portal; BALGRAD.AI stores only the SHA-256 hash.

Endpoint family

POST/api/v1/resolve

Resolve an exact BALGRAD ID, GTIN, brand + MPN, or exact brand + model.

GET/api/v1/products/{id}

Canonical identity, coverage and limitations.

GET/api/v1/products/{id}/offers

Current verified retailer offers with freshness and evidence.

GET/api/v1/products/{id}/history

Genuine observed price history. No fabricated backfill.

GET/api/v1/products/{id}/coverage

Offer, retailer and market coverage for the exact product.

POST/api/v1/batch/offers

Resolve and retrieve current intelligence for up to 50 identifiers per launch request.

POST/api/v1/exports/csv

Download a bounded current-offer CSV for up to 50 identifiers.

GET/api/v1/usage

Current monthly API, tracked-identifier and project usage.

GET/POST/DELETE/api/v1/alerts

List, create/update, or disable material-change alert rules. First evaluation seeds a baseline; email is sent only after a later qualifying change.

Resolve request

POST /api/v1/resolve
Authorization: Bearer bg_live_…
Content-Type: application/json

{
  "type": "GTIN",
  "identifier": "0000346049534"
}

Core truth rules

Exact identifiers first; ambiguity fails closed.
Original retailer currency is preserved.
Unknown shipping is not treated as free.
History contains genuine observations only.
Coverage is reported as supported verified coverage, never guaranteed global completeness.

Data states

Responses use explicit states such as VERIFIED_FRESH, VERIFIED_STALE, NO_CURRENT_OFFER, NO_MATCH and IDENTITY_AMBIGUOUS. Rate-limit metadata is returned in response headers.

Material-change alerts

Alert rules support absolute price change, percentage price change, stock change, new retailer and new market detection. The first evaluation only records a baseline. Later qualifying changes are deduplicated and sent to active organization owners/admins by transactional email, with at most three delivery attempts.