Ideon Logo
Ideon
GitHub

API Reference

Ideon exposes a RESTful API for frontend interaction. Most endpoints require authentication via session cookies.

System & Health

  • GET /api/health: Returns the service health status.
  • GET /api/system/version: Checks for the latest available version on GitHub.

Authentication

Ideon uses NextAuth.js for core authentication flows.

  • POST /api/auth/register: Register a new account (if public registration is enabled).
  • POST /api/auth/forgot-password: Request a password reset email.
  • POST /api/auth/reset-password: Reset password using a valid token.
  • GET /api/auth/invite?token=[token]: Validate an invitation token.
  • GET /api/auth/me: Get the currently authenticated user's session data.
  • GET /api/auth/settings: Get public authentication configuration (e.g., enabled providers).

Account Management

  • PATCH /api/account: Update user profile (username, display name).
  • POST /api/account/avatar: Upload a new profile picture.

Users (Admin)

Requires admin or superadmin role.

  • GET /api/users: List all users.
  • PATCH /api/users/[id]: Update a user's role.
  • DELETE /api/users/[id]: Delete a user permanently.
  • GET /api/users/search?q=[query]: Search users by email or name.
  • POST /api/users/invite: Create and send a new user invitation.
  • GET /api/users/invite: List all pending invitations.
  • PUT /api/users/invite/[id]: Resend an invitation email.
  • DELETE /api/users/invite/[id]: Revoke a pending invitation.

Projects

  • GET /api/projects: List all projects accessible to the user.
  • POST /api/projects: Create a new project.
  • GET /api/projects/[id]: Get project metadata.
  • DELETE /api/projects/[id]: Delete a project (Owner only).
  • POST /api/projects/[id]/open: Updates the "last opened" timestamp for the project.

Project Graph & Content

  • GET /api/projects/[id]/graph: Fetch the full project graph (blocks and links).
  • POST /api/projects/[id]/graph: Replace the graph state (used for sync).
  • POST /api/projects/[id]/files: Upload a file to the project.
  • GET /api/projects/[id]/files?name=[filename]: Download/Stream a file.
  • DELETE /api/projects/[id]/files?name=[filename]: Delete a file.

Collaboration

  • GET /api/projects/[id]/collaborators: List project members.
  • POST /api/projects/[id]/collaborators: Add or update a collaborator's role.
  • DELETE /api/projects/[id]/collaborators?userId=[id]: Remove a collaborator.

History (Temporal)

  • GET /api/projects/[id]/temporal?action=history: Get the list of state snapshots.
  • POST /api/projects/[id]/temporal: Create a new manual snapshot.
  • GET /api/projects/[id]/temporal?action=reconstruct&stateId=[id]: Revert/Preview a specific past state.

Management (Admin)

  • GET /api/management/audit: Retrieve system audit logs.
  • GET /api/management/auth: Get sensitive auth configuration (SSO settings, etc.).
  • POST /api/management/auth: Update auth configuration.
  • POST /api/management/auth/test-smtp: Send a test email to verify SMTP settings.

Utilities

  • POST /api/links/preview: Fetch OpenGraph metadata for a URL (protected against SSRF).
  • POST /api/git/stats: Fetch statistics for a GitHub repository.