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.
https://fross.ai/functions/api?route=/v1/sets| Route | Method | What it does |
|---|---|---|
| /v1/sets | POST | Create a study set from text (or a YouTube link on Pro) |
| /v1/generate | POST | Build flashcards, a quiz or an explanation from that set |
| /v1/usage | GET | This 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.
Authorization: Bearer fross_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeep 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.
| Limit | Free | Pro |
|---|---|---|
| Generations / month | 100 | 2,000 |
| Requests / minute | 10 | 60 |
| Characters / set | 20,000 | 20,000 |
| Items / generation | 25 | 100 |
| YouTube input | No | Yes |
| Keys | 3 | 3 |
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).
/v1/setsCreates 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.
| Field | Type | Required | Notes |
|---|---|---|---|
| text | string | one of text / youtube_url | At least 40 characters of material |
| youtube_url | string | one of text / youtube_url | The video's captions are read |
| title | string | no | Overrides the title taken from the material |
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"
}'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');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"]{
"set_id": "6a1f0c9d8e7b6a5f4c3d2e1b",
"title": "Photosynthesis",
"line_count": 2
}/v1/generateBuilds 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.
| Field | Type | Required | Notes |
|---|---|---|---|
| set_id | string | yes | A set this key created |
| type | string | yes | flashcards | quiz | explain |
| count | number | no | flashcards 20, quiz 10, explain 8 by default; capped by the plan |
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 }'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);
}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"]]{
"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.
/v1/usageThis key’s calls in the current calendar month (UTC), plus — for a developer key — the account’s plan and its shared quota.
curl 'https://fross.ai/functions/api?route=/v1/usage' \
-H 'Authorization: Bearer fross_live_...'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);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"]){
"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.
| Status | Code | Meaning |
|---|---|---|
| 400 | material_required | Neither text nor youtube_url was sent. |
| 400 | material_too_short | Under 40 characters of material. |
| 400 | invalid_type | type is not flashcards, quiz or explain. |
| 400 | items_over_limit | count is above the plan’s items per generation. |
| 401 | unauthorized / invalid_key | No key sent, or the key is not valid. |
| 402 | plan_required | YouTube input needs Pro. |
| 403 | key_inactive | The key was revoked. |
| 403 | account_suspended | The developer account is suspended. |
| 403 | set_not_yours | That set belongs to another key. |
| 404 | not_found / set_not_found | Unknown route, or no such set. |
| 413 | input_too_long | Material is over the plan’s characters per set. |
| 429 | rate_limited | Per-minute request limit (all keys together). |
| 429 | generation_limit_reached | Monthly generations used up. |
| 502 | ai_unavailable / nothing_generated | The AI could not build this now. Retry later. |
| 503 | api_disabled | An admin has paused the API. |
| 503 | daily_cost_cap_reached | The 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.