Developers & API

Interact with IdeaForks programmatically. Build integrations, export data, or power automated workflows.

Authentication

To use the write endpoints, you need to authenticate using your active Session Token (JWT). You can copy your token from the Settings page. Alternatively, power users and custom integrations can generate a dedicated, long-lived API Key from their account settings. Include your token or key in your requests as a Bearer token:

Authorization: Bearer YOUR_TOKEN_HERE

CLI Tool

We maintain an open-source CLI tool for power users to interact with IdeaForks directly from the terminal. Perfect for quick data dumps or scripting.

npx ideaforks-cli help

* Note: CLI is currently in beta.

REST API Endpoints

GET/api/claims

Fetches the 100 most recent claims. Returns a JSON array of claim objects including title, statement, and author details.

POST/api/claims

Create a new claim or fork. Requires a valid Supabase Auth JWT token or API Key.

Payload for New Idea:

{
  "title": "My New Idea",
  "statement": "A concise statement.",
  "explanation": "Detailed reasoning, scope, and assumptions.",
  "sources": [{ "title": "Study", "url": "https://..." }], // optional
  "citations": ["claim_uuid_here"] // optional array of existing idea IDs
}

Payload for Forking an Idea:

{
  "title": "My Modified Idea",
  "statement": "A concise statement.",
  "explanation": "Why this fork is necessary.",
  "parent_claim_id": "original_idea_uuid",
  "relationship_type": "fork",
  "sources": [{ "title": "Study", "url": "https://..." }], // optional
  "citations": ["claim_uuid_here"] // optional
}

Payload for Alternative View:

{
  "title": "A Competing View",
  "statement": "A concise statement.",
  "explanation": "What assumption do you disagree with? What conclusion is different?",
  "parent_claim_id": "original_idea_uuid",
  "relationship_type": "alternative_view",
  "evidence_statement": "Factual support for this view.", // REQUIRED
  "evidence_source_url": "https://...", // optional
  "citations": ["claim_uuid_here"] // optional
}

GET/api/claims/:id

Fetch a specific claim along with its forks, alternative views, and citation tree.