{
  "id": "p_aNkLz6fw_CEgM6Hx",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_aNkLz6fw_CEgM6Hx",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are about to let an agent run your A/B tests. It will start an experiment, check the results, and maybe conclude it. Before you hand over the keys, you open the OpenAPI contract for Statsig's Experiments API and start reading what the agent will read.\n\nThe API page on APIs.io shows 66 operations. That looks like a big, capable surface. It creates, starts, reviews and concludes A/B tests on Statsig's platform. But when you count, only 59 of those operations are distinct. Seven URLs appear twice.\n\nHere is how that happened. The contract is a merge of three of Statsig's published definitions, and each path carries the server of the definition it came from. One form, /experiments, sits on https://statsigapi.net/console/v1. The other, /console/v1/experiments, sits on https://statsigapi.net. Those two resolve to the same address. So the same URL shows up under two names, and the count doubles.\n\nYou might shrug at that. The listing, the get, the create, the patch and the delete are present on both forms and read the same. The two security schemes have different names, consoleApiKey on one and STATSIG-API-KEY on the other, but they send the same header, so that difference is cosmetic.\n\nThe start operation is where it stops being cosmetic. On the long path, PUT .../start requires a request body, an ExperimentStartDto. On the short path it requires none. One URL cannot both require a body and not require one. A generated client or an agent reading this document has to pick, and nothing in the document tells it which. The 200 responses disagree too: the start and reset operations return an Experiment object on one form and a message string on the other. Only the short paths declare the optional STATSIG-API-VERSION header, which defaults to 20240601.\n\nNow comes the part you did not expect. The post does not blame Statsig. The APIs.io catalog says the fix is its own: the merge should collapse paths that resolve to one URL and keep the richer definition. The catalog merged them that way, so the catalog owns the disagreement.\n\nWith the duplicates set aside, you see what Statsig built. Seven PUT verbs move an experiment through its life: start, reset, abandon, archive, unarchive, make_decision and defer_decision. restart_as_new is a POST. Eight operations cover change review, from creating a review through approve, reject and commit, so a change can wait for a person before it lands. Six more handle overrides. Pulse results accept statistical options as query parameters, including CUPED, confidence interval and Bonferroni corrections.\n\nYou look for retry safety next, because an agent will retry. The contract declares no idempotency header anywhere in the 66 operations. Two override deletes say in their descriptions that they are idempotent. For the state-changing verbs, you would have to find that answer in Statsig's documentation, not in this document.\n\nThen one operation stops you. POST /get_experiment lives on a different host, https://api.statsig.com/v1, and takes a different kind of key. It reads like a lookup. But its description says an exposure event is logged automatically. If your agent calls it just to inspect an experiment, it is also writing to that experiment's analysis.\n\nThe wider record gives you some context. Statsig scores 76.5, rated exemplar, on the Kin Score and 51.6 on Agent Readiness. Its agentic access record shows 384 operations, 234 of them acting and 33 flagged human-in-the-loop. The provider page lists 38 APIs, which the build split out of four source definitions, so this contract's merged shape comes from that split.\n\nWhat you take away is practical. Statsig published an experiment lifecycle that an agent can follow step by step, with a review gate built in. Treat get_experiment as a write, not a read. And until the catalog's merge is fixed, trust the /console/v1 form of the seven doubled operations, since it comes from the larger console definition.\n\nRead the original: https://apis.io/2026/11/06/statsig-experiments-api-lists-seven-urls-twice-and-the-contracts-disagree/",
  "title": "You Ask an Agent to Start a Statsig Experiment and Find the Contract Says Two Things",
  "topics": [
    "statsig",
    "openapi",
    "experimentation",
    "api-contracts"
  ],
  "published_at": "2026-11-06T19:21:04.803Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}