API & MCP documentation
Manage plans with your AI assistant. Consume credits from your own app. Both use the same permission-checked services.
Connect an AI assistant
Add Litesubs as a remote MCP server in a compatible client. Use this URL:
https://litesubs.com/api/mcp- Choose a remote HTTP MCP connection in your client and paste the endpoint above.
- Sign in to Litesubs and review the requested permissions.
- Approve access, then ask your assistant to create a plan, enroll a student, or grant credits.
Example: Create an Algebra plan with 10 credits for $100.
Or: Enroll ana@example.com in Algebra and give me the payment link.
Supports the stateless MCP 2026-07-28 profile and CIMD client identification. Legacy session-based and DCR-only clients are not currently supported. If your client cannot connect, check its protocol support.
Creator tools: list/get/create/update plans, list/get customers, enroll customers, grant credits, and list transactions. The consumption tool is available to machine keys only. No payout or refund tools are exposed.
Authentication
Creator operations: use OAuth through your MCP client. The scopes are plans:read, plans:write, customers:read, customers:write, and billing:read. An OAuth access token can also call REST endpoints with Authorization: Bearer <token>.
Machine consumption: generate an API token and send it in the x-api-key header. Tokens only consume credits; they cannot edit plans, grant credits, or read billing history. Keep them on your backend, never in public frontend code.
Tokens are shown once when generated. Save them securely; revoke and replace a lost or exposed token. Token expiration and rate limits are enforced on verification.
REST API
Base URL: https://litesubs.com. Send JSON bodies with Content-Type: application/json. List routes accept limit (1–100, default 50) and offset.
| Method | Path | Purpose |
|---|---|---|
| GET / POST | /api/v1/plans | Read or create plans |
| GET / PATCH | /api/v1/plans/:id | Read or update a plan |
| GET | /api/v1/customers | Read enrolled customers |
| GET | /api/v1/customers/:id | Read a customer's per-plan balances |
| POST | /api/v1/enrollments | Enroll or invite a customer |
| POST | /api/v1/credits/grant | Grant credits |
| POST | /api/v1/credits/consume | Consume credits with a machine key |
| GET | /api/v1/transactions | Read transaction history |
| GET / POST | /api/v1/invites | Read or create invites |
Plan creation takes {"name":"Algebra","price":100,"credits":10,"currency":"usd"}. Input prices are in major units ($100); returned prices are in minor units (10000 cents). Currencies: USD and EUR. Updating a plan does not change existing balances.
Errors return error, code, and optional details or fieldErrors. Expect 400 for invalid input, 401 for failed authentication, 403 for missing access, 404 for missing resources, and 409 for ambiguous identifiers or credit conflicts.
Credits and retries
Balances belong to a customer and a specific plan, not a shared wallet. Use exact names, emails, or IDs; ambiguous names require an explicit ID. Credits cannot go negative.
curl 'https://litesubs.com/api/v1/credits/consume' \
+ -H 'x-api-key: <your token>' \
+ -H 'Content-Type: application/json' \
+ -d '{"customer":"ana@example.com","plan":"Algebra","amount":1,"reason":"Lesson completed","idempotency_key":"booking_8812"}'A stable idempotency_key is required for consumption. Reuse it when retrying the same event: the original receipt is returned without another debit. A different payload using the same key returns a conflict. Grants accept an optional key.
reason is required and visible in the customer ledger. Set dry_run: true to preview a before/after balance without writing or reserving a key. Receipts contain transactionId, before, after, dryRun, and replayed.
Enrollment
Send {"customer":"ana@example.com","plan":"Algebra","mode":"invoice"} to /api/v1/enrollments, or use enroll_customer in MCP. Invoice mode is the default; it returns a checkout link and grants credits only after payment.
For complimentary access, set mode: "comp" and provide a reason. An existing enrollment cannot be comped again; use a separate credit grant.
If the student has no account, the result is invited with an expiring claim link. Complimentary credits are granted once on claim. No email is sent. Forward the returned invitation or payment link yourself.