fe9f8c441f
* fix(automation): align public API plan gating across cloud and self-hosted Add shared canUsePublicApi helper so cloud allows Early Adopter and Enterprise while self-hosted requires Enterprise. Update the API key dashboard page and backend key creation checks to use the same rules. Co-authored-by: Rotimi Best <[email protected]> * docs(api): document bearer auth on public API reference Add shared OpenAPI enrichment with bearerAuth security scheme and authentication instructions. The interactive reference now loads an enriched spec with Authorize support, and the API guide explains how to create and use org API keys. Co-authored-by: Rotimi Best <[email protected]> * feat(dashboard): add API quick-start code snippets on automation page Mirror the MCP client setup section with cURL, JavaScript, and Python examples that show how to authenticate public API requests with org keys. Co-authored-by: Rotimi Best <[email protected]> * ci(openapi): republish spec when public API OpenAPI helpers change Co-authored-by: Rotimi Best <[email protected]> * feat(dashboard): add Go snippet to API quick-start examples Co-authored-by: Rotimi Best <[email protected]> * docs(api): use /org/*/api and clarify dashboard key generation path Co-authored-by: Rotimi Best <[email protected]> * fix(api): escape backticks in OpenAPI description template literal Greptile flagged that unescaped backticks around * in PUBLIC_API_OPENAPI_DESCRIPTION evaluated to NaN and dropped auth docs from the Scalar spec. Also use plan-specific snackbar message on upgrade. Co-authored-by: Rotimi Best <[email protected]> --------- Co-authored-by: Cursor Agent <[email protected]> Co-authored-by: Rotimi Best <[email protected]>
95 lines
2.8 KiB
Plaintext
95 lines
2.8 KiB
Plaintext
---
|
|
title: API
|
|
description: Use the ClassroomIO public API to manage audience members and courses with organization-scoped API keys.
|
|
---
|
|
|
|
import { Callout } from 'fumadocs-ui/components/callout';
|
|
import { Step, Steps } from 'fumadocs-ui/components/steps';
|
|
|
|
The ClassroomIO public API is available under:
|
|
|
|
```text
|
|
https://api.classroomio.com/public-api/v1
|
|
```
|
|
|
|
Every request must include an organization-scoped API key as a Bearer token.
|
|
|
|
## Get an API key
|
|
|
|
Generate keys in the ClassroomIO dashboard as an **organization admin**.
|
|
|
|
<Steps>
|
|
<Step>
|
|
Sign in to [ClassroomIO](https://app.classroomio.com).
|
|
</Step>
|
|
<Step>
|
|
In the org sidebar, open the **Automation** section, then **API**.
|
|
</Step>
|
|
<Step>
|
|
Or go directly to [`/org/*/api`](https://app.classroomio.com/org/*/api). The `*` picks your current organization automatically.
|
|
</Step>
|
|
<Step>
|
|
Click **Generate API key**, name the key, and copy the secret immediately. Keys are shown only once and look like `cio_api_...`.
|
|
</Step>
|
|
<Step>
|
|
Send the key on every request as `Authorization: Bearer cio_api_your_key_here`.
|
|
</Step>
|
|
</Steps>
|
|
|
|
<Callout type="warn" title="Paid Access">
|
|
On ClassroomIO Cloud, API key creation is available on **Early Adopter** and **Enterprise** plans. Self-hosted deployments require **Enterprise**.
|
|
</Callout>
|
|
|
|
## Interactive Reference
|
|
|
|
- [Open the interactive API reference](/docs/api/reference)
|
|
|
|
The reference page includes an **Authorize** button. Paste your API key there to try endpoints without writing curl commands.
|
|
|
|
### Try requests in the reference UI
|
|
|
|
1. Open the [interactive API reference](/docs/api/reference).
|
|
2. Click **Authorize** (lock icon).
|
|
3. Select **bearerAuth** and paste your full `cio_api_...` key.
|
|
4. Use **Try it** on any endpoint.
|
|
|
|
### curl example
|
|
|
|
```bash
|
|
curl https://api.classroomio.com/public-api/v1/audience \
|
|
-H "Authorization: Bearer cio_api_your_key_here"
|
|
```
|
|
|
|
## Current Surface
|
|
|
|
Current public API groups:
|
|
|
|
- `audience`
|
|
- `courses`
|
|
|
|
Implemented route families:
|
|
|
|
- `GET /public-api/v1/audience`
|
|
- `POST /public-api/v1/audience`
|
|
- `POST /public-api/v1/audience/assign-courses`
|
|
- `GET /public-api/v1/audience/:memberId`
|
|
- `PUT /public-api/v1/audience/:memberId`
|
|
- `DELETE /public-api/v1/audience/:memberId`
|
|
- `GET /public-api/v1/courses`
|
|
- `GET /public-api/v1/courses/:courseId`
|
|
- `GET /public-api/v1/courses/:courseId/students`
|
|
- `GET /public-api/v1/courses/:courseId/export`
|
|
|
|
## OpenAPI
|
|
|
|
Raw OpenAPI JSON:
|
|
|
|
- [Public API OpenAPI JSON](https://api.cdn.clsrio.com/openapi/public-api/openapi-latest.json)
|
|
- [Interactive API Reference](/docs/api/reference)
|
|
|
|
## Notes
|
|
|
|
- API keys are organization-scoped.
|
|
- Enrollment is handled through `POST /public-api/v1/audience/assign-courses`.
|
|
- The API documentation will expand as the remaining public API write endpoints are added.
|