REST API Reference

Pro

Base URL: https://launchscore.app/api/v1

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer ls_live_a1b2c3d4e5f6...

API Key Format

Keys use the prefix ls_live_ followed by 32 hex characters (128 bits of entropy).

Important: API keys are shown once at creation time and cannot be retrieved later. Store them securely.

Creating Keys

Create and manage API keys in your studio settings under Settings → API. You can create up to 10 active keys per organization.

Scopes

Each API key is assigned one or more scopes that control what it can access. Choose the minimum scopes needed for your integration.

Scope	Access
ideas:read	List and view idea details
ideas:write	Create, update, delete ideas and trigger AI generation
analytics:read	Access signups, feedback, and analytics data

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Idea not found"
  }
}

Some errors include an additional details field with more context.

Error Codes

Code	Status	Description
MISSING_AUTH	401	Missing or empty Authorization header
INVALID_KEY	401	Invalid or revoked API key
INSUFFICIENT_SCOPE	403	API key lacks the required scope
PLAN_REQUIRED	403	Organization requires a Pro plan
LIMIT_REACHED	403	Usage limit reached (ideas or AI generations)
RATE_LIMITED	429	Too many requests
VALIDATION_ERROR	422	Invalid request body
INVALID_JSON	400	Request body is not valid JSON
INVALID_CURSOR	400	Invalid pagination cursor
INVALID_STATE	400	Idea is in an invalid state for the operation
ALREADY_GENERATED	409	AI content already generated and up-to-date
NOT_FOUND	404	Resource not found
DB_ERROR	500	Internal server error

Rate Limits

API requests are limited to 100 requests per minute per API key. If you exceed this limit, requests return a 429 status with the RATE_LIMITED error code.

If you need higher limits, contact us at support@launchscore.app.

Pagination

List endpoints use cursor-based pagination. Pass limit to control page size (1–100, default 20) and cursor to fetch the next page.

{
  "data": {
    "ideas": [...],
    "pagination": {
      "cursor": "eyJjcmVhdGVkX2F0Ijo...",
      "hasMore": true
    }
  }
}

Pass the cursor value from the previous response to get the next page. When hasMore is false, there are no more results.

Ideas

GET/api/v1/ideasideas:read

List all ideas in your organization.

Parameter	Required	Description
status	No	Filter by status (draft, validating, archived)
limit	No	Results per page (1–100, default 20)
cursor	No	Pagination cursor from previous response

Example

curl -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas

Response

{
  "data": {
    "ideas": [
      {
        "id": "uuid",
        "name": "TaskFlow Pro",
        "tagline": "Project management reimagined",
        "status": "validating",
        "signups": 42,
        "featured": true,
        "generation_status": "complete",
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-20T14:00:00Z",
        "published_at": "2026-01-16T09:00:00Z"
      }
    ],
    "pagination": {
      "cursor": "eyJjcmVhdGVkX2F0Ijo...",
      "hasMore": false
    }
  }
}

POST/api/v1/ideasideas:write

Create a new idea.

Request Body

Parameter	Required	Description
name	Yes	Idea name (max 100 chars)
tagline	Yes	Short tagline (max 200 chars)
problem	Yes	Problem statement (max 1000 chars)
solution	Yes	Proposed solution (max 1000 chars)
differentiator	Yes	What makes this unique (max 500 chars)
targetAudience	Yes	Object: { primary, painPoints[], keywords[] }
features	Yes	Array of { title, description, iconHint? } (max 10)
benefits	Yes	Array of benefit strings (max 10)
branding	Yes	Object: { industry, tone, colorHint?, iconStyle? }
pricing	Yes	Object: { model, pricePoint? }

branding.tone: professional, playful, minimal, bold, friendly, technical

pricing.model: free, freemium, subscription, one-time, usage-based, contact

