API reference

Grounded study content, by API. One endpoint, three routes.

Base URL and routes

Every route is served by one function. The route travels as a route query parameter; a POST may send the same value as a route field in the JSON body instead.

Base URL
https://fross.ai/functions/api?route=/v1/sets
RouteMethodWhat it does
/v1/setsPOSTCreate a study set from text (or a YouTube link on Pro)
/v1/generatePOSTBuild flashcards, a quiz or an explanation from that set
/v1/usageGETThis month's calls, generations and the plan's limits

Authentication

Send your key in an Authorization header on every request. A key is shown once when it is created; only its SHA-256 hash is stored, so a lost key cannot be recovered — roll a new one from the dashboard.

Header
Authorization: Bearer fross_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep the key on a server. Anything in a browser or a mobile app is public. You can hold 3 keys at a time and roll them without downtime.

A missing or unknown key returns 401; a revoked key returns 403 key_inactive.

Limits per plan

Limits are enforced server-side, per account: every key you own shares one quota, so a second key does not buy a second allowance.

LimitFreePro
Generations / month1002,000
Requests / minute1060
Characters / set20,00020,000
Items / generation25100
YouTube inputNoYes
Keys33

Over a limit returns 429 with { error, limit, reset_at } — reset_at is the ISO time the quota frees up.

The platform also keeps a master switch and a daily AI-spend cap. If either is hit, every call returns 503 with a reset_at (or null when an admin has paused the API).

POST/v1/sets

Creates a set from pasted text, or from a YouTube link (Pro). Text is split into numbered lines — that numbering is what every later citation points at.

FieldTypeRequiredNotes
textstringone of text / youtube_urlAt least 40 characters of material
youtube_urlstringone of text / youtube_urlThe video's captions are read
titlestringnoOverrides the title taken from the material
curl
curl -X POST 'https://fross.ai/functions/api?route=/v1/sets' \
  -H 'Authorization: Bearer fross_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Photosynthesis converts light energy into chemical energy.\nIt happens in the chloroplasts of plant cells.",
    "title": "Photosynthesis"
  }'
JavaScript
const BASE = 'https://fross.ai/functions/api';

const res = await fetch(`${BASE}?route=/v1/sets`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FROSS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: material, title: 'Photosynthesis' }),
});

const { set_id, line_count } = await res.json();
if (!res.ok) throw new Error('set creation failed');
Python
import os, requests

BASE = "https://fross.ai/functions/api"

r = requests.post(
    f"{BASE}?route=/v1/sets",
    headers={"Authorization": f"Bearer {os.environ['FROSS_API_KEY']}"},
    json={"text": material, "title": "Photosynthesis"},
    timeout=90,
)
r.raise_for_status()
set_id = r.json()["set_id"]
Response 200
{
  "set_id": "6a1f0c9d8e7b6a5f4c3d2e1b",
  "title": "Photosynthesis",
  "line_count": 2
}
POST/v1/generate

Builds one kind of material from a set you created: flashcards, quiz or explain. Every item is checked by a second model against the exact line it cites.

FieldTypeRequiredNotes
set_idstringyesA set this key created
typestringyesflashcards | quiz | explain
countnumbernoflashcards 20, quiz 10, explain 8 by default; capped by the plan
curl
curl -X POST 'https://fross.ai/functions/api?route=/v1/generate' \
  -H 'Authorization: Bearer fross_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "set_id": "6a1f0c9d8e7b6a5f4c3d2e1b", "type": "flashcards", "count": 10 }'
JavaScript
const res = await fetch(`${BASE}?route=/v1/generate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FROSS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ set_id, type: 'quiz', count: 10 }),
});

const { items, verified_count } = await res.json();
for (const item of items) {
  console.log(item.verified, item.confidence, item.question);
}
Python
r = requests.post(
    f"{BASE}?route=/v1/generate",
    headers={"Authorization": f"Bearer {os.environ['FROSS_API_KEY']}"},
    json={"set_id": set_id, "type": "quiz", "count": 10},
    timeout=180,
)
data = r.json()
verified = [i for i in data["items"] if i["verified"]]
Response 200
{
  "set_id": "6a1f0c9d8e7b6a5f4c3d2e1b",
  "type": "flashcards",
  "item_count": 2,
  "verified_count": 2,
  "items": [
    {
      "kind": "card",
      "topic": "Photosynthesis",
      "question": "What does photosynthesis convert light energy into?",
      "answer": "Chemical energy.",
      "source_line": 1,
      "source_quote": "Photosynthesis converts light energy into chemical energy.",
      "verified": true,
      "confidence": "high"
    }
  ]
}

Every item carries source_line, source_quote, verified and confidence. An item the checker could not confirm is returned with verified: false rather than dropped.

GET/v1/usage

This key’s calls in the current calendar month (UTC), plus — for a developer key — the account’s plan and its shared quota.

curl
curl 'https://fross.ai/functions/api?route=/v1/usage' \
  -H 'Authorization: Bearer fross_live_...'
JavaScript
const res = await fetch(`${BASE}?route=/v1/usage`, {
  headers: { Authorization: `Bearer ${process.env.FROSS_API_KEY}` },
});
const usage = await res.json();
console.log(usage.account.generations_this_month, usage.account.limits);
Python
usage = requests.get(
    f"{BASE}?route=/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['FROSS_API_KEY']}"},
    timeout=30,
).json()
print(usage["calls_this_month"], usage["account"]["generations_this_month"])
Response 200
{
  "key": "Production server",
  "month_start": "2026-11-01T00:00:00.000Z",
  "calls_this_month": 12,
  "monthly_limit": 0,
  "remaining": null,
  "per_minute_limit": 10,
  "plan": "free",
  "account": {
    "email": "dev@example.com",
    "status": "active",
    "calls_this_month": 12,
    "generations_this_month": 4,
    "cost_usd_this_month": 0.05,
    "limits": {
      "generations_per_month": 100,
      "requests_per_minute": 10,
      "max_input_chars": 20000,
      "max_items_per_generation": 25,
      "youtube": false
    },
    "generations_reset_at": "2026-12-01T00:00:00.000Z"
  }
}

Error codes

Every error is JSON with an error code and a message you can show a person.

StatusCodeMeaning
400material_requiredNeither text nor youtube_url was sent.
400material_too_shortUnder 40 characters of material.
400invalid_typetype is not flashcards, quiz or explain.
400items_over_limitcount is above the plan’s items per generation.
401unauthorized / invalid_keyNo key sent, or the key is not valid.
402plan_requiredYouTube input needs Pro.
403key_inactiveThe key was revoked.
403account_suspendedThe developer account is suspended.
403set_not_yoursThat set belongs to another key.
404not_found / set_not_foundUnknown route, or no such set.
413input_too_longMaterial is over the plan’s characters per set.
429rate_limitedPer-minute request limit (all keys together).
429generation_limit_reachedMonthly generations used up.
502ai_unavailable / nothing_generatedThe AI could not build this now. Retry later.
503api_disabledAn admin has paused the API.
503daily_cost_cap_reachedThe platform’s daily AI cap was reached; opens at 00:00 UTC.

Good to know

  • Sets created through the API belong to your key. They never appear in the study app.
  • A generation replaces the previous output for the same set and type; it does not stack.
  • Flashcards are also written into the spaced-repetition deck, so re-running keeps its state.
  • Rolling a key mints a new one and revokes the old one in the same step — deploy the new value, then confirm the old one returns 403.