AI Startup Analyzer REST API Reference and Overview

The AI Startup Analyzer REST API gives you programmatic access to every capability in the platform — from registering users and managing sessions to creating multi-agent startup analyses, polling processing progress, regenerating individual report sections, and chatting with AI about your results. This reference covers every endpoint, its parameters, expected responses, and the security requirements you need to satisfy.

Base URL

All API endpoints are served from a single origin. In local development the server binds to port 4000:

http://localhost:4000

In staging or production, set the BACKEND_URL environment variable on your frontend or client application to override this default. The server port can also be changed via BACKEND_PORT.

Content Type

Every request that includes a body must set the Content-Type header to application/json. Every successful response also returns application/json. There are no form-encoded or multipart endpoints.

Content-Type: application/json
Accept: application/json

Authentication

The API does not use Authorization: Bearer headers. Authentication is handled exclusively through httpOnly cookies that the server sets automatically on successful login or registration. Your HTTP client must persist and re-send these cookies on every subsequent request.

accessToken — A signed JWT valid for 7 days. Sent with every protected request.
refreshToken — An opaque token valid for 30 days, used to issue a new access token pair.

For browser-based clients using fetch or axios, enable credential forwarding:

// fetch
fetch('http://localhost:4000/analysis', { credentials: 'include' });

// axios
axios.get('/analysis', { withCredentials: true });

For curl testing, use -c to save cookies and -b to send them:

curl -c cookies.txt http://localhost:4000/auth/login ...
curl -b cookies.txt http://localhost:4000/analysis

See the Authentication guide for the full cookie and CSRF flow.

CSRF Protection

State-changing requests to /analysis routes (POST and DELETE) require a valid CSRF token in addition to the auth cookie. Fetch the token first, then include it as an X-XSRF-TOKEN header. See Authentication — CSRF flow for details.

Error Codes

The API returns standard HTTP status codes. Error responses include a JSON body with a message field (and sometimes a statusCode field) describing the problem.

Status Code	Meaning
`400 Bad Request`	Missing or invalid request body / query parameters
`401 Unauthorized`	Missing, expired, or invalid access token cookie
`403 Forbidden`	Authenticated but not permitted to access the resource
`404 Not Found`	Resource does not exist or does not belong to the authenticated user
`409 Conflict`	Monthly analysis limit reached for your current plan
`429 Too Many Requests`	Rate limit exceeded — back off and retry
`500 Internal Server Error`	Unexpected server error

{
  "statusCode": 409,
  "message": "Monthly limit reached (3 for FREE plan)."
}

Rate Limits

Certain endpoints are rate-limited at two timescales to prevent abuse. The server returns 429 Too Many Requests when a limit is exceeded.

Endpoint	Per Minute	Per Hour
`POST /auth/register`	5 requests	20 requests
`POST /auth/login`	10 requests	50 requests
`POST /analysis/chat`	10 requests / 60 s	—

Quick Start: Full Flow Example

The following curl sequence demonstrates a complete end-to-end flow — register a new account, obtain a CSRF token, submit a startup idea for analysis, and poll for completion.

curl -s -c cookies.txt \
  -X POST http://localhost:4000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@example.com",
    "password": "Str0ng!Pass#99",
    "name": "Alex Founder"
  }'
# Response: { "user": { "id": "clx...", "email": "founder@example.com" } }
# Cookies saved: accessToken, refreshToken

API Sections

Auth Endpoints

Analysis Endpoints

Create analyses, poll progress, retrieve reports, regenerate sections, chat with AI, and manage plan usage.

Authentication Guide

Deep dive into cookie-based JWT auth, the CSRF double-submit pattern, and token refresh flow.

Health Check

Server liveness endpoint for load balancers, container probes, and uptime monitors.

Overview

Endpoints

Documentation Index

​Base URL

​Content Type

​Authentication

​CSRF Protection

​Error Codes

​Rate Limits

​Quick Start: Full Flow Example

​API Sections