{
  "openapi": "3.1.0",
  "info": {
    "title": "openproduct catalog",
    "version": "1.5.0",
    "description": "Products built in the open, as a machine-readable catalog. Every field a human reads carries its provenance: whether a person wrote it, something measured it, or we computed it — and for the last two, when. Anonymous, edge-cached for 60 seconds, and no credential is accepted on any route here. Additive forever. A field, once published, stays. A removal is announced on this page with a date at least 90 days out, carries a Deprecation header for the whole notice period, and is marked x-deprecated in the OpenAPI document until it goes. There is no 2.0.0: a breaking change is a new path beside the old one, and the old one keeps answering for the notice period. Rate limited, and the limit is published: 120 requests a minute per address on the public read (`anon`); 60 requests a minute per subject on the signed-in plane (`identity`); 300 requests a minute per organisation on an organisation's maintainer routes (`org`). Each bucket refills continuously. A refused request answers 429 with a Retry-After header computed from the refill and a body naming the bucket. The count is one per key rather than one per data centre, so the number here is the number enforced.",
    "x-rate-limits": {
      "anon": {
        "limit": 120,
        "windowSec": 60,
        "keyedBy": "address",
        "guards": "the public read"
      },
      "identity": {
        "limit": 60,
        "windowSec": 60,
        "keyedBy": "subject",
        "guards": "the signed-in plane"
      },
      "org": {
        "limit": 300,
        "windowSec": 60,
        "keyedBy": "organisation",
        "guards": "an organisation's maintainer routes"
      }
    }
  },
  "externalDocs": {
    "url": "https://openproduct.live/docs/api",
    "description": "The changelog and the stability policy"
  },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "The catalog, one page at a time",
        "description": "Every published listing, in the published order (sort.most-active), cut into pages. `next` is on every page: a cursor for the page after this one, or null on the last. A cursor is opaque — a position in the ordering, issued by this API — and lives in a URL. No credential is accepted; the response is identical for every caller, which is what makes it cacheable.",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The `next` of the previous page. Absent for the first page. A cursor this API did not issue is refused (422)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            },
            "description": "Rows on the page. Bounded; a larger number is served as the maximum."
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "products",
                        "next",
                        "total",
                        "computedAt"
                      ],
                      "properties": {
                        "products": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CatalogCard"
                          }
                        },
                        "next": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The cursor for the page after this one; null on the last page, never absent."
                        },
                        "total": {
                          "type": "integer",
                          "description": "Every published listing, counted — a number about the catalog, not about the page."
                        },
                        "computedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "When the catalogue these cards came from was computed (OS5). The sweep materialises it every ten minutes; null while a page is served from the live join, before the first sweep."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "A cursor this API did not issue"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/products/{slug}": {
      "get": {
        "summary": "One product",
        "description": "Unknown, unpublished and unreachable all answer 404 — deliberately indistinguishable, so this endpoint cannot be used to discover drafts.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The product"
          },
          "404": {
            "description": "No published listing at this address"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/facets": {
      "get": {
        "summary": "The facet taxonomy",
        "description": "The vocabulary the catalog is filterable by, so a client can build its own navigation rather than hard-coding ours.",
        "responses": {
          "200": {
            "description": "The taxonomy"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/media/{ref}": {
      "get": {
        "summary": "A media asset, by reference",
        "description": "The bytes a listing's `media[].value.ref` names: 64 hex characters of SHA-256, a dot, and png, jpg or webp. Content-addressed, so the answer is immutable and carries `cache-control: public, max-age=31536000, immutable` — cache it for a year. Derivatives are at `/v1/media/{hash}/w{400|800|1600}.webp`, exist only at widths below the original's, and where one was not generated the original is served at that address rather than a 404. Served with `x-content-type-options: nosniff` and the type the upload was sniffed as, never the type the uploader claimed.",
        "responses": {
          "200": {
            "description": "The asset"
          },
          "404": {
            "description": "No such reference"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": {
        "description": "Too many requests from this caller. Retry-After is whole seconds until the bucket holds a token for you — computed from its refill, not a flat window — and the body names which bucket refused and what it allows.",
        "headers": {
          "Retry-After": {
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Seconds until the next request is yours."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "required": [
                    "code",
                    "message",
                    "details",
                    "requestId"
                  ],
                  "properties": {
                    "code": {
                      "type": "string",
                      "enum": [
                        "rate_limited"
                      ]
                    },
                    "message": {
                      "type": "string"
                    },
                    "requestId": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "required": [
                        "bucket",
                        "limit",
                        "windowSec",
                        "retryAfterSeconds"
                      ],
                      "properties": {
                        "bucket": {
                          "type": "string",
                          "enum": [
                            "anon",
                            "identity",
                            "org"
                          ]
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "windowSec": {
                          "type": "integer"
                        },
                        "retryAfterSeconds": {
                          "type": "integer",
                          "minimum": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Fact": {
        "type": "object",
        "required": [
          "value",
          "provenance"
        ],
        "description": "A value and where it came from. Every field a human reads is wrapped: a catalog that hands out numbers without saying where they came from is a catalog of assertions.",
        "properties": {
          "value": {
            "description": "The value itself; type varies by field."
          },
          "provenance": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "class",
                  "by"
                ],
                "properties": {
                  "class": {
                    "type": "string",
                    "enum": [
                      "authored"
                    ]
                  },
                  "by": {
                    "type": "string",
                    "enum": [
                      "maintainer",
                      "contributor"
                    ]
                  }
                },
                "description": "A person wrote it, and it is visibly in their voice."
              },
              {
                "type": "object",
                "required": [
                  "class",
                  "source",
                  "observedAt"
                ],
                "properties": {
                  "class": {
                    "type": "string",
                    "enum": [
                      "observed"
                    ]
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "linked_repo",
                      "declared_repo",
                      "manifest",
                      "operator",
                      "declared_url"
                    ]
                  },
                  "observedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When this was true. Required: a measurement without a moment is not a measurement."
                  }
                },
                "description": "Something measured it, at a stated time."
              },
              {
                "type": "object",
                "required": [
                  "class",
                  "formula",
                  "inputs",
                  "computedAt"
                ],
                "properties": {
                  "class": {
                    "type": "string",
                    "enum": [
                      "derived"
                    ]
                  },
                  "formula": {
                    "type": "string",
                    "enum": [
                      "repo.licence",
                      "repo.language",
                      "repo.last-commit",
                      "repo.open-issues",
                      "activity.merges.7d",
                      "activity.merges.30d",
                      "sort.most-active",
                      "catalog.front-page-floor",
                      "sort.most-saved",
                      "sort.newest",
                      "sort.roles",
                      "alternatives.overlap",
                      "similar.same-category-then-active",
                      "votes.clean",
                      "integrity.discount",
                      "endorsements.total",
                      "endorsements.7d",
                      "digest.most-endorsed",
                      "facet.count",
                      "openings.open",
                      "followers.count",
                      "people.roster",
                      "team.size-bucket",
                      "contributor.maintains",
                      "contributor.contributes-to",
                      "contributor.since",
                      "contributor.reviews.12mo",
                      "listing.indexable",
                      "search.relevance",
                      "launch.board-rank",
                      "launch.leaderboard",
                      "topic.recent-launches",
                      "collection.newest",
                      "openings.newest",
                      "people.open-to-project",
                      "maker.launched",
                      "threads.recently-replied",
                      "threads.latest",
                      "threads.most-replied",
                      "maker.upvoted",
                      "maker.comments",
                      "maker.first-launch",
                      "maker.history",
                      "contributor.followers",
                      "comment.votes",
                      "product.stage",
                      "product.milestones-shipped",
                      "product.crew-count"
                    ],
                    "description": "Resolves to a published sentence at /docs/formulas."
                  },
                  "inputs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "computedAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "description": "We computed it, from a published formula."
              }
            ]
          }
        }
      },
      "CatalogCard": {
        "type": "object",
        "required": [
          "category",
          "crewCount",
          "hasLiveUrl",
          "hosting",
          "indexable",
          "language",
          "lastCommitAt",
          "licence",
          "media",
          "metrics",
          "milestoneCounts",
          "openIssues",
          "openRoles",
          "openingCommitments",
          "pricing",
          "publishedAt",
          "slug",
          "stack",
          "stackCanonical",
          "stage",
          "tagline"
        ],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/Fact"
          },
          "crewCount": {
            "$ref": "#/components/schemas/Fact",
            "description": "How many people the product's page lists as its crew: its published maintainers, counted (`product.crew-count`). `null` while the catalogue row predates the count — never a zero nobody counted. Not an ordering input."
          },
          "hasLiveUrl": {
            "$ref": "#/components/schemas/Fact"
          },
          "hosting": {
            "$ref": "#/components/schemas/Fact"
          },
          "indexable": {
            "$ref": "#/components/schemas/Fact"
          },
          "language": {
            "$ref": "#/components/schemas/Fact"
          },
          "lastCommitAt": {
            "$ref": "#/components/schemas/Fact"
          },
          "licence": {
            "$ref": "#/components/schemas/Fact"
          },
          "media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fact"
            },
            "description": "The listing's media, in document order: the hero, then the gallery in the maker's order, then the automated capture. Each row carries its OWN provenance — a hero and a gallery image are authored by the maker and never go stale; a capture is observed, carries the moment it was taken, and is withdrawn past its window rather than presented as current. An empty list means the listing published no images, not that a picture was taken and found nothing."
          },
          "metrics": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Fact"
            },
            "description": "Observed metrics by name. A metric is ABSENT — never zero — when this listing's tier cannot see it, or when the last reading has gone stale past its window."
          },
          "milestoneCounts": {
            "$ref": "#/components/schemas/Fact",
            "description": "`{shipped, total}`: how many of the product's milestones are marked shipped, and how many it has. Derived from `milestones` (`product.milestones-shipped`)."
          },
          "openIssues": {
            "$ref": "#/components/schemas/Fact"
          },
          "openRoles": {
            "$ref": "#/components/schemas/Fact"
          },
          "openingCommitments": {
            "$ref": "#/components/schemas/Fact"
          },
          "pricing": {
            "$ref": "#/components/schemas/Fact"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "description": "The listing's public address segment."
          },
          "stack": {
            "$ref": "#/components/schemas/Fact"
          },
          "stackCanonical": {
            "$ref": "#/components/schemas/Fact"
          },
          "stage": {
            "$ref": "#/components/schemas/Fact",
            "description": "Where the product is: `idea`, `building` (code and a first milestone), `stage` (people can try it) or `production` (real people use it). ALWAYS `authored` since SC1 — the crew sets it by hand, one step at a time, and each step asks for its own inputs; milestones no longer move it. Before SC1 this was derived from the milestones as `idea` or `shipping`; every `shipping` product became `stage` when it had a try link and `building` when it did not. Not an ordering input."
          },
          "tagline": {
            "$ref": "#/components/schemas/Fact"
          }
        }
      },
      "CatalogProduct": {
        "type": "object",
        "required": [
          "category",
          "changes",
          "cleanVotes",
          "components",
          "crewCount",
          "followers",
          "hasLiveUrl",
          "hosting",
          "indexable",
          "installLine",
          "language",
          "lastCommitAt",
          "launch",
          "launches",
          "licence",
          "liveUrl",
          "maintainers",
          "media",
          "metrics",
          "milestoneCounts",
          "milestones",
          "openIssues",
          "openRoles",
          "openingCommitments",
          "openings",
          "pitch",
          "pitchDigest",
          "pricing",
          "publishedAt",
          "repoUrl",
          "slug",
          "stack",
          "stackCanonical",
          "stage",
          "tagline",
          "tryUrl",
          "whereItRuns",
          "workspaceRef"
        ],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/Fact"
          },
          "changes": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object"
            },
            "description": "What changed on this listing in the last week, oldest snapshot to newest. Each entry carries its OWN provenance: a maintainer's edit is `authored` and carries NO moment — we know it happened between two daily snapshots and a timestamp would be inventing precision — while a licence or language change is `observed` and carries the moment of the read that found it. `null` means there is no earlier snapshot to compare against and NOT that nothing changed; `[]` means we compared and nothing moved. Nothing here is an ordering input and no formula id names one: \"recently updated\" rewards touching a listing rather than improving a product."
          },
          "cleanVotes": {
            "$ref": "#/components/schemas/Fact",
            "description": "Whether this listing's upvotes were checked by the integrity model and almost none discounted: at least 10 counted upvotes and no more than 5% of everything cast set aside. A BOOLEAN AND NEVER A COUNT — no per-listing suppression figure is published anywhere. `false` IS NOT A FINDING: it covers both a listing with too few upvotes to check, which is most of them, and one that did not clear the bar, and nothing distinguishes the two. It orders nothing; the catalog's own orderings read the discounted total, which already reflects the same check."
          },
          "components": {
            "$ref": "#/components/schemas/Fact"
          },
          "crewCount": {
            "$ref": "#/components/schemas/Fact",
            "description": "How many people the product's page lists as its crew: its published maintainers, counted (`product.crew-count`). `null` while the catalogue row predates the count — never a zero nobody counted. Not an ordering input."
          },
          "followers": {
            "$ref": "#/components/schemas/Fact"
          },
          "hasLiveUrl": {
            "$ref": "#/components/schemas/Fact"
          },
          "hosting": {
            "$ref": "#/components/schemas/Fact"
          },
          "indexable": {
            "$ref": "#/components/schemas/Fact"
          },
          "installLine": {
            "$ref": "#/components/schemas/Fact",
            "description": "One copyable install command, in the maintainer's own words. ALWAYS `authored` — this catalog never derives an install line, and a client should treat the provenance as load-bearing rather than decorative: nobody measured this and nothing has run it. It is one command by construction; pipes, chaining, substitution and redirection are refused at the column and in the contract, so a consumer does not receive a script. `null` means the listing has no install line, not that one could not be worked out."
          },
          "language": {
            "$ref": "#/components/schemas/Fact"
          },
          "lastCommitAt": {
            "$ref": "#/components/schemas/Fact"
          },
          "launch": {
            "$ref": "#/components/schemas/Fact"
          },
          "launches": {
            "$ref": "#/components/schemas/Fact"
          },
          "licence": {
            "$ref": "#/components/schemas/Fact"
          },
          "liveUrl": {
            "$ref": "#/components/schemas/Fact"
          },
          "maintainers": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "media": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Fact"
            },
            "description": "The listing's media, in document order: the hero, then the gallery in the maker's order, then the automated capture. Each row carries its OWN provenance — a hero and a gallery image are authored by the maker and never go stale; a capture is observed, carries the moment it was taken, and is withdrawn past its window rather than presented as current. An empty list means the listing published no images, not that a picture was taken and found nothing."
          },
          "metrics": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Fact"
            },
            "description": "Observed metrics by name. A metric is ABSENT — never zero — when this listing's tier cannot see it, or when the last reading has gone stale past its window."
          },
          "milestoneCounts": {
            "$ref": "#/components/schemas/Fact",
            "description": "`{shipped, total}`: how many of the product's milestones are marked shipped, and how many it has. Derived from `milestones` (`product.milestones-shipped`)."
          },
          "milestones": {
            "$ref": "#/components/schemas/Fact",
            "description": "The product's milestones in the crew's order, as one authored list: each entry is `{code, title, summary, shippedAt}`, where `code` is the crew's own short label and `shippedAt` is the moment the crew marked it shipped — `null` until they have. An empty list means the crew has written none."
          },
          "openIssues": {
            "$ref": "#/components/schemas/Fact"
          },
          "openRoles": {
            "$ref": "#/components/schemas/Fact"
          },
          "openingCommitments": {
            "$ref": "#/components/schemas/Fact"
          },
          "openings": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "pitch": {
            "$ref": "#/components/schemas/Fact"
          },
          "pitchDigest": {
            "type": "string",
            "nullable": true,
            "description": "sha256:<hex> of the pitch as published — a cache key, and a receipt."
          },
          "pricing": {
            "$ref": "#/components/schemas/Fact"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "repoUrl": {
            "$ref": "#/components/schemas/Fact"
          },
          "slug": {
            "type": "string",
            "description": "The listing's public address segment."
          },
          "stack": {
            "$ref": "#/components/schemas/Fact"
          },
          "stackCanonical": {
            "$ref": "#/components/schemas/Fact"
          },
          "stage": {
            "$ref": "#/components/schemas/Fact",
            "description": "Where the product is: `idea`, `building` (code and a first milestone), `stage` (people can try it) or `production` (real people use it). ALWAYS `authored` since SC1 — the crew sets it by hand, one step at a time, and each step asks for its own inputs; milestones no longer move it. Before SC1 this was derived from the milestones as `idea` or `shipping`; every `shipping` product became `stage` when it had a try link and `building` when it did not. Not an ordering input."
          },
          "tagline": {
            "$ref": "#/components/schemas/Fact"
          },
          "tryUrl": {
            "$ref": "#/components/schemas/Fact",
            "description": "The address of the running product, as the crew declared it. ALWAYS `authored` — nothing here has checked that the address answers. `null` means the crew gave none."
          },
          "whereItRuns": {
            "$ref": "#/components/schemas/Fact",
            "description": "Where the product runs: `{stage, production}`. `stage` is `{url, note, version, source, setBy, at}` while the product is on stage or in production and has a stage link, else `null`; `production` is `{url, since, version, access, source, setBy, at}` while it is in production, else `null`. Each link, version and `since` is the crew's own value, else the one its last Orunbase deploy reported (SC3); `source` says which per field (`crew` or `synced`; a crew value equal to the synced one is `synced`), and the stage `version` is always the stage deploy's. `since` is a `YYYY-MM-DD` day, `access` is `everyone`, `waitlist` or `invite`. `setBy` is `{kind: \"crew\", name, handle}` — name and handle `null` for a crew member who is not on the public roster — `{kind: \"orun\", name: null, handle: null}` when the row's link is the synced one (then `at` is the deploy's moment), or `null` when nobody is recorded. ALWAYS `authored`: nothing here has checked that an address answers."
          },
          "workspaceRef": {
            "type": "string",
            "nullable": true,
            "description": "The console address (org_…) of the public workspace the maintainers attested with their link grant; null while the listing holds none. Open it at the console's /view/{workspaceRef}."
          }
        }
      },
      "FacetGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "category",
              "stack",
              "licence",
              "openings",
              "activity",
              "team_size",
              "hosting",
              "pricing"
            ]
          },
          "label": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "assigned",
              "derived"
            ]
          },
          "cardinality": {
            "type": "string",
            "enum": [
              "single",
              "multi"
            ]
          },
          "description": {
            "type": "string"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}