All API requests require a Bearer token in the Authorization header.
Authorization: Bearer hrv_live_a1b2c3d4e5f6...
Keys use the prefix hrv_live_ followed by 32 hex characters (128 bits of entropy). Keys are stored only as a SHA-256 hash — the raw key is never persisted.
Important: API keys are shown once at creation time and cannot be retrieved later. Store them securely.
Create and manage API keys in your studio settings under Settings → API. You can create up to 10 active keys per organization. The REST API is a Pro feature — requests from a key on a Free organization return PLAN_REQUIRED.
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 and OG cards |
| ideas:write | Create, update, delete, publish ideas and trigger AI generation |
| analytics:read | Access signups, feedback, and analytics data |
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. Successful responses are wrapped in a data envelope.
| 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 |
| CONFLICT | 409 | A generation is already in progress |
| NOT_SUPPORTED | 415 | Operation not supported (e.g. direct image upload) |
| SERVICE_UNAVAILABLE | 503 | Image generation service not configured |
| NOT_FOUND | 404 | Resource not found |
| DB_ERROR | 500 | Internal server error |
API requests are limited to 100 requests per minute per API key. Exceeding this returns a 429 status with the RATE_LIMITED error code.
AI generation endpoints (content and hero image generation) are subject to an additional, tighter limit of 10 requests per minute per organization.
If you need higher limits, contact us at support@launchscore.io.
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
}
}
}When hasMore is true, pass the returned cursor on the next request to fetch the following page.
/ideasList your organization's ideas, newest first, with cursor pagination.
| Parameter | Required | Description |
|---|---|---|
| limit | No | Page size, 1–100 (default 20) |
| cursor | No | Pagination cursor from a previous response |
| status | No | Filter by status (draft, validating, launched, archived) |
curl https://launchscore.io/api/v1/ideas?limit=20 \ -H "Authorization: Bearer hrv_live_..."
/ideasCreate a new idea from authored input. The new idea starts in draft status.
The request body is the idea input (name, tagline, problem, solution, target audience, features). name is required.
curl -X POST https://launchscore.io/api/v1/ideas \
-H "Authorization: Bearer hrv_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "TaskFlow",
"tagline": "Automate your busywork",
"problem": "Teams waste hours on repetitive tasks",
"solution": "AI-driven workflow automation",
"targetAudience": "Operations teams",
"features": ["No-code builder", "Integrations"]
}'/ideas/:idFetch a single idea with its input, generated content, metrics, and generation status.
/ideas/:idPartially update an idea's input. The patch is merged onto the existing input and revalidated. Changing the input clears generated content (generation_status becomes pending) so it can be regenerated.
curl -X PATCH https://launchscore.io/api/v1/ideas/IDEA_ID \
-H "Authorization: Bearer hrv_live_..." \
-H "Content-Type: application/json" \
-d '{ "tagline": "A sharper tagline" }'/ideas/:idArchive an idea (soft delete). The idea's status is set to archived; it is not permanently removed.
/ideas/:id/generateTrigger AI generation of landing-page content (colors, copy, SEO, icons) from the idea's input. Runs asynchronously and returns 202 Accepted. Poll GET /ideas/:id and watch generation_status until it is complete.
Returns ALREADY_GENERATED (409) when content is already up to date with the current input — change the input (via PATCH) to trigger a regeneration. Counts against your monthly AI generation allowance.
{ "data": { "status": "generating", "idea_id": "IDEA_ID" } }/ideas/:id/heroGenerate an AI hero image for the idea. Runs asynchronously and returns 202 Accepted. Poll GET /ideas/:id for the resulting hero_image_url.
Optional JSON body to steer the generation. Direct file uploads are not supported (multipart returns NOT_SUPPORTED). Counts against your monthly AI generation allowance.
| Parameter | Required | Description |
|---|---|---|
| prompt | No | Custom image prompt |
| style | No | Visual style (abstract, illustration, 3d, minimal) |
| mood | No | Optional mood/tone hint |
/ideas/:id/publishPublish an idea (status → validating), making its landing page live. The first publish stamps published_at.
/ideas/:id/unpublishReturn an idea to draft, taking its landing page offline. published_at is preserved.
/ideas/:id/ogReturn the idea's OpenGraph / Twitter social card as a 1200×630 PNG, rendered on the fly from the idea's generated copy and brand colors.
This endpoint responds with an image, not JSON. OG cards are generated dynamically — there is no stored binary to upload, so custom uploads return NOT_SUPPORTED.
/ideas/:id/analyticsEngagement metrics for an idea: views, unique visitors, CTA clicks, signups, feedback count, average rating, and conversion rate.
/ideas/:id/signupsList the idea's email signups (newest first), with cursor pagination.
| Parameter | Required | Description |
|---|---|---|
| limit | No | Page size, 1–100 (default 20) |
| cursor | No | Pagination cursor from a previous response |
/ideas/:id/feedbackList the idea's feedback responses (rating + comment, newest first), with cursor pagination.
| Parameter | Required | Description |
|---|---|---|
| limit | No | Page size, 1–100 (default 20) |
| cursor | No | Pagination cursor from a previous response |
Have questions or feedback? Reach out to us at support@launchscore.io