API and integrations

API documentation should rely on generated artifacts from knowspread, but it should not stop at schema descriptions. Integrators also need scenarios, order of operations, idempotence, errors, and product impact.

Sources

Source	Use
swagger/rest/v1/swagger.yaml	OpenAPI contract for the public REST API.
spec/rest/v1/*	Specs as evidence of expected behavior.
app/controllers/rest/v1/*	Real implementation.
app/serializers/*	Response shape and field naming.

Proposed structure

• Authentication
• Users
• Groups
• Content
• Learning events
• Webhooks
• Error handling
• Rate limits and retry strategy

Current public REST API areas

Area	Purpose
Authentication	Get a Bearer JWT token via client credentials.
Users	Manage users in a company space.
User Groups	Groups, membership, and assigned content.
Company Space	Basic information about the space.
Contents	Own content and blended learning content.
Learning Events	Events and their days.
Content Participations	Study reporting and certificates.
Webhooks	Outgoing notifications toward the client.

The detailed contract is generated by rswag into knowspread/swagger/rest/v1/swagger.yaml.