Example

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TaskFlow Pro",
    "tagline": "Project management reimagined",
    "problem": "Teams waste hours coordinating tasks across tools",
    "solution": "A unified workspace that adapts to your workflow",
    "differentiator": "AI-powered task prioritization",
    "targetAudience": {
      "primary": "Remote engineering teams",
      "painPoints": ["Context switching", "Lost updates"],
      "keywords": ["project management", "collaboration"]
    },
    "features": [
      { "title": "Smart Boards", "description": "AI-organized task boards" }
    ],
    "benefits": ["Ship 2x faster", "Zero context switching"],
    "branding": { "industry": "SaaS", "tone": "professional" },
    "pricing": { "model": "subscription", "pricePoint": "$12/mo" }
  }' \
  https://launchscore.app/api/v1/ideas

Response (201)

{
  "data": {
    "id": "uuid",
    "name": "TaskFlow Pro",
    "status": "draft",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

GET/api/v1/ideas/:idideas:read

Get full idea details including input, generated content, and metrics.

Example

curl -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}

Response

{
  "data": {
    "id": "uuid",
    "name": "TaskFlow Pro",
    "tagline": "Project management reimagined",
    "status": "validating",
    "input": { ... },
    "generated": { "colors": {...}, "copy": {...}, "seo": {...} },
    "generation_status": "complete",
    "signups": 42,
    "featured": true,
    "metrics": {
      "visitors": 380,
      "pageviews": 520,
      "signups": 42,
      "feedbackCount": 8,
      "avgRating": 4.2,
      "conversionRate": 11.05,
      "interestScore": 85
    },
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-20T14:00:00Z",
    "published_at": "2026-01-16T09:00:00Z"
  }
}

PATCH/api/v1/ideas/:idideas:write

Update an idea. Send only the fields you want to change — they are merged with the existing input.

If the input changes, generated content is cleared and generation_status becomes "pending". Call the generate endpoint to regenerate content.

Example

curl -X PATCH \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagline": "The future of project management" }' \
  https://launchscore.app/api/v1/ideas/{id}

Response

{
  "data": {
    "id": "uuid",
    "generation_status": "pending",
    "input_changed": true
  }
}

DELETE/api/v1/ideas/:idideas:write

Archive an idea (soft delete). The idea is not permanently removed.

Example

curl -X DELETE \
  -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}

Response

{
  "data": {
    "id": "uuid",
    "status": "archived"
  }
}

AI Generation

POST/api/v1/ideas/:id/generateideas:write

Trigger AI content generation for an idea. Runs asynchronously — returns immediately with a 202 status.

Returns 409 if content is already generated and up-to-date. Update the idea input first to trigger regeneration.

Example

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}/generate

Response (202)

{
  "data": {
    "status": "generating",
    "idea_id": "uuid"
  }
}

Images

Upload custom images or trigger AI generation for OG (social share) and hero images. Both endpoints accept either a file upload (multipart/form-data) or a JSON body to trigger AI generation.

POST/api/v1/ideas/:id/ogideas:write

Generate or upload an OG (social share) image for an idea.

Two modes: Send multipart/form-data to upload a custom image, or application/json to trigger AI generation (returns 202 immediately).

File Upload

Parameter	Required	Description
file	Yes	Image file (png, jpeg, webp, gif — max 5 MB)

Example — Upload

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@og-image.png" \
  https://launchscore.app/api/v1/ideas/{id}/og

Response (200)

{
  "data": {
    "url": "https://...supabase.co/storage/v1/object/public/idea-assets/og-images/..."
  }
}

AI Generation

Parameter	Required	Description
prompt	No	Custom prompt to guide image generation

Example — Generate

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Minimalist gradient with app icon" }' \
  https://launchscore.app/api/v1/ideas/{id}/og

Response (202)

{
  "data": {
    "status": "generating",
    "idea_id": "uuid"
  }
}

POST/api/v1/ideas/:id/heroideas:write

Generate or upload a hero image for an idea's landing page.

Two modes: Send multipart/form-data to upload a custom image, or application/json to trigger AI generation (returns 202 immediately). Returns 409 if generation is already in progress.

