# Sylla API

> Sylla is a study tracker anybody can sign up for. Its API lets an app read one person's syllabus (subjects and sessions), their own progress, grades and stats, and record progress for them, always with their consent through OAuth 2.0 with PKCE. No endpoint ever returns another person's data.

Key facts for code generation:

- Base URL: https://sylla.study. JSON everywhere; errors are `{ error, error_description, request_id }`.
- Auth: OAuth 2.0 authorization code with PKCE (S256 only) for apps; personal access tokens (`sylp_...`) for a person's own scripts. Both are sent as `Authorization: Bearer ...`.
- Access tokens last 1 hour; refresh tokens last 60 days and rotate on every use, so always store the newest one.
- Rate limit: 120 requests per 60 seconds per connection; on 429 wait `Retry-After` seconds.
- Sessions have a syllabus month (1-12), not a date. Scheduling is the app's job.
- Webhooks are signed with HMAC-SHA256 in `Sylla-Signature: t=<seconds>,v1=<hex>` over `${t}.${rawBody}`.
- MCP: Sylla is also a remote MCP server at https://sylla.study/api/mcp (streamable HTTP, stateless, JSON answers), with the same Bearer tokens, scopes and rate limit. Tools: `list_subjects`, `list_sessions`, `get_session`, `get_stats`, `set_session_status`, `record_grade`, `update_task`.

## Docs

- [Full reference for LLMs](https://sylla.study/llms-full.txt): every endpoint, scope, webhook and error in one Markdown file
- [API docs](https://sylla.study/developers/docs): the same reference for people, with samples in cURL, JavaScript and Python
- [OpenAPI 3.1](https://sylla.study/api/v1/openapi.json): for client generators
- [OAuth server metadata](https://sylla.study/.well-known/oauth-authorization-server)

## Endpoints

- `GET /api/v1/me`: Who the token belongs to (scope `profile.read`)
- `GET /api/v1/subjects`: The subjects in this person's syllabus (scope `sessions.read`)
- `GET /api/v1/sessions`: The syllabus with this person's progress (scope `sessions.read`)
- `GET /api/v1/sessions/{sessionId}`: One session (scope `sessions.read`)
- `PATCH /api/v1/progress/{sessionId}`: Mark a session, or its tasks, for this person (scope `progress.write`)
- `POST /api/v1/progress/batch`: Mark many sessions at once (scope `progress.write`)
- `GET /api/v1/plan/today`: Today's study plan: its next step and the streak (scope `plan.read`)
- `GET /api/v1/stats`: Work done, Average, XP, level and streak (scope `stats.read`)
- `GET /api/v1/achievements`: Achievements, held and still to reach (scope `stats.read`)
- `GET /api/v1/study-days`: Days this person studied (scope `stats.read`)
- `POST /api/mcp`: Sylla as an MCP server, for AI assistants
- `GET /oauth/authorize`: Send the person here to connect
- `POST /api/oauth/token`: Swap a code or refresh token for tokens
- `POST /api/oauth/revoke`: Disconnect (RFC 7009)
- `POST /api/oauth/introspect`: Is this token still good (RFC 7662)
- `GET /.well-known/oauth-authorization-server`: Server metadata (RFC 8414)
- `POST /api/oauth/register`: Register a client yourself (RFC 7591)
- `GET /.well-known/oauth-protected-resource/api/mcp`: Where to sign in for the MCP server (RFC 9728)

## Optional

- [Developer portal](https://sylla.study/developers): register apps, webhooks, logs, team
- [Playground](https://sylla.study/developers/playground): try requests with a personal access token