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 Personal Access Token (JWT). You can view and copy your token from the Settings page. Include it 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.

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.