README — GET /api/v1/orgs/{id}/documents
List class-owned documents
GET /api/v1/orgs/{id}/documents · Operation ID: listOrgDocuments
Application use
Returns documents owned by class:, not every personal document belonging to students or every document shared with the class. For human members, teachers and co-teachers have owner-level access, billing and students normally viewer access. A personally granted editor role can matter when opening a specific document. New org-owned tokens receive a role-derived access label here, but individual-document checks identify their own class principal as owner. Do not infer viewer-only service-token authority from this listing label; see the identity guide. Use the shared document API for content and edits, and follow all cursor pages.
Authentication and permission
Bearer credential with documents:read. Membership plus documents:read; token document restrictions also filter results.
Scopes, membership, current role, effective policy and applicable plan checks all apply. A managed student token cannot grant organisation-management authority. A student-pool login JWT is not a public-API bearer credential. See Classroom identity and roles.
Example
Replace placeholders using an authorised disposable test class. Mutation examples change real data when run. Keep tokens on the server; never copy student credentials into diagnostics.
curl --fail-with-body -X GET 'https://handwrites.io/api/v1/orgs/REPLACE_ORG_ID/documents' \
-H "Authorization: Bearer $HANDWRITE_API_TOKEN"
Parameters
| Name | In | Required | Details |
|---|---|---|---|
id | path | Yes | An organisation ID (org_…). |
since | query | No | ISO 8601 time: every change after it, oldest first, with tombstones (sync). |
limit | query | No | Page size, 1–100. |
cursor | query | No | The cursor from the previous page (opaque). |
Responses and recovery
| Status | Meaning | Format |
|---|---|---|
| 200 | With your access: managers owner, team members editor, students viewer. | application/json |
| 400 | invalid_request (the message names the field), validation_failed. | application/json |
| 401 | unauthorized: no token, or it's invalid, revoked or expired. | application/json |
| 403 | insufficient_scope, forbidden (you can see it but not do this), app_test_restricted, account_deleted (the account is scheduled for deletion; any request). | application/json |
| 404 | not_found: it doesn't exist or you can't see it (never 403 for documents you can't see). | application/json |
| 429 | rate_limited (burst or daily cap) or quota_exceeded (no characters left). | application/json |
| 500 | internal_error. | application/json |
The paired API reference holds the shared machine-readable schema. Additional role, policy, seat and plan failures are described in API specification notes. Do not parse 204 or 304 responses as JSON, and do not treat 403 as a transient retry.