Falando API

Access your Falando learning data programmatically — stats, SRS reviews, vocabulary, and grammar — through a simple REST API.

Introduction

The Falando Open API lets you pull your own learning data — stats, SRS review state, vocabulary, and grammar — into your own scripts, dashboards, and integrations you build. It is read-only in v1.

Requires an active Premium subscription. Create keys from Settings → API.

Base URL

https://falando.app/api/v1

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer fld_your_api_key_here

Keep your key secret

A key grants read access to your account's learning data. Treat it like a password — don't commit it to a public repo or paste it into a shared script. Revoke a key any time from Settings if you suspect it leaked; up to 5 active keys per account.

The key-management endpoints (POST/GET/DELETE /api/v1/api-keys) use your logged-in browser session instead of a key — use them from the Falando web app, not from external scripts.

Rate limits

60 requests/minute and 2,000 requests/day per account (UTC day). Every response carries your current limit status:

Param	Type	Description
RateLimit-Limit	integer	Per-minute limit.
RateLimit-Remaining	integer	Requests left in the current minute.
RateLimit-Reset	epoch seconds	When the per-minute window resets.
X-RateLimit-Day-Limit	integer	Per-day limit.
X-RateLimit-Day-Remaining	integer	Requests left today (UTC).
X-RateLimit-Day-Reset	epoch seconds	Next UTC midnight.

Response format

Every response uses the same envelope:

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Pagination

List endpoints (/reviews, /vocabulary, /grammar) use cursor pagination:

Param	Type	Description
per_page	integer	Rows per page. Default 100, max 500.
page_after_id	string	Pass the previous response’s pages.next_cursor to fetch the next page.

Response shape

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pages": { "per_page": 100, "next_cursor": "abc123" },
    "total_count": 8449
  }
}

next_cursor is null on the last page. Pass an ids filter (comma-separated, max 100–500 depending on the endpoint) to fetch a specific set of rows directly — that mode ignores the cursor and returns every match in one response.

Errors

Status	Code	Meaning
401	UNAUTHORIZED / INVALID_API_KEY	Missing, malformed, revoked, or expired API key.
403	PLAN_REQUIRED	The key belongs to a free account, or the subscription has lapsed.
404	NOT_FOUND	The route does not exist.
422	VALIDATION_ERROR	A request body failed schema validation.
429	RATE_LIMITED	Per-minute or per-day limit exceeded. See Retry-After.
500	INTERNAL_ERROR	Unexpected server error. Safe to retry with backoff.

Fair use & terms

Personal use, dashboards, and your own app integrations are welcome. Please don't redistribute, mirror, or resell Falando's vocabulary or grammar content pulled through this API — it's still covered by our Terms & Conditions. We monitor usage for abuse and may revoke keys that scrape content at scale or otherwise violate these terms.

Endpoints

Account snapshot

GET/api/v1/user

Your profile, subscription, and learning preferences.

curl -H "Authorization: Bearer fld_..." https://falando.app/api/v1/user

{
  "success": true,
  "data": {
    "user": {
      "id": "…", "username": "capivara42", "level": "B1", "experience": 12450,
      "streak": 42, "total_study_time_seconds": 186400, "last_study_date": "2026-07-01",
      "daily_quests_streak": 15, "member_since": "2025-11-02T10:00:00Z"
    },
    "subscription": {
      "plan": "paid", "lifetime": false, "status": "active", "interval": "annual",
      "current_period_end": "2027-07-01T00:00:00Z", "auto_renewing": true
    },
    "preferences": {
      "daily_goal": 20, "weekly_goal": 100, "new_vocabulary_per_day": 10,
      "new_listening_per_day": 3, "timezone": "America/Sao_Paulo", "ui_language": "en"
    }
  }
}

Review queue status

GET/api/v1/summary

How many reviews are due right now, and when the next batch becomes available.

{
  "success": true,
  "data": {
    "reviews": { "due_now": 12, "next_review_at": null },
    "upcoming": [
      { "at": "2026-07-02T18:00:00.000Z", "count": 4 },
      { "at": "2026-07-02T19:00:00.000Z", "count": 9 }
    ]
  }
}

next_review_at is null whenever due_now is greater than 0 — there's nothing to wait for. upcoming buckets the next 24 hours by UTC hour.

Learning stats snapshot

GET/api/v1/stats

Profile totals, today's activity, mastery progress, and badge count.

curl -H "Authorization: Bearer fld_..." https://falando.app/api/v1/stats

{
  "success": true,
  "data": {
    "profile": { "level": "B1", "experience": 12450, "streak": 42,
      "total_study_time_seconds": 186400, "last_study_date": "2026-07-01", "daily_quests_streak": 15 },
    "today": { "study_time_seconds": 1800, "study_time_minutes": 30, "reviews_completed": 25,
      "reviews_correct": 22, "reviews_accuracy": 88, "interactions": 45, "sessions_count": 2 },
    "progress": { "total_items_mastered": 340, "grammar_mastered": 45, "vocabulary_mastered": 260,
      "listening_mastered": 35, "total_items_in_progress": 520 },
    "srs": { "items_due_now": 12 },
    "achievements": { "badges_unlocked": 18 }
  }
}

Daily time-series

