Docs

API Documentation

Complete reference for all Brainiall APIs.

Authentication

All endpoints accept any of these headers (use one):

Authorization: Bearer YOUR_KEYOcp-Apim-Subscription-Key: YOUR_KEYapi-key: YOUR_KEY

Base URLhttps://api.brainiall.com

Authentication details

Get a free API key at app.brainiall.com (100 image credits / 10 minutes of audio / 10k memory events per month). The key is a single Bearer token shared across all 18 endpoints — no per-product credentials.

Rate limits

Plan	Calls / minute	Concurrent	Monthly quota
Free	10	2	100 images / 10 min audio / 10k events
Pay-as-you-go	120	10	Unlimited (usage-billed)
Enterprise	Custom	Custom	Custom (committed-use)

Hitting the per-minute limit returns HTTP 429 with the headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.

Error codes

HTTP	Cause	Fix
`401`	Missing / malformed Bearer token	Verify `Authorization: Bearer brnl-...` header is present and unrevoked.
`403`	Token lacks scope for this endpoint or quota exceeded	Check /usage for quota; for scope, contact support.
`422`	Validation failed (e.g. tier="ultra" not in enum)	Inspect `error.details` JSON; cross-check with OpenAPI.
`429`	Rate limit exceeded	Honor `Retry-After` header; back off + retry. Upgrade plan if frequent.
`500-599`	Transient backend error	Idempotent retry with exponential backoff. Check /status for incidents.

All error responses follow the OpenAPI Error envelope: {"error":{"code":N,"message":"...","details":{}}}.

Token rotation

Manage tokens at /api-tokens — create short-lived OAuth-style tokens (24h to 90d expiry), name them per project, and revoke any one without affecting the others. Long-lived keys are rotated automatically every 90 days; you receive an email at the 14-day and 7-day marks.

For machine-to-machine workflows that cannot rotate, use a service-account token from /team (Enterprise plan).

NLP Suite Endpoints

Detect toxic, offensive, or harmful content in text.

curl -X POST https://api.brainiall.com/v1/nlp/toxicity \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"This product is absolutely amazing"}'

SDK & tooling

Use any client format — all stay in sync with the live OpenAPI spec.

Try interactive explorer →OpenAPI 3.1 JSON OpenAPI 3.1 YAML Postman v2.1 Collection Postman Environment TypeScript SDK (.tar.gz)Python SDK (.tar.gz)Datasheet PDF (sample)

Generate a typed client: npx @openapitools/openapi-generator-cli generate -i https://app.brainiall.com/openapi.json -g typescript-fetch -o ./brainiall-sdk

Webhooks

Brainiall sends two kinds of webhooks: Marketplace SaaS Fulfillment v2 events (subscription lifecycle from Microsoft Azure Marketplace) and Usage events (per-call metering pushed to your endpoint, optional, Pay-as-you-go and Enterprise plans).

Marketplace SaaS Fulfillment v2

Microsoft Azure Marketplace dispatches subscription lifecycle events to our webhook handler at https://app.brainiall.com/api/marketplace/webhook. You don't implement this — it's documented here so enterprise security teams can audit the integration during procurement.

Action types: Subscribe, Unsubscribe, SuspendSubscription, ReinstateSubscription, ChangePlan, ChangeQuantity, Renew, Transfer.

Payload shape (key fields):

{
  "id":              "uuid",
  "activityId":      "uuid",
  "subscriptionId":  "uuid",
  "publisherId":     "brainiall-publisher-id",
  "offerId":         "specialist-ai-apis",
  "planId":          "s1-background-removal-fast",
  "quantity":        1,
  "action":          "Subscribe",
  "timeStamp":       "2026-04-29T08:30:00.0000000Z",
  "status":          "InProgress",
  "operationRequestSource": "Azure",
  "subscription": { ...full subscription object ... }
}

Signature validation

Every webhook delivers a signed Bearer token in the Authorization header. We validate:

Algorithm = RS256
Issuer = https://sts.windows.net/{tenantId}/
Audience = our AAD application ID
JWKS fetched and cached from https://login.microsoftonline.com/common/discovery/keys
exp claim within 10-minute clock skew

Replay-attack defense

Each activityId is processed at most once. Repeats of the same activityId with different action are rejected with 409 Conflict. The timeStamp field must be within 5 minutes of server clock; older requests are rejected with 401.

Usage events (opt-in)

On Pay-as-you-go and Enterprise plans, you can opt in to receive a usage event for each successful API call, dispatched to your URL. Configure at /webhooks.

{
  "event":      "api.call",
  "id":         "evt_2K9...",
  "created":    "2026-04-29T08:30:00.123Z",
  "endpoint":   "/v1/image/remove-background/base64",
  "sku":        "s1-background-removal",
  "tier":       "hd",
  "tokens_in":  null,
  "tokens_out": null,
  "units":      1,
  "unit_kind":  "image",
  "duration_ms": 3142,
  "status":     200,
  "request_id": "req_8c3..."
}

Signed with HMAC-SHA256 over the raw body using a per-tenant secret you configure when you opt in. Send the signature in X-Brainiall-Signature; verify before processing.