Ideon Logo
Ideon

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.
  • GET /api/system/changelog: Fetch the latest changelog from the GitHub repository.

Authentication

Ideon uses NextAuth.js for core authentication flows and supports OAuth 2.0 + SAML 2.0 for enterprise SSO.

  • 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 OAuth providers).
  • POST /api/auth/sso/[provider]: Initiate OAuth 2.0 flow with specified provider (e.g., google, discord, slack).
  • POST /api/auth/sso/saml: Handle SAML 2.0 assertions and metadata endpoints (managed by SAML Jackson).

Account Management

  • PATCH /api/account: Update user profile (username, display name).
  • POST /api/account/avatar: Upload a new profile picture (multipart form, max 5MB, JPEG/PNG/WebP/GIF).
  • GET /api/user/git-tokens: List all connected Git provider tokens.
  • POST /api/user/git-tokens: Add a new Git provider token.
  • PATCH /api/user/git-tokens: Enable/Disable a Git token.
  • DELETE /api/user/git-tokens?id=[id]: Delete a Git token.

Folders

  • GET /api/folders?view=[view]: List folders. view can be starred, trash, shared, or my-projects.
  • POST /api/folders: Create a new folder.
  • GET /api/folders/[id]: Get folder details.
  • PATCH /api/folders/[id]: Update folder (rename, star, soft delete).
  • DELETE /api/folders/[id]?permanent=[bool]: Delete a folder. If permanent=true, projects are moved to root.
  • GET /api/folders/[id]/collaborators: List folder members.
  • POST /api/folders/[id]/collaborators: Add or update a folder collaborator.
  • DELETE /api/folders/[id]/collaborators?userId=[id]: Remove a folder collaborator.

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: Update the "last opened" timestamp for the project.
  • DELETE /api/projects/trash: Empty the trash (permanently delete all soft-deleted projects and folders).

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.

Sharing & Access

  • GET /api/projects/[id]/share: Get sharing status and public link details (Owner only).
  • POST /api/projects/[id]/share: Generate a new public share link (Owner only).
  • PATCH /api/projects/[id]/share: Toggle public sharing on/off (Owner only).
  • DELETE /api/projects/[id]/share: Revoke the public share link (Owner only).
  • POST /api/projects/[id]/request-access: Request access to a project.
  • GET /api/projects/[id]/request-access: Check the status of your access request.
  • GET /api/projects/[id]/requests: List pending access requests (Owner only).
  • PATCH /api/projects/[id]/requests: Approve or reject access requests (Owner only).

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). Body: { url: string }. Returns: { title, description, image }.
  • GET /api/git/stats?url=[url]: Fetch repository statistics (stars, releases, commits, issues, contributors) for a Git repository. Respects user Git tokens for private/self-hosted repos.
  • GET /api/proxy/image?url=[url]: Proxy image requests to avoid CORS issues and provide SSRF protection. Returns the proxied image with appropriate headers.