IdeaForge
Sign inRequest Beta Access

API Reference

v1

Programmatic access to the IdeaForge dynamic idea-scoring engine. Score ideas, retrieve analyses, and browse the dimension library.

Base URL:https://tryideaforge.com
Authentication

Public endpoints require no authentication. Authenticated endpoints require a bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

API keys are available on Pro+ tiers (Forge and above). View pricing →

Rate limits: Free tier — 10 req/min · Pro — 60 req/min · Enterprise — custom.

POST/api/quick-scorePublic

Instant 10-dimension score for any idea — fastest analysis, no auth required.

Request Body (JSON)

ideastringrequiredIdea description (20–10,000 chars)
categorystringIdea category (optional). One of: SaaS, E-commerce, Consumer App, Marketplace, Hardware/IoT, Health & Wellness, Education, Finance & FinTech, Gaming, Media & Entertainment, Retail & CPG, Professional Services, Other

Example

curl -X POST https://tryideaforge.com/api/quick-score \
  -H "Content-Type: application/json" \
  -d '{"idea": "A B2B SaaS platform for automated invoice reconciliation"}'

Response

{
  "score": 72.4,
  "grade": "B+",
  "dimensionSignature": "Workflow-Efficiency Optimizer",
  "topStrengths": ["Clear pain point", "Recurring revenue model"],
  "topRisks": ["Competitive market", "Integration complexity"],
  "dimensions": [
    { "name": "Market Size", "score": 78, "category": "Market" },
    ...
  ]
}
POST/api/analyzeAuth required

Full multi-dimensional analysis. Dispatches an async job — poll /api/analyze/[jobId] for results.

Request Body (JSON)

ideastringrequiredIdea description (20–10,000 chars)
tierstringAnalysis tier. Defaults to 'spark' (100 dims). Options: spark · forge · vault · ignite · inferno · apex · titan · oracle · nexus · atlas · singularity · cosmic
categorystringIdea category (see quick-score for options)

Example

curl -X POST https://tryideaforge.com/api/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"idea": "...", "tier": "forge"}'

Response

{
  "jobId": "job_abc123",
  "status": "queued",
  "tier": "forge"
}
POST/api/analyze/batchAuth required

Submit up to 5 ideas in a single request. Each is dispatched as an independent async job. Returns HTTP 207 when some items succeed and others fail.

Request Body (JSON)

ideasarrayrequiredArray of 1–5 idea objects, each with { idea, category, tier }

Example

curl -X POST https://tryideaforge.com/api/analyze/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"ideas":[{"idea":"...","category":"Technology","tier":"spark"},{"idea":"...","category":"Business","tier":"spark"}]}'

Response

{
  "jobs": [
    { "index": 0, "jobId": "uuid-1" },
    { "index": 1, "jobId": "uuid-2" }
  ],
  "failed": [
    { "index": 2, "error": "Rate limit exceeded — remaining ideas skipped" }
  ],
  "total": 3
}
GET/api/rate-limit/statusPublic

Return the caller's current analysis quota without consuming a request.

Example

curl https://tryideaforge.com/api/rate-limit/status

Response

{
  "tier": "anonymous",
  "allowed": true,
  "remaining": 4,
  "limit": 5,
  "resetAt": "2026-04-17T18:30:00.000Z",
  "resetInSeconds": 842
}
GET/api/analyze/[jobId]Auth required

Poll for analysis results by job ID. Returns 202 while in progress, 200 when complete.

Path / Query Params

jobIdstringrequiredJob ID returned from POST /api/analyze

Example

curl https://tryideaforge.com/api/analyze/job_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "complete",
  "result": {
    "overallScore": 81.2,
    "grade": "A",
    "dimensionSignature": "High-Signal Recurring Revenue Play",
    "dimensionCount": 200,
    "tier": "forge",
    "synthesis": { "executiveBrief": "...", "topStrengths": [...], ... },
    "dimensionData": [ ... ]
  }
}
GET/api/dimensionsPublic

Browse the VaultSpark v5 dimension library — 2,500 dimensions across 9 categories.

Path / Query Params

categorystringFilter by category ID (A–I)
qstringFull-text search within dimension names and descriptions
limitnumberMax results (default 50, max 500)

Example

curl "https://tryideaforge.com/api/dimensions?category=A&limit=10"

Response

{
  "dimensions": [
    { "name": "Market Size", "category": "A", "baseWeight": 1.0, "ideaPool": "all" },
    ...
  ],
  "total": 2500
}
POST/api/shareAuth required

Generate a public share token for an analysis result. Returns a shareable URL.

Request Body (JSON)

analysisIdstringrequiredAnalysis ID to share

Example

curl -X POST https://tryideaforge.com/api/share \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"analysisId": "abc123"}'

Response

{
  "token": "a3f9b2...",
  "shareUrl": "https://tryideaforge.com/share/a3f9b2...",
  "expiresAt": null
}
GET/api/report/[analysisId]Auth required

Generate a printable HTML/PDF report for an owned analysis, with optional white-label branding query params.

Path / Query Params

analysisIdstringrequiredAnalysis ID to export
companyNamestringOptional brand name shown in the report header
accentColorhex colorOptional #RRGGBB accent color
footerTextstringOptional footer copy

Example

curl "https://tryideaforge.com/api/report/abc123?companyName=Acme&accentColor=%2300E5A0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

<!DOCTYPE html>
<html>
  <!-- branded printable report -->
</html>
GET/api/dilPublic

Dimension Intelligence Loop stats — which dimensions are most predictive and how feedback shapes scoring.

Example

curl https://tryideaforge.com/api/dil

Response

{
  "totalSignals": 14302,
  "uniqueDimensions": 847,
  "topAccurateDimensions": [ ... ],
  "topFeedbackWeighted": [ ... ]
}
GET/api/trendsAuth required

Category scoring breakdown for the authenticated user — per-category counts, average scores, grade distribution, and weekly analysis volume.

Example

curl https://tryideaforge.com/api/trends \
  -H "Authorization: Bearer <token>"

Response

{
  "categories": [
    {
      "category": "Technology",
      "count": 12,
      "avgScore": 71.2,
      "topScore": 88.5,
      "recentCount": 5,
      "grades": { "A": 3, "B": 5, "C": 4 }
    }
  ],
  "weekly": [
    { "week": "2026-04-14", "count": 7, "avgScore": 69.3 }
  ],
  "totalAnalyses": 12,
  "totalCompleted": 12
}
POST/api/feedbackAuth required

Submit overall accuracy feedback or per-dimension votes on an analysis. Feeds the Dimension Intelligence Loop.

Request Body (JSON)

analysisIdstringrequiredAnalysis ID
overall"up" | "down"Overall accuracy vote
dimensionFeedbackarrayPer-dimension votes: [{dimensionName, vote: 'up'|'down'}]

Example

curl -X POST https://tryideaforge.com/api/feedback \
  -H "Content-Type: application/json" \
  -d '{"analysisId": "abc123", "overall": "up"}'

Response

{ "ok": true }

The IdeaForge API is in early access. Endpoints may change before general availability.

Questions? founder@vaultsparkstudios.com