{
  "openapi": "3.1.0",
  "info": {
    "title": "Ponicorn API",
    "version": "1.0.0",
    "description": "Where indie founders learn how small internet businesses grow, launch their own, and show their numbers, with the source behind every figure. Reading needs no key. Adding a startup needs a personal API key and files a submission for a person to read; nothing here publishes, edits or deletes."
  },
  "servers": [
    {
      "url": "https://ponicorn.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A personal key from /dashboard/api-keys, sent as `Authorization: Bearer pon_…`. Server-side only: a key in browser JavaScript is a leaked key, which is why the write endpoint answers no CORS preflight."
      }
    },
    "schemas": {
      "Source": {
        "type": [
          "object",
          "null"
        ],
        "description": "The page a figure was read from. Reviewer notes and crawl bookkeeping are deliberately absent.",
        "properties": {
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ]
          },
          "source_type": {
            "type": "string"
          },
          "author": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Metric": {
        "type": "object",
        "description": "One dated figure with the evidence behind it. `label` is the site's own binary: verified when the founder stands behind the profile, when Ponicorn read it from their connected payment account, or when a third party read it from a public dashboard.",
        "properties": {
          "metric": {
            "type": "string",
            "enum": [
              "mrr",
              "arr",
              "annual_revenue",
              "monthly_revenue",
              "users",
              "paid_customers",
              "total_customers",
              "downloads",
              "installs",
              "funding_raised",
              "valuation",
              "acquisition_price",
              "profit",
              "traffic",
              "total_revenue"
            ]
          },
          "value": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Whole units."
          },
          "value_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217."
          },
          "measured_at": {
            "type": "string",
            "description": "YYYY-MM-DD; when it was true."
          },
          "period_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "evidence_status": {
            "type": "string",
            "enum": [
              "reported",
              "estimated",
              "inferred"
            ]
          },
          "verified_via": {
            "type": [
              "string",
              "null"
            ]
          },
          "connected_via": {
            "type": [
              "string",
              "null"
            ]
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ]
          },
          "label": {
            "type": "string",
            "enum": [
              "verified",
              "unverified"
            ]
          },
          "is_current": {
            "type": "boolean"
          },
          "verified_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "disputed": {
            "type": "boolean",
            "description": "The founder has disputed this figure and a person is looking."
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/Source"
          }
        }
      },
      "Term": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "StartupSummary": {
        "type": "object",
        "description": "A startup as it appears in a list. Identity is the slug.",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Its page on the site."
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "founded_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2."
          },
          "team_size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "funding_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "bootstrapped",
              "angel",
              "venture",
              "other",
              null
            ]
          },
          "status": {
            "type": "string"
          },
          "primary_category": {
            "type": [
              "string",
              "null"
            ]
          },
          "founder": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              }
            }
          },
          "founder_verified": {
            "type": "boolean"
          },
          "editor_verified": {
            "type": "boolean"
          },
          "likes": {
            "type": "integer"
          },
          "headline_metric": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Metric"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "StartupDetail": {
        "type": "object",
        "description": "One startup in full. Every field of the summary, plus the complete dated figure history and the source behind each figure.",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Its page on the site."
          },
          "tagline": {
            "type": [
              "string",
              "null"
            ]
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "founded_year": {
            "type": [
              "integer",
              "null"
            ]
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2."
          },
          "team_size": {
            "type": [
              "integer",
              "null"
            ]
          },
          "funding_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "bootstrapped",
              "angel",
              "venture",
              "other",
              null
            ]
          },
          "status": {
            "type": "string"
          },
          "primary_category": {
            "type": [
              "string",
              "null"
            ]
          },
          "founder": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              }
            }
          },
          "founder_verified": {
            "type": "boolean"
          },
          "editor_verified": {
            "type": "boolean"
          },
          "likes": {
            "type": "integer"
          },
          "headline_metric": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Metric"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "ownership": {
            "type": "string"
          },
          "startup_cost": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer"
              },
              "currency": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "note": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "launch_time_days": {
            "type": [
              "integer",
              "null"
            ]
          },
          "launch_time_note": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "string"
          },
          "founders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "slug": {
                  "type": "string"
                },
                "role": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "is_primary": {
                  "type": "boolean"
                },
                "website_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "x_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "linkedin_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "business_models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "technologies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "growth_channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            }
          },
          "milestones": {
            "type": "array",
            "description": "Figures the founder posted, each already read by a person.",
            "items": {
              "type": "object",
              "properties": {
                "note": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "published_at": {
                  "type": "string"
                },
                "metric": {
                  "$ref": "#/components/schemas/Metric"
                }
              }
            }
          },
          "alternatives": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          }
        }
      },
      "Milestone": {
        "type": "object",
        "properties": {
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": "string"
          },
          "startup": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "metric": {
            "$ref": "#/components/schemas/Metric"
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "Where this page sits in the result.",
        "properties": {
          "number": {
            "type": "integer",
            "description": "1-based."
          },
          "size": {
            "type": "integer",
            "description": "Rows asked for."
          },
          "total": {
            "type": "integer",
            "description": "Rows matching, across all pages."
          },
          "pages": {
            "type": "integer"
          }
        }
      },
      "Links": {
        "type": "object",
        "description": "The caller's own request with the page changed, so paging never means rebuilding a query string. `next` is null on the last page.",
        "properties": {
          "self": {
            "type": "string"
          },
          "next": {
            "type": [
              "string",
              "null"
            ]
          },
          "prev": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Taxonomy": {
        "type": "object",
        "description": "Only terms a published startup actually uses, so a filter built from this never returns nothing.",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "business_models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "technologies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          },
          "funding_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "team_sizes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          },
          "revenue_bands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "min_monthly_usd": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "max_monthly_usd": {
                  "type": [
                    "integer",
                    "null"
                  ]
                }
              }
            }
          },
          "sorts": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "all_funding_types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metric_types": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Every failure, on every endpoint, has this shape.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "bad_request",
                  "unauthorized",
                  "invalid_key",
                  "key_revoked",
                  "not_found",
                  "method_not_allowed",
                  "unsupported_media_type",
                  "payload_too_large",
                  "unprocessable",
                  "rate_limited",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "description": "Per-field messages, when the request named fields.",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/startups": {
      "get": {
        "summary": "Search published startups",
        "description": "The same filters `/startups` uses, so a filtered URL from the site works here by changing only the path. An unknown filter value is ignored rather than refused; call `/api/v1/taxonomy` for the slugs that exist.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Name or tagline fragment; at most 80 characters.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Category slug. See `/api/v1/taxonomy`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "description": "Business-model slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "stack",
            "in": "query",
            "required": false,
            "description": "Technology slug.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "revenue",
            "in": "query",
            "required": false,
            "description": "Current monthly-equivalent USD revenue band.",
            "schema": {
              "type": "string",
              "enum": [
                "under_1k",
                "1k_10k",
                "10k_50k",
                "50k_250k",
                "250k_plus"
              ]
            }
          },
          {
            "name": "team",
            "in": "query",
            "required": false,
            "description": "Team-size band.",
            "schema": {
              "type": "string",
              "enum": [
                "solo",
                "small",
                "medium",
                "large"
              ]
            }
          },
          {
            "name": "funding",
            "in": "query",
            "required": false,
            "description": "How the business was funded.",
            "schema": {
              "type": "string",
              "enum": [
                "bootstrapped",
                "angel",
                "venture",
                "other"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Ordering. Defaults to `newest`.",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "likes",
                "revenue",
                "name"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of startups.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StartupSummary"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "name": "Example",
                      "slug": "example",
                      "url": "https://ponicorn.com/startups/example",
                      "tagline": "What the business does, in one line.",
                      "website_url": "https://example.com",
                      "logo_url": null,
                      "founded_year": 2024,
                      "country_code": "PT",
                      "team_size": 1,
                      "funding_type": "bootstrapped",
                      "status": "active",
                      "primary_category": "developer-tools",
                      "founder": {
                        "name": "Ada Lovelace",
                        "slug": "ada-lovelace"
                      },
                      "founder_verified": true,
                      "editor_verified": false,
                      "likes": 34,
                      "headline_metric": {
                        "metric": "mrr",
                        "value": 12000,
                        "value_text": null,
                        "currency": "USD",
                        "measured_at": "2026-08-01",
                        "period_type": "monthly",
                        "evidence_status": "reported",
                        "verified_via": null,
                        "connected_via": "stripe",
                        "confidence": "high",
                        "label": "verified",
                        "is_current": true,
                        "verified_at": "2026-08-03",
                        "disputed": false,
                        "note": null,
                        "source": {
                          "url": "https://example.com/six-months-in",
                          "title": "Six months in",
                          "publisher": "Example Blog",
                          "source_type": "founder_post",
                          "author": "Ada Lovelace",
                          "published_at": "2026-08-01"
                        }
                      }
                    }
                  ],
                  "page": {
                    "number": 1,
                    "size": 25,
                    "total": 63,
                    "pages": 3
                  },
                  "links": {
                    "self": "https://ponicorn.com/api/v1/startups?revenue=10k_50k&page=1",
                    "next": "https://ponicorn.com/api/v1/startups?revenue=10k_50k&page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "A `page` or `limit` that is not a number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "bad_request",
                    "message": "page must be a positive whole number.",
                    "details": {
                      "page": "page must be a positive whole number."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Carries `retry-after: 60`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Try again in a minute."
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit a startup for review",
        "description": "Creates a pending submission attributed to the key's owner. It never publishes. Send `content-type: application/json`; the body is capped at 64 KB. This endpoint answers no CORS preflight, because a key in browser JavaScript is a leaked key.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "website_url",
                  "description",
                  "founders"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "website_url": {
                    "type": "string",
                    "description": "Absolute http(s) URL of the product's own site."
                  },
                  "description": {
                    "type": "string",
                    "description": "What the business does, in plain prose. A figure written here must also appear in `claim`, or the row is flagged."
                  },
                  "founders": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Real people. Never an LLC, a studio, or an App Store seller name."
                  },
                  "category_slugs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "technology_slugs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "business_model_slugs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "growth_channel_slugs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "claim": {
                    "type": "object",
                    "description": "Optional current monthly revenue. Recorded at low confidence until a reviewer or a payment platform says otherwise.",
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "Whole units, e.g. `12000`."
                      },
                      "currency": {
                        "type": "string",
                        "description": "ISO 4217. Defaults to USD."
                      },
                      "source_url": {
                        "type": "string",
                        "description": "The page stating the figure."
                      }
                    }
                  },
                  "note": {
                    "type": "string",
                    "description": "Context for the reviewer. Never shown publicly."
                  }
                }
              },
              "example": {
                "name": "Example",
                "website_url": "https://example.com",
                "description": "What the business does.",
                "founders": [
                  "Ada Lovelace"
                ],
                "business_model_slugs": [
                  "saas"
                ],
                "category_slugs": [
                  "developer-tools"
                ],
                "technology_slugs": [
                  "typescript"
                ],
                "claim": {
                  "value": "12000",
                  "currency": "USD",
                  "source_url": "https://example.com/six-months-in"
                },
                "note": "I am the founder."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Filed for review. Nothing is published by this call.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "submission_id": {
                          "type": "integer"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending_review"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "submission_id": 412,
                    "status": "pending_review",
                    "message": "Filed for review. A person reads every submission before anything is published."
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "A valid API key is required."
                  }
                }
              }
            }
          },
          "422": {
            "description": "The submission did not validate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unprocessable",
                    "message": "Some fields need attention.",
                    "details": {
                      "website_url": "Enter the product's own http(s) address."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Carries `retry-after: 60`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/startups/{slug}": {
      "get": {
        "summary": "One published startup in full",
        "description": "Every dated figure with the source behind it. A figure the site marks disputed comes back marked.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The startup's slug, e.g. `example`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The startup, its figures and their sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/StartupDetail"
                    }
                  }
                },
                "example": {
                  "data": {
                    "name": "Example",
                    "slug": "example",
                    "url": "https://ponicorn.com/startups/example",
                    "tagline": "What the business does, in one line.",
                    "website_url": "https://example.com",
                    "logo_url": null,
                    "founded_year": 2024,
                    "country_code": "PT",
                    "team_size": 1,
                    "funding_type": "bootstrapped",
                    "status": "active",
                    "primary_category": "developer-tools",
                    "founder": {
                      "name": "Ada Lovelace",
                      "slug": "ada-lovelace"
                    },
                    "founder_verified": true,
                    "editor_verified": false,
                    "likes": 34,
                    "headline_metric": {
                      "metric": "mrr",
                      "value": 12000,
                      "value_text": null,
                      "currency": "USD",
                      "measured_at": "2026-08-01",
                      "period_type": "monthly",
                      "evidence_status": "reported",
                      "verified_via": null,
                      "connected_via": "stripe",
                      "confidence": "high",
                      "label": "verified",
                      "is_current": true,
                      "verified_at": "2026-08-03",
                      "disputed": false,
                      "note": null,
                      "source": {
                        "url": "https://example.com/six-months-in",
                        "title": "Six months in",
                        "publisher": "Example Blog",
                        "source_type": "founder_post",
                        "author": "Ada Lovelace",
                        "published_at": "2026-08-01"
                      }
                    },
                    "description": "A longer paragraph on what the business does and for whom.",
                    "ownership": "independent",
                    "startup_cost": {
                      "amount": 400,
                      "currency": "USD",
                      "note": "Domain and hosting."
                    },
                    "launch_time_days": 45,
                    "launch_time_note": null,
                    "published_at": "2026-06-02T09:00:00.000Z",
                    "updated_at": "2026-08-14T11:20:00.000Z",
                    "founders": [
                      {
                        "name": "Ada Lovelace",
                        "slug": "ada-lovelace",
                        "role": "Founder",
                        "is_primary": true,
                        "website_url": "https://example.com",
                        "x_url": null,
                        "linkedin_url": null
                      }
                    ],
                    "categories": [
                      {
                        "name": "Developer tools",
                        "slug": "developer-tools"
                      }
                    ],
                    "business_models": [
                      {
                        "name": "SaaS",
                        "slug": "saas"
                      }
                    ],
                    "technologies": [
                      {
                        "name": "TypeScript",
                        "slug": "typescript"
                      }
                    ],
                    "growth_channels": [
                      {
                        "name": "Content",
                        "slug": "content"
                      }
                    ],
                    "metrics": [
                      {
                        "metric": "mrr",
                        "value": 12000,
                        "value_text": null,
                        "currency": "USD",
                        "measured_at": "2026-08-01",
                        "period_type": "monthly",
                        "evidence_status": "reported",
                        "verified_via": null,
                        "connected_via": "stripe",
                        "confidence": "high",
                        "label": "verified",
                        "is_current": true,
                        "verified_at": "2026-08-03",
                        "disputed": false,
                        "note": null,
                        "source": {
                          "url": "https://example.com/six-months-in",
                          "title": "Six months in",
                          "publisher": "Example Blog",
                          "source_type": "founder_post",
                          "author": "Ada Lovelace",
                          "published_at": "2026-08-01"
                        }
                      }
                    ],
                    "milestones": [
                      {
                        "note": "Crossed 12k MRR.",
                        "published_at": "2026-08-03T08:00:00.000Z",
                        "metric": {
                          "metric": "mrr",
                          "value": 12000,
                          "value_text": null,
                          "currency": "USD",
                          "measured_at": "2026-08-01",
                          "period_type": "monthly",
                          "evidence_status": "reported",
                          "verified_via": null,
                          "connected_via": "stripe",
                          "confidence": "high",
                          "label": "verified",
                          "is_current": true,
                          "verified_at": "2026-08-03",
                          "disputed": false,
                          "note": null,
                          "source": {
                            "url": "https://example.com/six-months-in",
                            "title": "Six months in",
                            "publisher": "Example Blog",
                            "source_type": "founder_post",
                            "author": "Ada Lovelace",
                            "published_at": "2026-08-01"
                          }
                        }
                      }
                    ],
                    "alternatives": [
                      {
                        "name": "Other Example",
                        "slug": "other-example"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "No published startup has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "No published startup has that slug."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Carries `retry-after: 60`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/taxonomy": {
      "get": {
        "summary": "The slug vocabularies used for filtering",
        "description": "Call this before filtering rather than guessing a slug. Only terms a published startup uses are listed.",
        "responses": {
          "200": {
            "description": "Categories, models, stacks and bands.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Taxonomy"
                    }
                  }
                },
                "example": {
                  "data": {
                    "categories": [
                      {
                        "name": "Developer tools",
                        "slug": "developer-tools"
                      }
                    ],
                    "business_models": [
                      {
                        "name": "SaaS",
                        "slug": "saas"
                      }
                    ],
                    "technologies": [
                      {
                        "name": "TypeScript",
                        "slug": "typescript"
                      }
                    ],
                    "funding_types": [
                      "bootstrapped"
                    ],
                    "team_sizes": [
                      {
                        "slug": "solo",
                        "label": "Solo founder"
                      }
                    ],
                    "revenue_bands": [
                      {
                        "slug": "10k_50k",
                        "label": "$10k–$50k / mo",
                        "min_monthly_usd": 10000,
                        "max_monthly_usd": 50000
                      }
                    ],
                    "sorts": [
                      "newest",
                      "likes",
                      "revenue",
                      "name"
                    ],
                    "all_funding_types": [
                      "bootstrapped",
                      "angel",
                      "venture",
                      "other"
                    ],
                    "metric_types": [
                      {
                        "slug": "mrr",
                        "label": "MRR"
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Carries `retry-after: 60`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/milestones": {
      "get": {
        "summary": "Figures founders posted themselves, newest first",
        "description": "Each was posted from a profile its founder claimed, and read by a person before it appeared. Takes `page` and `limit` only — the startup filters do not apply here.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Rows per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of milestones.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Milestone"
                      }
                    },
                    "page": {
                      "$ref": "#/components/schemas/Page"
                    },
                    "links": {
                      "$ref": "#/components/schemas/Links"
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "note": "Crossed 12k MRR.",
                      "published_at": "2026-08-03T08:00:00.000Z",
                      "startup": {
                        "name": "Example",
                        "slug": "example",
                        "url": "https://ponicorn.com/startups/example"
                      },
                      "metric": {
                        "metric": "mrr",
                        "value": 12000,
                        "value_text": null,
                        "currency": "USD",
                        "measured_at": "2026-08-01",
                        "period_type": "monthly",
                        "evidence_status": "reported",
                        "verified_via": null,
                        "connected_via": "stripe",
                        "confidence": "high",
                        "label": "verified",
                        "is_current": true,
                        "verified_at": "2026-08-03",
                        "disputed": false,
                        "note": null,
                        "source": {
                          "url": "https://example.com/six-months-in",
                          "title": "Six months in",
                          "publisher": "Example Blog",
                          "source_type": "founder_post",
                          "author": "Ada Lovelace",
                          "published_at": "2026-08-01"
                        }
                      }
                    }
                  ],
                  "page": {
                    "number": 1,
                    "size": 25,
                    "total": 41,
                    "pages": 2
                  },
                  "links": {
                    "self": "https://ponicorn.com/api/v1/milestones?page=1",
                    "next": "https://ponicorn.com/api/v1/milestones?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "A `page` or `limit` that is not a number.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "bad_request",
                    "message": "page must be a positive whole number.",
                    "details": {
                      "page": "page must be a positive whole number."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Carries `retry-after: 60`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests. Try again in a minute."
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}