The Bayanii API

1. 1

   Create a token

   Sign in and open Account → API. Give the token a name you will recognize later (for example, the program that will use it), choose how long it lasts, and copy it. It starts with bay_ and is shown only once.

   Keep it in an environment variable, not in your code:

   Terminal content_copyCopy

   export BAYANII_TOKEN="bay_..."

2. 2

   Find your model

   List your models. Note the id of the one you want and the input columns it expects.

   curl content_copyCopy

   curl -H "Authorization: Bearer $BAYANII_TOKEN" \
     https://bayanii.com/api/v1/models

   Response content_copyCopy

   {
     "data": [
       {
         "id": 88,
         "name": "Churn",
         "task_type": "classification",
         "targets": ["churned"],
         "input_columns": ["tenure", "plan", "monthly_charges"],
         "input": "rows",
         ...
       }
     ],
     "meta": {"total": 1, "limit": 50, "offset": 0, "has_more": false}
   }

3. 3

   Get a prediction

   Send one object per row, with every input column as a key.

   curl content_copyCopy

   curl -X POST https://bayanii.com/api/v1/models/88/predictions \
     -H "Authorization: Bearer $BAYANII_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"rows": [{"tenure": 12, "plan": "monthly", "monthly_charges": 70.5}]}'

   Response content_copyCopy

   {
     "data": {
       "model_id": 88,
       "task_type": "classification",
       "row_count": 1,
       "predictions": [
         {"prediction": "yes", "confidence": 0.82, "runner_up": "no", "runner_up_confidence": 0.18}
       ],
       "warnings": [],
       "prediction_run_id": 1234,
       "stored": false
     }
   }

Authentication

Every request carries your token in the Authorization header:

Authorization: Bearer bay_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• schedule

  Lifetime

  30, 90 or 365 days, or no expiry. Up to 10 active tokens per account.

• block

  Revoking

  Revoke a token on Account → API. The next request with it is refused.

• person_off

  Account changes

  Deleting your account deletes its tokens. A disabled account stops working within 15 minutes.

• lock

  Token management

  A token cannot create, list or revoke tokens — that needs you, signed in.

Requests and responses

Every response has the same shape: the result under "data", or a problem under "error" — never both. Check the HTTP status first, then read the matching key.

{
  "data": { ... },
  "meta": { ... }
}

{
  "error": {
    "code": "missing_columns",
    "message": "Row 3 is missing: plan.",
    "details": {"row": 3, "columns": ["plan"]}
  }
}

• "meta" appears on lists and carries the paging facts.
• Branch on "code" in your program — it never changes. "message" is a sentence for people and follows the Accept-Language header (en or ar; English by default).
• Timestamps such as created_at and expires_at are ISO 8601 in UTC, ending in Z — for example 2026-11-01T09:30:00Z. A forecast's period is the date as your training data had it, with no time zone added.
• Send request bodies as JSON with Content-Type: application/json.
• Responses are never cached (Cache-Control: no-store): they can hold your data.

Making predictions

What to send

• Every input column must be present in every row. A value may be a number, text, true / false, or null for an empty cell — the model fills an empty cell the way it did in training.
• Extra keys are ignored, and a warning names them, so a typo in a column name does not go unnoticed.
• Use the model's input_schema to build rows: the exact column names, and for categories the values it knows.

What you get back

Warnings

Each warning has a code, a severity, a title and a message. "caution" means the prediction may be less reliable; "notice" is for your information.

{
  "code": "out_of_range",
  "severity": "caution",
  "title": "Values outside the training range",
  "message": "Values in \"tenure\" are outside the range seen during training (0–72; count: 1). They were not changed.",
  "details": {"column": "tenure", "min": 0, "max": 72, "count": 1}
}

Forecasting models

A forecaster with no input columns takes "steps" instead of rows, and each item comes back with its period and interval:

{"steps": 3}

{
  "period": "2026-01-01T00:00:00",
  "prediction": 120.5,
  "lower": 98.1,
  "upper": 141.7
}

Errors

A 4xx status means something in the request needs fixing — retrying the same request will fail the same way, except 429. A 5xx status is our side: retry later, and quote details.request_id if you contact us.

Limits

Limits count per account — all of your tokens together. Batch rows into one request instead of sending one request per row: it is faster for you and counts once.

prediction requests per minute

30

other requests per minute

120

rows per prediction request

10,000

active tokens per account

10

Full examples

A prediction with error handling, reading the token from the environment.

import os
import requests

API = "https://bayanii.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['BAYANII_TOKEN']}"

rows = [
    {"tenure": 12, "plan": "monthly", "monthly_charges": 70.5},
    {"tenure": 48, "plan": "yearly", "monthly_charges": 55.0},
]
resp = session.post(f"{API}/models/88/predictions", json={"rows": rows}, timeout=120)
body = resp.json()

if resp.ok:
    for row, p in zip(rows, body["data"]["predictions"]):
        print(row, "->", p["prediction"], p.get("confidence"))
    for w in body["data"]["warnings"]:
        if w["severity"] == "caution":
            print("caution:", w["message"])
elif resp.status_code == 429:
    print("Slow down; retry after", resp.headers.get("Retry-After"), "seconds")
else:
    print(resp.status_code, body["error"]["code"], body["error"]["message"])

const API = "https://bayanii.com/api/v1";

const resp = await fetch(`${API}/models/88/predictions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BAYANII_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    rows: [{ tenure: 12, plan: "monthly", monthly_charges: 70.5 }],
  }),
});
const body = await resp.json();

if (!resp.ok) {
  throw new Error(`${resp.status} ${body.error.code}: ${body.error.message}`);
}
for (const p of body.data.predictions) {
  console.log(p.prediction, p.confidence);
}

curl -sS -X POST https://bayanii.com/api/v1/models/88/predictions \
  -H "Authorization: Bearer $BAYANII_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: en" \
  -d '{
        "rows": [
          {"tenure": 12, "plan": "monthly", "monthly_charges": 70.5},
          {"tenure": 48, "plan": "yearly",  "monthly_charges": 55.0}
        ],
        "store": true
      }'

Versioning

The version is in the URL. Within v1 we may add endpoints, response fields, warning codes and error codes, so ignore fields you do not know. We will not rename or remove a field or change what a code means — a change like that becomes /api/v2, and v1 keeps working alongside it.