API Documentation

Getting Started

Introduction

The forg.to API gives you read access to public data about builders and their products. It's free, read-only, and requires an API key linked to your forg.to account. Use it to build dashboards, tools, or anything else on top of the forg.to ecosystem.

Base URL

https://api.forg.to/v1

Version

v1

Auth

Bearer token

Quick Start

Get up and running in under a minute:

1Go to forg.to/settings/api and generate a free API key.
2Pass it in the Authorization header of every request.
3Use any of the endpoints below — all responses are JSON.

What you can access

The forg.to API is free with no commercial restrictions. Build whatever you want on top of it. The only rule: don't resell or republish raw data as a standalone dataset.

Getting Started

Authentication

All API requests require authentication using a Bearer token in the Authorization header. You can get your key at forg.to/settings/api.

All requests require header: Authorization: Bearer YOUR_API_KEY
Keys are prefixed with forg_ for easy identification.

Keep your API key safe: Your API key is tied to your forg.to account and carries your privileges. Do not expose it in client-side code, public GitHub repositories, or any untrusted environment.

Getting Started

Rate Limits

To ensure stability and fair use of the API, we enforce rate limits on all endpoints based on your API key.

Tier	Requests per minute	Requests per day
Free	60	5,000

Rate Limit Headers

Every API response includes the following headers to help you track your usage:

X-RateLimit-Limit: The max requests allowed in the current window.
X-RateLimit-Remaining: The number of requests remaining.
X-RateLimit-Reset: A unix timestamp when the limit resets.

If you exceed the rate limit, the API will return a 429 Too Many Requests response. You must wait until the time specified in the X-RateLimit-Reset header.

Getting Started

Errors

The forg.to API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Standard Error Response

{
  "error": {
    "code": "not_found",
    "message": "Product not found"
  }
}

Error Codes

HTTP	Code	Meaning
400	bad_request	Invalid query params
401	unauthorized	Missing or invalid API key
403	forbidden	Key revoked or account banned
404	not_found	Resource does not exist
429	rate_limited	Too many requests
500	server_error	Something went wrong on our end

Endpoints

Products

Products represent what builders on forg.to are making. Every product has a lifecycle status, engagement stats, and a chronological feed of updates.

List ProductsGET /v1/products

Returns a paginated list of public products. Use sort=trending to get the most upvoted this week.

Parameter	Type	Description
pagedefault: 1	number	Page number (1-indexed)
limitdefault: 20	number	Items per page. Maximum 50.
status	string	Filter by lifecycle status. One of: idea, validating, building, alpha, beta, launched, growing, profitable, funded, scaling, paused, dead, acquired.
sortdefault: newest	string	Sort order. newest returns most recently created first. trending returns most upvoted first.

Paginated Response

{
  "data": [
    "...product objects"
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 340,
    "hasMore": true
  }
}

Get ProductGET /v1/products/:slug

Retrieve a single product by its slug. Returns 404 if the product doesn't exist or is private.

Parameter	Type	Description
slugRequired	string	The product's unique URL slug, e.g. my-product-name.

List Product UpdatesGET /v1/products/:slug/updates

Returns all published updates (build logs, milestones, launches, etc.) for a product, sorted by most recent. Pinned updates always appear first.

Parameter	Type	Description
slugRequired	string	The product's slug.
pagedefault: 1	number	Page number.
limitdefault: 20	number	Items per page. Maximum 50.

Product Object

{
  "id": "6789abc123",
  "name": "Doomed",
  "slug": "doomed",
  "tagline": "Twitter for builders who ship",
  "description": "A focused microblogging platform for indie makers.",
  "logo": "https://cdn.forg.to/logos/doomed.png",
  "website": "https://doomed.build",
  "github": null,
  "status": "building",
  "keywords": [
    "social",
    "builders",
    "indie"
  ],
  "isOpenSource": false,
  "sourceCodeUrl": null,
  "category": "social_media_tools",
  "platforms": [
    "web"
  ],
  "productType": "saas",
  "priceType": "free",
  "stats": {
    "upvotes": 128,
    "updates": 34
  },
  "owner": {
    "username": "kislay",
    "displayName": "Kislay",
    "profileImage": "https://cdn.forg.to/avatars/kislay.jpg"
  },
  "launchDate": null,
  "createdAt": "2025-11-01T00:00:00.000Z"
}

Update Object

{
  "id": "upd_a1b2c3",
  "type": "milestone",
  "title": "Hit 1,000 users",
  "content": "Just crossed 1,000 signups. Here's what worked...",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.forg.to/media/abc.jpg",
      "caption": "Growth chart"
    }
  ],
  "engagement": {
    "likes": 47,
    "comments": 12
  },
  "author": {
    "username": "kislay",
    "displayName": "Kislay",
    "profileImage": "https://cdn.forg.to/avatars/kislay.jpg"
  },
  "product": {
    "slug": "doomed",
    "name": "Doomed",
    "logo": "https://cdn.forg.to/logos/doomed.png"
  },
  "publishedAt": "2026-03-10T14:00:00.000Z"
}

Endpoints

Users

Users are the builders on forg.to. The API exposes their public profile information — bio, skills, social links, and activity stats. Private information (email, tokens, settings) is never returned.

Users who have enabled incognito mode or whose accounts are not active will return 404 from all user endpoints.

Get Builder ProfileGET /v1/users/:username

Returns a builder's full public profile including stats (products, updates, followers, following).

Parameter	Type	Description
usernameRequired	string	The builder's username on forg.to. Case-insensitive.

List User's ProductsGET /v1/users/:username/products

Returns all public products owned by a builder, sorted by most recently created. Private products are never returned.

Parameter	Type	Description
usernameRequired	string	The builder's username.
pagedefault: 1	number	Page number.
limitdefault: 20	number	Items per page. Maximum 50.

List User's UpdatesGET /v1/users/:username/updates

Returns all published updates from a builder across all their products, sorted by most recent. Use the type filter to narrow by update category.

Parameter	Type	Description
usernameRequired	string	The builder's username.
pagedefault: 1	number	Page number.
limitdefault: 20	number	Items per page. Maximum 50.
type	string	Filter by update type. One of: update, launch, feature, milestone, revenue, bugfix, design, idea, fail, win, announcement, integration.

User Object

{
  "username": "kislay",
  "displayName": "Kislay",
  "profileImage": "https://cdn.forg.to/avatars/kislay.jpg",
  "bio": "Building things in public. forg.to founder.",
  "location": "India",
  "website": "https://kislay.dev",
  "skills": [
    {
      "name": "Next.js",
      "category": "framework"
    },
    {
      "name": "TypeScript",
      "category": "language"
    }
  ],
  "socialLinks": [
    {
      "platform": "twitter",
      "url": "https://twitter.com/kislay"
    }
  ],
  "openTo": {
    "jobs": false,
    "freelance": false,
    "collaborations": true,
    "mentorship": true
  },
  "isPremium": true,
  "stats": {
    "products": 4,
    "updates": 87,
    "followers": 512,
    "following": 134
  },
  "joinedAt": "2024-06-01T00:00:00.000Z"
}

Reference

Changelog

Breaking changes will always be versioned (v2, v3, ...) so existing integrations keep working. Non-breaking additions are shipped continuously.

March 2026v1.0Initial Release

Public API launched at api.forg.to/v1
Endpoints: GET /products, /products/:slug, /products/:slug/updates
Endpoints: GET /users/:username, /users/:username/products, /users/:username/updates
API key authentication with per-key rate limiting (60 req/min, 5,000 req/day)
Rate limit headers on all responses (X-RateLimit-Limit, Remaining, Reset)