GET/api/v1/datapoints

Daily aggregated values for one metric — built for time-series dashboards and daily-goal tracking tools.

Param	Type	Description
metric	string	study_minutes \| reviews_completed \| reviews_correct \| items_mastered \| interactions \| sessions \| streak. Default study_minutes.
days	integer	Lookback window. Default 30, max 365.
tz	IANA timezone	e.g. America/Sao_Paulo. Buckets days in this timezone instead of UTC — use this for daily-goal integrations, or an evening session drifts onto the next UTC day.

curl

curl -H "Authorization: Bearer fld_..." \
  "https://falando.app/api/v1/datapoints?metric=study_minutes&days=7&tz=America/Sao_Paulo"

{
  "success": true,
  "data": {
    "metric": "study_minutes", "days": 7,
    "datapoints": [
      { "date": "2026-06-26", "value": 25 },
      { "date": "2026-06-27", "value": 40 }
    ]
  }
}

Your SRS review items

GET/api/v1/reviews

Per-item spaced-repetition state — interval, ease factor, next review time, and more.

Param	Type	Description
type	string	grammar \| vocabulary \| listening.
ids	comma-separated	Fetch specific items by id (max 100). Ignores cursor.
updated_after	ISO 8601	Only items changed since this timestamp — for incremental sync.
page_after_id	string	Cursor from the previous page.
per_page	integer	Default 100, max 500.

Vocabulary catalog

GET/api/v1/vocabulary

Read-only vocabulary catalog metadata (not the full lesson content — see fair use above).

Param	Type	Description
levels	comma-separated CEFR	A1,A2,B1,B2,C1,C2,EX. Default: all levels.
pos	string	Filter by part of speech (noun, verb, adjective, …).
ids	comma-separated	Fetch specific words by id (max 500). Ignores cursor.
updated_after	ISO 8601	Only rows changed since this timestamp.
page_after_id	string	Cursor from the previous page.
per_page

Grammar point catalog

GET/api/v1/grammar

Grammar point metadata (title, synopsis, structure). Full lesson explanations stay in-app.

Param	Type	Description
levels	comma-separated CEFR	A1,A2,B1,B2,C1,C2,EX. Default: all levels.
ids	comma-separated	Fetch specific points by id (max 500). Ignores cursor.
updated_after	ISO 8601	Only rows changed since this timestamp.
page_after_id	string	Cursor from the previous page.
per_page	integer	Default 100, max 500.

CORS

Every v1 response allows cross-origin requests (Access-Control-Allow-Origin: *), so you can call the API directly from a browser-based dashboard. Authentication is token-only (no cookies are read or set), so this is safe.

Versioning

The API is versioned by URL path (/api/v1/...). New fields and new endpoints are added without notice and are safe to ignore if your client doesn't know about them yet. A breaking change (a field renamed or removed, a status code meaning changed) would ship as /api/v2, with v1 kept running.

Changelog

2026-07-02 — Public launch for all Premium accounts. Added /user, /summary, /reviews, /vocabulary, and /grammar. /stats and /datapoints carry over unchanged from the private beta.

curl -H "Authorization: Bearer fld_..." \
  "https://falando.app/api/v1/reviews?type=vocabulary&per_page=50"

{
  "success": true,
  "data": {
    "items": [{
      "id": "…", "type": "vocabulary", "vocabulary_id": "casa-de-praia", "grammar_point_id": null,
      "grammar_exercise_id": null, "listening_id": null, "interval": 6, "ease_factor": 2.5,
      "repetitions": 4, "lapses": 0, "next_review": "2026-07-05T09:00:00Z",
      "last_review": "2026-06-29T09:00:00Z", "is_suspended": false,
      "created_at": "2026-01-10T12:00:00Z", "updated_at": "2026-06-29T09:00:00Z"
    }],
    "pages": { "per_page": 50, "next_cursor": null },
    "total_count": 1
  }
}

{
  "success": true,
  "data": {
    "items": [{
      "id": "falar", "level": "A1", "portuguese": "falar", "english": "to speak / to talk",
      "pronunciation": "fah-LAHR", "ipa": "fa.ˈla(ʁ)", "part_of_speech": "verb", "gender": null, "frequency": "very_high",
      "is_top_1000": true, "tags": ["core"], "regions": [],
      "created_at": "2025-09-01T00:00:00Z", "updated_at": "2025-09-01T00:00:00Z"
    }],
    "pages": { "per_page": 20, "next_cursor": "gostar" },
    "total_count": 8449
  }
}

curl -H "Authorization: Bearer fld_..." \
  "https://falando.app/api/v1/grammar?levels=A1,A2"

{
  "success": true,
  "data": {
    "items": [{
      "id": "present-tense-ar-verbs", "title": "Present Tense: -AR Verbs",
      "short_title": "-AR present tense", "synopsis": "Conjugating regular -ar verbs in the present.",
      "structure": "subject + verb stem + ending (-o, -a, -amos, -am)", "cefr": "A1", "lesson": "1.2",
      "created_at": "2025-08-01T00:00:00Z", "updated_at": "2026-02-14T00:00:00Z"
    }],
    "pages": { "per_page": 100, "next_cursor": null },
    "total_count": 178
  }
}