API.md

CogFlow Platform API Docs

This page is the API documentation hub.

Canonical machine-readable contract:

• docs/openapi.json

Regenerate the schema artifact:

./scripts/generate_openapi.sh

API Documentation Split

• Public API: participant-facing and integration-safe endpoints for launch and result submission paths.
• Researcher API: authenticated researcher workflows (study lifecycle, sharing, analysis jobs, assets).
• Admin API (Internal): privileged platform administration endpoints.
• Builder/Interpreter Schema API: runtime config/timeline schema contracts used by Builder and Interpreter.
• Contributor Guide: formatting, sync workflow, and merge process for platform contributions.

Internal Security References

• Admin Security Policy
• Admin Action Security Matrix

Website Public-Public Copy Pack

• CogFlow Overview
• Advantages and SEO Points
• Customization and Services
• Tutorials Page Copy

Publication Scopes

• Public website docs (cogflow.app) should publish only Public API and approved Researcher API sections.
• Admin API docs should remain internal-only documentation.

Endpoint Source of Truth

Endpoint routing lives in backend/project/urls.py. OpenAPI is generated from the running backend schema endpoint (/api/schema) using the script above.

Runtime Schema Source of Truth

Builder/Interpreter schema contracts are documented in docs/API_SCHEMAS.md and sourced from:

• frontend/builder/src/schemas/JSPsychSchemas.js
• frontend/interpreter/src/timelineCompiler.js
• backend/project/api_views_common.py task scope definitions

Update Policy

Follow docs/DOCS_MAINTENANCE.md for update triggers, cadence, and release gates.