File Upload

Parameter	Required	Description
file	Yes	Image file (png, jpeg, webp, gif — max 5 MB)

Example — Upload

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@hero.png" \
  https://launchscore.app/api/v1/ideas/{id}/hero

Response (200)

{
  "data": {
    "url": "https://...supabase.co/storage/v1/object/public/idea-assets/hero-images/..."
  }
}

AI Generation

Parameter	Required	Description
prompt	No	Custom prompt to guide image generation
style	No	Image style: editorial, product, abstract, concept
mood	No	Image mood: professional, warm, vibrant, dark

Example — Generate

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "style": "illustration", "mood": "vibrant" }' \
  https://launchscore.app/api/v1/ideas/{id}/hero

Response (202)

{
  "data": {
    "status": "generating",
    "idea_id": "uuid"
  }
}

Publishing

POST/api/v1/ideas/:id/publishideas:write

Publish an idea — sets status to "validating" and makes the landing page live.

Example

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}/publish

Response

{
  "data": {
    "id": "uuid",
    "status": "validating"
  }
}

POST/api/v1/ideas/:id/unpublishideas:write

Unpublish an idea — sets status back to "draft".

Example

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}/unpublish

Response

{
  "data": {
    "id": "uuid",
    "status": "draft"
  }
}

Analytics

GET/api/v1/ideas/:id/analyticsanalytics:read

Get full metrics for an idea.

Example

curl -H "Authorization: Bearer $API_KEY" \
  https://launchscore.app/api/v1/ideas/{id}/analytics

Response

{
  "data": {
    "visitors": 380,
    "pageviews": 520,
    "signups": 42,
    "feedbackCount": 8,
    "avgRating": 4.2,
    "conversionRate": 11.05,
    "interestScore": 85
  }
}

GET/api/v1/ideas/:id/signupsanalytics:read

Paginated list of email subscribers for an idea.

Parameter	Required	Description
limit	No	Results per page (1–100, default 20)
cursor	No	Pagination cursor from previous response

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://launchscore.app/api/v1/ideas/{id}/signups?limit=50"

Response

{
  "data": {
    "signups": [
      {
        "email": "user@example.com",
        "created_at": "2026-01-18T12:00:00Z"
      }
    ],
    "pagination": {
      "cursor": "eyJjcmVhdGVkX2F0Ijo...",
      "hasMore": true
    }
  }
}

GET/api/v1/ideas/:id/feedbackanalytics:read

Paginated list of feedback and ratings for an idea.

Parameter	Required	Description
limit	No	Results per page (1–100, default 20)
cursor	No	Pagination cursor from previous response

Example

curl -H "Authorization: Bearer $API_KEY" \
  "https://launchscore.app/api/v1/ideas/{id}/feedback?limit=50"

Response

{
  "data": {
    "feedback": [
      {
        "rating": 5,
        "comment": "Love this concept!",
        "created_at": "2026-01-19T15:30:00Z"
      }
    ],
    "pagination": {
      "cursor": "eyJjcmVhdGVkX2F0Ijo...",
      "hasMore": false
    }
  }
}

Need Help?

Have questions about the API? Reach out at support@launchscore.app

Scope

Access

ideas:read

List and view idea details

ideas:write

Create, update, delete ideas and trigger AI generation

analytics:read

Access signups, feedback, and analytics data

Code

Status

Description

MISSING_AUTH

401

Missing or empty Authorization header

INVALID_KEY

401

Invalid or revoked API key

INSUFFICIENT_SCOPE

403

API key lacks the required scope

PLAN_REQUIRED

403

Organization requires a Pro plan

LIMIT_REACHED

403

Usage limit reached (ideas or AI generations)

RATE_LIMITED

429

Too many requests

VALIDATION_ERROR

422

Invalid request body

INVALID_JSON

400

Request body is not valid JSON

INVALID_CURSOR

400

Invalid pagination cursor

INVALID_STATE

