Analysis Endpoints: Create, Query, and Manage Reports

The analysis endpoints are the core of the AI Startup Analyzer platform. They allow you to submit a startup idea for multi-agent AI processing, track processing progress, retrieve completed reports broken down across 13 strategic dimensions, regenerate any individual section on demand, chat conversationally with AI about your results, and inspect your plan’s usage limits. Every endpoint under /analysis requires a valid accessToken cookie — see the Authentication guide for how to obtain one. State-changing requests (POST, DELETE) also require an X-XSRF-TOKEN header — see the CSRF section.

GET /analysis/csrf-token

Generates a cryptographically random CSRF token, sets it as a readable XSRF-TOKEN cookie, and returns it in the response body. Call this before any POST or DELETE request to /analysis. This endpoint does require authentication (the accessToken cookie), but does not require a CSRF header itself.

Response

csrfToken

string

A 64-character hex string generated from 32 cryptographically random bytes. Use this value as the X-XSRF-TOKEN header on subsequent state-changing requests.

curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token

POST /analysis

Submits a startup idea for analysis. The server checks your plan’s monthly limit, creates an Analysis record with status PENDING, enqueues it for multi-agent processing, and returns the new record immediately. Processing happens asynchronously — use GET /analysis/:id/progress to track completion. Requires: accessToken cookie + X-XSRF-TOKEN header.

Request Body

idea

string

required

