Skip to content
Vocapi guide

API reference

Read your cards, reviews, progress, vocabulary, writing history, and the course content you have access to. These endpoints use GET requests and return JSON.

Make a request

Link to “Make a request”

In Vocapi, open Settings → API keys and create a key with the scopes your tool needs. You can rotate or revoke it from the same screen.

Use the API base URL provided for your environment and send the key as a bearer token:

Terminal window
curl "$VOCAPI_API_BASE/v1/user" \
  -H "Authorization: Bearer $VOCAPI_API_KEY"

Keep the key private. For access and connection details, see Developer access.

16 read endpoints

The list below is generated from Vocapi’s API contract.

GET /v1/achievements Get 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

  • language query · required

Responses

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

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

Parameters

  • language query · optional
  • page_after query · optional
  • per_page query · optional

Responses

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

List a language's lessons in global curriculum order.

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked, or expired API key.
  • 402 Free-tier user filtered to a locked (paid) language.
  • 403 The API key lacks the required scope.
  • 404 Unknown language code, or no resource with the given id.
  • 422 Validation Error
  • 429 Rate limit exceeded.
GET /v1/content/lessons/{lesson_id} Get Content Lesson

Return one lesson in the forward sections/beats shape. The retired blocks arm is deleted (B5 #1629): sections/beats is the one lesson contract, and this read-only mirror follows the service read it wraps -- the same `LessonDetail` projection of the stored compiled build.

Parameters

  • lesson_id path · required

Responses

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

List a language's curated graded readers.

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked, or expired API key.
  • 402 Free-tier user filtered to a locked (paid) language.
  • 403 The API key lacks the required scope.
  • 404 Unknown language code, or no resource with the given id.
  • 422 Validation Error
  • 429 Rate limit exceeded.
GET /v1/content/readers/{item_id} Get Content Reader

Return one curated graded reader with its ordered sections.

Parameters

  • item_id path · required

Responses

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

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

Parameters

  • language query · required
  • grammar_point_id query · optional
  • page_after query · optional
  • per_page query · optional

Responses

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

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

Parameters

  • language query · optional
  • updated_after query · optional
  • page_after query · optional
  • per_page query · optional

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked, or expired API key.
  • 402 Free-tier user filtered to a locked (paid) language.
  • 403 The API key lacks the required scope.
  • 404 Unknown language code, or no resource with the given id.
  • 422 Validation Error
  • 429 Rate limit exceeded.
GET /v1/free-writes/error-patterns Get 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

  • language query · required

Responses

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

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

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

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

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

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

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

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

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

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

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

Parameters

  • language query · optional
  • updated_after query · optional
  • page_after query · optional
  • per_page query · optional

Responses

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

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

Parameters

None.

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked, or expired API key.
  • 403 The API key lacks the required scope.
  • 429 Rate limit exceeded.
GET /v1/user Get User

Return the authenticated caller's profile.

Parameters

None.

Responses

  • 200 Successful Response
  • 401 Missing, invalid, revoked, or expired API key.
  • 403 The API key lacks the required scope.
  • 429 Rate limit exceeded.
GET /v1/vocabulary Get Vocabulary

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

Parameters

  • language query · required
  • page_after query · optional
  • per_page query · optional

Responses

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