Developer API

Your learning data, in a stable read-only contract.

Use a personal API key to read your cards, reviews, progress, vocabulary strength, writing history, and available course content.

Version: 1.0.0-beta
Base URL: https://api.vocapi.app/v1
Format: JSON over HTTPS

Authentication

Make your first request

Create a scoped key in Vocapi under Settings → API keys, then send it as a Bearer token. Each key can be rotated or revoked from the same screen.

curl "https://api.vocapi.app/v1/user" \
  -H "Authorization: Bearer $VOCAPI_API_KEY"

Contract 1.0.0-beta

16 read endpoints

Parameters and response statuses below are generated from the committed, versioned OpenAPI schema.

GET/v1/achievementsGet Achievements

Return the achievement catalog + the caller's progress for a language. Note: gated by ``progress:read`` -- there is no ``achievements:read`` scope in the ``api_keys`` scope catalog (``vocapi.api_keys.API_KEY_SCOPES``).

Parameters

languagequery · required

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/cardsGet Cards

List the caller's SRS cards, per-language or cross-language.

Parameters

languagequery · optional
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/content/lessonsGet Content Lessons

List a language's lessons in global curriculum order.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/content/lessons/{lesson_id}Get Content Lesson

Return one lesson with its composed, ordered blocks.

Parameters

lesson_idpath · required

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/content/readersGet Content Readers

List a language's curated graded readers.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/content/readers/{item_id}Get Content Reader

Return one curated graded reader with its ordered sections.

Parameters

item_idpath · required

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/content/sentencesGet Content Sentences

List a language's active sentences, optionally filtered to one GP.

Parameters

languagequery · required
grammar_point_idquery · optional
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/free-writesGet Free Writes Route

Return a keyset page of the caller's graded free-production attempts.

Parameters

languagequery · optional
updated_afterquery · optional
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/free-writes/error-patternsGet Error Patterns

Return the caller's recurring error-pattern rollup for a language. Wraps :func:`get_recent_error_patterns` with its default recent-window size -- no extra windowing params on this surface.

Parameters

languagequery · required

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/progress/chaptersGet Progress Chapters

List a language's chapters with a per-chapter lesson-completion rollup.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/progress/grammar-pointsGet Progress Grammar Points

List a language's grammar-mastery dashboard, paginated.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/progress/lessonsGet Progress Lessons

List every lesson in a language's curriculum order with completion state.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/reviewsGet Reviews

Return a keyset page of the caller's review history.

Parameters

languagequery · optional
updated_afterquery · optional
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

GET/v1/summaryGet Summary

Return the learner's active-language and global state rollup.

Parameters

None.

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
403The API key lacks the required scope.
429Rate limit exceeded.

GET/v1/userGet User

Return the authenticated caller's profile.

Parameters

None.

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
403The API key lacks the required scope.
429Rate limit exceeded.

GET/v1/vocabularyGet Vocabulary

List the caller's vocabulary knowledge inventory for one language.

Parameters

languagequery · required
page_afterquery · optional
per_pagequery · optional

Responses

200Successful Response
401Missing, invalid, revoked, or expired API key.
402Free-tier user filtered to a locked (paid) language.
403The API key lacks the required scope.
404Unknown language code, or no resource with the given id.
422Validation Error
429Rate limit exceeded.

Built for trustworthy tools

Clear boundaries, useful responses.

Keys are scoped, revocable, and stored as hashes.
Every request resolves to the learner who created the key.
Course access rules match the app and return explicit response details.
Rate-limit responses identify when a client should slow down.