The startup idea to analyze. Must be at least 10 characters and no more than 2000 characters. Characters `< > ” ’ “ are stripped, and prompt-injection patterns are removed before the idea is processed.

Response

string

CUID identifier for the newly created analysis. Use this in all subsequent calls.

idea

string

The sanitized idea text as stored.

status

string

Initial value is always "PENDING". Transitions to PROCESSING, then COMPLETED or FAILED.

userId

string

The ID of the authenticated user who owns this analysis.

content

string

Empty string on creation; populated as agents complete.

createdAt

string

ISO 8601 timestamp of when the analysis was created.

updatedAt

string

ISO 8601 timestamp of the last update.

Errors

Status	Condition
`400 Bad Request`	`idea` field is missing, not a string, or shorter than 10 characters after trimming
`401 Unauthorized`	Missing or invalid `accessToken` cookie
`403 Forbidden`	Missing or invalid `X-XSRF-TOKEN` header
`409 Conflict`	Monthly analysis limit reached for your current plan (FREE: 3, PRO: 50, TEAM: 999)

CSRF=$(curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token | jq -r '.csrfToken')

curl -s -b cookies.txt -c cookies.txt \
  -X POST http://localhost:4000/analysis \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
    "idea": "A B2B SaaS platform that uses machine learning to predict customer churn in subscription businesses and recommends personalized retention campaigns to customer success teams."
  }'

GET /analysis/:id/progress

Returns the current processing progress for an analysis. Poll this endpoint repeatedly until status is COMPLETED or FAILED. For completed analyses the server returns progress: 100 without hitting the job queue; for failed analyses it returns progress: 0. Requires: accessToken cookie. No CSRF token needed (GET request).

Path Parameters

string

required

The CUID of the analysis to check.

Response

status

string

One of PENDING, PROCESSING, COMPLETED, or FAILED.

progress

number

An integer from 0 to 100 representing the percentage of agent steps completed. 100 when COMPLETED; 0 when FAILED.

ANALYSIS_ID="clx4k7m2v0000abc123xyz789"

while true; do
  RESULT=$(curl -s -b cookies.txt \
    http://localhost:4000/analysis/$ANALYSIS_ID/progress)
  STATUS=$(echo $RESULT | jq -r '.status')
  PROGRESS=$(echo $RESULT | jq -r '.progress')
  echo "Status: $STATUS | Progress: $PROGRESS%"
  if [[ "$STATUS" == "COMPLETED" || "$STATUS" == "FAILED" ]]; then
    break
  fi
  sleep 3
done

A polling interval of 2–4 seconds works well for most analyses. Processing typically takes 30–90 seconds depending on plan, model latency, and queue depth.

GET /analysis

Returns a paginated list of all analyses belonging to the authenticated user, ordered by most recently created first. Only summary fields are returned (not the full agent results). Requires: accessToken cookie.

Query Parameters

skip

number

Number of records to skip for pagination. Defaults to 0.

take

number

Number of records to return. Defaults to 20, maximum 50.

Response

An array of analysis summary objects:

string

CUID of the analysis.

idea

string

The startup idea text.

status

string

Current status: PENDING, PROCESSING, COMPLETED, or FAILED.

overallScore

number | null

Composite AI-assigned score (0–100). null until the analysis completes.

marketDemandScore

number | null

Market demand sub-score. null until complete.

profitPotentialScore

number | null

Profit potential sub-score. null until complete.

createdAt

string

ISO 8601 creation timestamp.

curl -s -b cookies.txt \
  "http://localhost:4000/analysis?skip=0&take=20"

GET /analysis/:id

Returns the full analysis record for a single analysis, including all agent result fields. Agent results are stored as JSON strings in the database; they are returned as parsed objects in the response. Requires: accessToken cookie. The analysis must belong to the authenticated user.

Path Parameters

string

required

The CUID of the analysis to retrieve.

Response

The full Analysis object with all fields populated (those not yet generated remain null):

string

CUID identifier.

idea

string

The original startup idea text.

status

string

PENDING | PROCESSING | COMPLETED | FAILED

ideaAnalysis

object | null

Show IdeaAnalysis fields

summary

string

One-paragraph summary of the idea.

coreProblem

string

The core problem being solved.

targetUsers

string[]

List of target user personas.

industry

string

Industry classification.

useCases

string[]

Key use cases for the product.

comprehensiveIdeaAnalysis

object | null

Deep multi-dimension viability assessment including market opportunity, competitive analysis, target audience fit, financial feasibility, and risk assessment scores.

marketResearch

object | null

TAM/SAM/SOM sizing, growth trends, and geographic opportunities.

competitorAnalysis

object | null

Direct and indirect competitors with strengths, weaknesses, and pricing.

mvpPlan

object | null

Product name, tagline, core features (prioritized), KPIs, development complexity, and estimated time.

monetization

object | null

Recommended monetization model and pricing tiers.

goToMarket

object | null

Marketing channels, communities, partnerships, and growth hacks.

riskRadar

object | null

Risk factors and mitigation strategies.

roadmap

object | null

Development and launch roadmap.

businessModel

object | null

Business model canvas breakdown.

visionMission

object | null

Vision and mission statements.

brandIdentity

object | null

Brand positioning, voice, and identity recommendations.

budgetEstimate

object | null

Budget estimation across development, marketing, and operations.

overallScore

number | null

Composite score 0–100.

marketDemandScore

number | null

Market demand sub-score.

competitionScore

number | null

Competition intensity sub-score.

executionDifficultyScore

number | null

Execution difficulty sub-score.

profitPotentialScore

number | null

Profit potential sub-score.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

curl

curl -s -b cookies.txt \
  http://localhost:4000/analysis/clx4k7m2v0000abc123xyz789

GET /analysis/:id/idea-analysis

Returns only the ideaAnalysis section of a completed analysis — a lightweight alternative to fetching the full record when you only need the core idea breakdown. Requires: accessToken cookie. The analysis must belong to the authenticated user.

Path Parameters

string

required

The CUID of the analysis whose idea-analysis section you want to retrieve.

Response

Returns the ideaAnalysis object if it has been generated, or null if the analysis is still pending or the section has not yet been produced.

summary

string

One-paragraph summary of the startup idea.

coreProblem

string

The core problem the idea is solving.

targetUsers

string[]

List of target user personas identified for the idea.

industry

string

Industry classification for the startup.

useCases

string[]

Key use cases for the product or service.

curl -s -b cookies.txt \
  http://localhost:4000/analysis/clx4k7m2v0000abc123xyz789/idea-analysis

DELETE /analysis/:id

Permanently deletes an analysis record and all its agent results. This action is irreversible. Requires: accessToken cookie + X-XSRF-TOKEN header.

Path Parameters

string

required

The CUID of the analysis to delete. Must belong to the authenticated user.

Response

success

boolean

true when the record was successfully deleted.

CSRF=$(curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token | jq -r '.csrfToken')

curl -s -b cookies.txt \
  -X DELETE http://localhost:4000/analysis/clx4k7m2v0000abc123xyz789 \
  -H "X-XSRF-TOKEN: $CSRF"

POST /analysis/:id/retry

Re-queues a failed analysis for processing. Only analyses with status = "FAILED" can be retried. The status is reset to PENDING and a new job is added to the queue with a unique retry job ID to prevent collisions. Requires: accessToken cookie + X-XSRF-TOKEN header.

Path Parameters

string

required

The CUID of the failed analysis to retry.

Response

success

boolean

true when the retry was successfully enqueued.

CSRF=$(curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token | jq -r '.csrfToken')

curl -s -b cookies.txt \
  -X POST http://localhost:4000/analysis/clx4k7m2v0000abc123xyz789/retry \
  -H "X-XSRF-TOKEN: $CSRF"

After calling retry, use GET /analysis/:id/progress to track the new processing run. A retry does not count against your monthly analysis limit.

POST /analysis/:id/regenerate/:section

Regenerates a single section of a completed analysis using the corresponding AI agent, and updates the stored value. This is useful for refreshing stale results or getting alternative outputs without re-running the full analysis pipeline. Requires: accessToken cookie + X-XSRF-TOKEN header.

Path Parameters

string

required

The CUID of the analysis whose section should be regenerated.

section

string

required

The section slug to regenerate. Must be one of the values listed below.

Section Slugs

Slug	Description
`idea-analysis`	Core problem, target users, industry, and use cases
`comprehensive-idea-analysis`	Multi-dimension viability scoring across 6 categories
`market-research`	TAM/SAM/SOM, growth trends, geographic opportunities
`competitor-analysis`	Direct and indirect competitors with SWOT breakdown
`mvp`	Product name, features (MoSCoW priority), KPIs, feasibility
`monetization`	Recommended model, pricing tiers, reasoning
`go-to-market`	Channels, communities, partnerships, growth hacks
`risk-radar`	Risk factors and mitigation strategies
`roadmap`	Phased development and launch roadmap
`business-model`	Business model canvas
`vision-mission`	Vision and mission statement generation
`brand-identity`	Brand positioning, voice, and visual identity
`budget`	Budget estimation across cost categories

Response

Returns an object with a single key matching the regenerated section’s database field name and the newly generated result as the value.

CSRF=$(curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token | jq -r '.csrfToken')

curl -s -b cookies.txt \
  -X POST http://localhost:4000/analysis/clx4k7m2v0000abc123xyz789/regenerate/market-research \
  -H "X-XSRF-TOKEN: $CSRF"

POST /analysis/chat

Sends a conversational message to the AI, optionally grounded in a specific analysis report as context. Returns a concise AI-generated reply. Ideal for follow-up questions, clarifications, or exploring specific aspects of a report. Rate limit: 10 requests per 60 seconds per user. Requires: accessToken cookie + X-XSRF-TOKEN header.

Request Body

message

string

required

The question or message to send to the AI assistant. Maximum 500 characters after trimming. Must not be empty.

context

string

required

The analysis report content to use as grounding context for the AI response. Maximum 3000 characters. Pass a stringified summary or the relevant section text from a completed analysis.

analysisId

string

Optional CUID of an analysis. When provided, the server verifies the analysis belongs to the authenticated user before processing the message. This is recommended to prevent context injection.

Response

string

The AI assistant’s response to the message, grounded in the provided context.

Errors

Status	Condition
`400 Bad Request`	`message` is empty or missing; `analysisId` provided but analysis not found
`429 Too Many Requests`	More than 10 chat requests in the past 60 seconds

CSRF=$(curl -s -b cookies.txt -c cookies.txt \
  http://localhost:4000/analysis/csrf-token | jq -r '.csrfToken')

curl -s -b cookies.txt \
  -X POST http://localhost:4000/analysis/chat \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
    "message": "What are the top 3 risks I should focus on first?",
    "context": "Market demand is high, competition is moderate. Key risks include regulatory uncertainty, high CAC in enterprise sales, and dependency on third-party ML infrastructure.",
    "analysisId": "clx4k7m2v0000abc123xyz789"
  }'

GET /analysis/me/plan

Returns the authenticated user’s current subscription plan, the number of analyses used this calendar month, and the monthly limit for their plan. Requires: accessToken cookie.

Response

plan

string

The user’s current plan: "FREE", "PRO", or "TEAM".

used

number

Number of analyses created in the current calendar month.

limit

number

Maximum analyses allowed per month for the current plan. FREE = 3, PRO = 50, TEAM = 999.

curl -s -b cookies.txt \
  http://localhost:4000/analysis/me/plan

The monthly usage counter resets at the start of each calendar month. If you receive a 409 Conflict from POST /analysis, check this endpoint to confirm your current usage and consider upgrading your plan.

Overview

Endpoints

Analysis Endpoints: Create, Query, and Manage Reports

GET /analysis/csrf-token

Response

POST /analysis

Request Body

Response

Errors

GET /analysis/:id/progress

Path Parameters

Response

GET /analysis

Query Parameters

Response

GET /analysis/:id

Path Parameters

Response

GET /analysis/:id/idea-analysis

Path Parameters

Response

DELETE /analysis/:id

Path Parameters

Response

POST /analysis/:id/retry

Path Parameters

Response

POST /analysis/:id/regenerate/:section

Path Parameters

Section Slugs

Response

POST /analysis/chat

Request Body

Response

Errors

GET /analysis/me/plan

Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /analysis/csrf-token

​Response

​POST /analysis

​Request Body

​Response

​Errors

​GET /analysis/:id/progress

​Path Parameters

​Response

​GET /analysis

​Query Parameters

​Response

​GET /analysis/:id

​Path Parameters

​Response

​GET /analysis/:id/idea-analysis

​Path Parameters

​Response

​DELETE /analysis/:id

​Path Parameters

​Response

​POST /analysis/:id/retry

​Path Parameters

​Response

​POST /analysis/:id/regenerate/:section

​Path Parameters

​Section Slugs

​Response

​POST /analysis/chat

​Request Body

​Response

​Errors

​GET /analysis/me/plan

​Response

Build docs developers (and LLMs) love

GET /analysis/csrf-token

Response

POST /analysis

Request Body

Response

Errors

GET /analysis/:id/progress

Path Parameters

Response

GET /analysis

Query Parameters

Response

GET /analysis/:id

Path Parameters

Response

GET /analysis/:id/idea-analysis

Path Parameters

Response

DELETE /analysis/:id

Path Parameters

Response

POST /analysis/:id/retry

Path Parameters

Response

POST /analysis/:id/regenerate/:section

Path Parameters

Section Slugs

Response

POST /analysis/chat

Request Body

Response

Errors

GET /analysis/me/plan

Response