Falando API

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.

https://falando.app/api/v1

Every request needs an API key in the Authorization header:

Authorization: Bearer fld_your_api_key_here

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.

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

Every response uses the same envelope:

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

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

Responses are sent with Cache-Control: private, no-store: they are your personal data and are never served from a shared cache. A failed query always returns an error, never partial data or invented zeros.

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

{
  "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.

Your profile, subscription, and learning preferences. Subscription fields are null when access does not come from a recurring subscription (for example lifetime access), and preferences is null until settings are first saved.

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"
    }
  }
}

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 }
    ]
  }
}

Due times follow the same schedule as the review queue in the app, so due_now matches the count you see there. 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. Suspended items are excluded.

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

curl -H "Authorization: Bearer fld_..." \
  "https://falando.app/api/v1/stats?tz=America/Sao_Paulo"

{
  "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 }
  }
}

today.* counts sessions that started today in tz, with the same rules as . is until the first review of the day. matches the review queue in the app.

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

Per-item spaced-repetition state — when each item is next due, review and lapse counts, and more.

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

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

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.

The rate-limit headers and Retry-After are exposed to browser code, including on error responses.

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.

• 2026-09-26 — Due times now follow the review queue in the app: /summary, /stats (srs.items_due_now), and /reviews (next_review) could previously report an outdated schedule for some items.
• 2026-09-24 — /datapoints: documented format=beeminder. Out-of-range days and unknown format values now return 400 instead of being clamped or ignored. The window is whole calendar days in tz, including today. Sessions count on the day they started. Study minutes are rounded once per day instead of per session. Long histories are no longer cut off at 1,000 rows. A failed query returns an error instead of partial data. You can still list and revoke keys after a subscription lapses.
• 2026-07-26 — /vocabulary items include ipa (Brazilian Portuguese IPA; null where not yet available).
• 2026-07-06 — /stats accepts for the “today” window.