400

Idea is in an invalid state for the operation

ALREADY_GENERATED

409

AI content already generated and up-to-date

NOT_FOUND

404

Resource not found

DB_ERROR

500

Internal server error

Parameter

Required

Description

status

Filter by status (draft, validating, archived)

limit

Results per page (1–100, default 20)

cursor

Pagination cursor from previous response

{ "data": { "ideas": [ { "id": "uuid", "name": "TaskFlow Pro", "tagline": "Project management reimagined", "status": "validating", "signups": 42, "featured": true, "generation_status": "complete", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-20T14:00:00Z", "published_at": "2026-01-16T09:00:00Z" } ], "pagination": { "cursor": "eyJjcmVhdGVkX2F0Ijo...", "hasMore": false } } }

Parameter

Required

Description

name

Yes

Idea name (max 100 chars)

tagline

Yes

Short tagline (max 200 chars)

problem

Yes

Problem statement (max 1000 chars)

solution

Yes

Proposed solution (max 1000 chars)

differentiator

Yes

What makes this unique (max 500 chars)

targetAudience

Yes

Object: { primary, painPoints[], keywords[] }

features

Yes

Array of { title, description, iconHint? } (max 10)

benefits

Yes

Array of benefit strings (max 10)

branding

Yes

Object: { industry, tone, colorHint?, iconStyle? }

pricing

Yes

Object: { model, pricePoint? }

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "TaskFlow Pro", "tagline": "Project management reimagined", "problem": "Teams waste hours coordinating tasks across tools", "solution": "A unified workspace that adapts to your workflow", "differentiator": "AI-powered task prioritization", "targetAudience": { "primary": "Remote engineering teams", "painPoints": ["Context switching", "Lost updates"], "keywords": ["project management", "collaboration"] }, "features": [ { "title": "Smart Boards", "description": "AI-organized task boards" } ], "benefits": ["Ship 2x faster", "Zero context switching"], "branding": { "industry": "SaaS", "tone": "professional" }, "pricing": { "model": "subscription", "pricePoint": "$12/mo" } }' \ https://launchscore.app/api/v1/ideas

{ "data": { "id": "uuid", "name": "TaskFlow Pro", "tagline": "Project management reimagined", "status": "validating", "input": { ... }, "generated": { "colors": {...}, "copy": {...}, "seo": {...} }, "generation_status": "complete", "signups": 42, "featured": true, "metrics": { "visitors": 380, "pageviews": 520, "signups": 42, "feedbackCount": 8, "avgRating": 4.2, "conversionRate": 11.05, "interestScore": 85 }, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-20T14:00:00Z", "published_at": "2026-01-16T09:00:00Z" } }

Parameter

Required

Description

file

Yes

Image file (png, jpeg, webp, gif — max 5 MB)

Parameter

Required

Description

prompt

Custom prompt to guide image generation

curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Minimalist gradient with app icon" }' \ https://launchscore.app/api/v1/ideas/{id}/og

Parameter

Required

Description

file

Yes

Image file (png, jpeg, webp, gif — max 5 MB)

Parameter

Required

Description

prompt

Custom prompt to guide image generation

style

Image style: editorial, product, abstract, concept

mood

Image mood: professional, warm, vibrant, dark

Parameter

Required

Description

limit

Results per page (1–100, default 20)

cursor

Pagination cursor from previous response

{ "data": { "signups": [ { "email": "user@example.com", "created_at": "2026-01-18T12:00:00Z" } ], "pagination": { "cursor": "eyJjcmVhdGVkX2F0Ijo...", "hasMore": true } } }

Parameter

Required

Description

limit

Results per page (1–100, default 20)

cursor

Pagination cursor from previous response

{ "data": { "feedback": [ { "rating": 5, "comment": "Love this concept!", "created_at": "2026-01-19T15:30:00Z" } ], "pagination": { "cursor": "eyJjcmVhdGVkX2F0Ijo...", "hasMore": false } } }