API reference

Base URL https://api.finic.ai. Send an API key as Authorization: Bearer gsk_… (Authentication) and JSON bodies (Content-Type: application/json); the score endpoints also take multipart/form-data. Every response has an X-Request-Id header.

ErrorsCopy Anchor Link

A failed request returns an error status and this JSON:

{ "error": { "type": "invalid_request", "message": "\" Yes\" appears twice in the criteria.", "param": "questions.q.criteria" } }

type is one of the types below: branch on it. message is for people and can change, so don't parse it. param is the dotted path to the field at fault, or null. Validation stops at the first problem.

• Out of credit, decide and score calls get 402 before their data is checked; creating and calibrating never do.
• A 502 or 504 from the network edge, during a deployment or an outage, has no JSON body or X-Request-Id: treat it like 503.
• 202 from create_score and calibrate means accepted, with the work running in a job. A failed job reports its error at get_job_status, in the same shape without param.
• A 429 for the request rate says Too many requests for this organization: the limit is 5 requests per second across its API keys and the playground. and clears in moments. A daily limit's (This organization has created 100 scores in the last 24 hours, the limit.) doesn't, so retrying soon fails the same way.

Some invalid_request errors:

RetryingCopy Anchor Link

• decide is safe to retry; a retry of a request that succeeded makes the decision again.
• score with the same score_id scores a record once: if the first call succeeded, the retry gets 409 duplicate_score_id, without the score.
• create_score retried after a timeout can create a second score, counted toward the daily limit.
• calibrate retried resends the same outcomes, which replace themselves; while the first call's job runs, it gets 409 calibration_in_progress.
• get_job_status is always safe.

Retry 429 (except a daily limit), 500, 502, 503, 504, network errors and timeouts with exponential backoff and jitter; don't retry other 4xx without changing the request. Set client timeouts above 30 seconds, the longest a decision can run.

import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}


def post(path: str, body: dict, api_key: str, attempts: int = 5) -> dict:
    for attempt in range(attempts):
        last = attempt == attempts - 1
        try:
            response = requests.post(
                f"https://api.finic.ai{path}",  # "/v1/decide" or "/v1/score"
                headers={"Authorization": f"Bearer {api_key}"},
                json=body,
                timeout=60,
            )
        except (requests.ConnectionError, requests.Timeout):
            if last:
                raise
        else:
            if response.status_code not in RETRYABLE or last:
                break
        time.sleep(min(8.0, 0.5 * 2**attempt) * random.uniform(0.5, 1.0))

    if not response.ok:
        request_id = response.headers.get("X-Request-Id")
        try:
            error = response.json()["error"]
        except ValueError:  # an edge 502/504 has no JSON body
            raise RuntimeError(f"{response.status_code} (request {request_id})")
        raise RuntimeError(f"{response.status_code} {error['type']}: {error['message']} (request {request_id})")
    return response.json()

For help, email support@finic.ai with the X-Request-Id. Support sees a request's time, key, endpoint, status and error type, not its content: if the problem depends on the content, describe it or send a redacted example.

LimitsCopy Anchor Link

Rate limitsCopy Anchor Link

The request rate covers all of an organization's API keys, agent sign-ins and playground runs, for decide, score, create and calibrate calls; checking a job doesn't count. Requests over it get 429 rate_limited, with no Retry-After header: retry with exponential backoff (Retrying). For higher volume, contact support@finic.ai.

ScoresCopy Anchor Link

Over a daily limit, requests get 429 rate_limited until the 24 hours pass.

DecideCopy Anchor Link

Over a limit, a request gets 400 invalid_request, or 413 request_too_large for tokens and body size.

How tokens are countedCopy Anchor Link

usage.input_tokens counts everything the model reads:

• data and context: a string as sent, an object or array as compact JSON.
• A noul, choice or score question: its instructions and criteria, plus 2 marker tokens per question and 1 per option or level.
• A multi_choice: each option is asked separately, so each costs the instructions, the list of all options (with 16 or fewer), the option and 2 markers. One with 8 options reads its instructions 8 times.

Question names and option keys aren't read, so they don't count. To size requests, send a representative one and read usage.input_tokens; see Data & context for fitting a long history.