{"openapi":"3.1.0","info":{"title":"Bergsonne Labs HTTP API","summary":"Composable, millimeter-scale Tiles — embedded intelligence for physical AI. Fully-encapsulated modules, plus the Studio IDE that composes them.","description":"A read-only API over the tile catalog, the driver reference, and the lookup tables.\n\nEverything here is public: no authentication, CORS open to any origin, and responses\ncached at the edge. Results reflect the **public tier** only — tiles that are not yet\npublicly available return 404, exactly as they do in the catalog.\n\nTiles are identified as `Family.Name` (for example `Sense.BP`), optionally pinned to a\nrevision as `Family.Name@rev`. That identifier is stable across the catalog, the driver\nreference, Studio and the datasheets.\n\nEvery tile and driver response carries a `links` object pointing at its other\nrepresentations — HTML page, markdown twin, driver reference, PDF datasheet — so a\nclient never has to construct URLs.\n\nPrefer `/llms.txt` for a map of the whole site, or `/llms-full.txt` for the entire\ngenerated documentation corpus in one request.","version":"1.0.0","contact":{"name":"Bergsonne Labs","url":"https://bergsonne.io"}},"servers":[{"url":"https://bergsonne.io"}],"tags":[{"name":"Tiles","description":"The tile catalog — what exists, and each tile’s definition."},{"name":"Drivers","description":"Tile driver reference, including the capabilities each driver does NOT expose."},{"name":"Reference","description":"Lookup tables: I²C addresses and pad assignments."},{"name":"Commons","description":"Compositions shared by their authors — real designs showing which tiles get used together and how they are wired."},{"name":"Search","description":"Site-wide search."}],"paths":{"/api/tiles":{"get":{"operationId":"tiles","summary":"List publicly available tiles","description":"Every tile visible to the public tier, with package, interfaces, primary part, and links to its other representations. Filters combine with AND.","tags":["Tiles"],"parameters":[{"name":"family","in":"query","required":false,"description":"Exact family, case-insensitive.","schema":{"type":"string","examples":["Sense"]}},{"name":"interface","in":"query","required":false,"description":"Tile exposes this interface.","schema":{"type":"string","examples":["I2C"]}},{"name":"package","in":"query","required":false,"description":"Package type.","schema":{"type":"string","examples":["T44"]}},{"name":"q","in":"query","required":false,"description":"Substring match over id, headline and primary part.","schema":{"type":"string","examples":["pressure"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TileList"}}}}}}},"/api/tiles/{id}":{"get":{"operationId":"tiles_id","summary":"Get one tile","description":"A single tile with its full definition. `Family.Name` resolves the newest publicly visible revision; `Family.Name@rev` pins one.\n\n**Note:** A tile that is not publicly visible returns 404, exactly as the catalog does. This API is not a side door around tier gating.\n\n**Note:** The digital-twin simulator source and internal database ids are withheld; `twin.score` and `twin.status` are returned instead.","tags":["Tiles"],"parameters":[{"name":"id","in":"path","required":true,"description":"Tile identifier: `Family.Name` or `Family.Name@rev`.","schema":{"type":"string","examples":["Sense.TOF"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TileResponse"}}}},"400":{"description":"Malformed request — usually a tile identifier that is not `Family.Name`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it is not visible to the public tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/drivers":{"get":{"operationId":"drivers","summary":"List tile drivers","description":"Every documented driver with its API size and its count of declared capability gaps.","tags":["Drivers"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverList"}}}}}}},"/api/drivers/{tile}":{"get":{"operationId":"drivers_tile","summary":"Get one driver reference","description":"The parsed driver header: every public function with signature, parameters and return, plus enums, structs, defines, and the declared gaps.\n\n**Note:** `driver.studio_unsupported` lists chip capabilities this driver does NOT expose, tagged hardware-gated or driver-deferred. Prefer it over inferring an API from the chip datasheet.","tags":["Drivers"],"parameters":[{"name":"tile","in":"path","required":true,"description":"Tile identifier, e.g. `Sense.BP`.","schema":{"type":"string","examples":["Sense.BP"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"400":{"description":"Malformed request — usually a tile identifier that is not `Family.Name`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, or it is not visible to the public tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reference/{table}":{"get":{"operationId":"reference_table","summary":"Get a reference lookup table","description":"Generated from the canonical tile definitions. `i2c` returns default and alternate addresses; `pads` returns each pad’s default function and alternates.\n\n**Note:** Tier-gated and fail-closed: if tile visibility cannot be determined the table is withheld with 503 rather than over-published.","tags":["Reference"],"parameters":[{"name":"table","in":"path","required":true,"description":"Either `i2c` or `pads`.","schema":{"type":"string","examples":["i2c"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceResponse"}}}},"404":{"description":"No such resource, or it is not visible to the public tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A dependency was unavailable. This API fails closed rather than returning partial data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/commons":{"get":{"operationId":"commons","summary":"List shared compositions","description":"Projects whose authors set their visibility to `commons`. Each carries the tiles used (with per-tile configuration and behaviour), and the netlist connecting them.\n\n**Note:** Only projects explicitly shared as `commons` appear. Private and internal projects are never published.\n\n**Note:** Author identity, originating prompts, and model-generated design narrative are withheld — sharing a composition is not the same as sharing who made it or what they asked for.","tags":["Commons"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommonsList"}}}}}}},"/api/search":{"get":{"operationId":"search","summary":"Search the site","description":"Tiles, drivers, driver functions, SDK symbols, documentation pages and reference lookups. Exact symbol matches rank first.\n\n**Note:** Results depend on the caller’s tier, so this endpoint is never shared-cacheable.","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Query string. Fewer than two characters returns an empty list.","schema":{"type":"string","examples":["core_i2c_write"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","not_found","unavailable"]},"message":{"type":"string"},"hint":{"type":"string","description":"Human-facing suggestion. Branch on `code`."}}}}},"Provenance":{"type":"object","properties":{"generated":{"type":"string","format":"date-time"},"driverManifests":{"type":"string","description":"The `tiles@<sha>` the driver manifests were generated from.","examples":["tiles@842d43e"]}}},"TileLinks":{"type":"object","required":["page","markdown"],"description":"Every representation of this tile, so callers never build URLs.","properties":{"page":{"type":"string","format":"uri","description":"Canonical HTML page."},"markdown":{"type":"string","format":"uri","description":"Markdown datasheet twin."},"driver":{"type":"string","format":"uri"},"driverMarkdown":{"type":"string","format":"uri"},"datasheet":{"type":"string","format":"uri","description":"Generated PDF datasheet."}}},"TileSummary":{"type":"object","required":["id","family","name","rev","interfaces","links"],"properties":{"id":{"type":"string","description":"`Family.Name` — the identifier used across the catalog, docs and Studio.","examples":["Sense.TOF"]},"family":{"type":"string","examples":["Sense"]},"name":{"type":"string","examples":["TOF"]},"rev":{"type":"string","examples":["a"]},"headline":{"type":"string"},"package":{"type":"object","properties":{"type":{"type":"string","examples":["T44"]},"pads":{"type":"integer"},"width_mm":{"type":"number","description":"Omitted when the definition has no value."},"depth_mm":{"type":"number"},"height_mm":{"type":"number"}}},"interfaces":{"type":"array","items":{"type":"string"},"examples":[["I2C"]]},"primaryPart":{"type":"string","examples":["TMF8806"]},"links":{"$ref":"#/components/schemas/TileLinks"}}},"TileDetail":{"allOf":[{"$ref":"#/components/schemas/TileSummary"},{"type":"object","properties":{"description":{"type":"string"},"twin":{"type":"object","description":"Digital-twin coverage. The simulator SOURCE is not published — it ships as a private package.","properties":{"score":{"type":"number"},"status":{"type":"string","examples":["validated"]}}},"definition":{"type":"object","description":"The canonical tile definition — package, power rails, pads, interfaces, components, application notes. Internal fields (`twin`, `tile_id`) are withheld."}}}]},"TileList":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["tiles","count"],"properties":{"tiles":{"type":"array","items":{"$ref":"#/components/schemas/TileSummary"}},"count":{"type":"integer"}}}]},"TileResponse":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["tile"],"properties":{"tile":{"$ref":"#/components/schemas/TileDetail"}}}]},"DriverSummary":{"type":"object","required":["tile","displayName","brief","version","functionCount","gapCount"],"properties":{"tile":{"type":"string","examples":["Sense.BP"]},"displayName":{"type":"string"},"brief":{"type":"string"},"version":{"type":"string","examples":["1.2.0"]},"functionCount":{"type":"integer"},"gapCount":{"type":"integer","description":"Chip capabilities this driver does NOT expose."},"studioReady":{"type":"boolean"},"links":{"type":"object","properties":{"page":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"},"tile":{"type":"string","format":"uri"}}}}},"DriverList":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["drivers","count"],"properties":{"drivers":{"type":"array","items":{"$ref":"#/components/schemas/DriverSummary"}},"count":{"type":"integer"}}}]},"DriverResponse":{"allOf":[{"$ref":"#/components/schemas/DriverSummary"},{"type":"object","properties":{"driver":{"type":"object","description":"The parsed driver header: `functions`, `enums`, `structs`, `defines`, `studio_events`, and `studio_unsupported` (the declared gaps)."}}}]},"ReferenceResponse":{"type":"object","required":["table","entries","count"],"properties":{"table":{"type":"string","enum":["i2c","pads"]},"entries":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"}}},"CommonsProject":{"type":"object","required":["id","name","tiles","nets"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Author-given project name."},"tiles":{"type":"array","items":{"type":"object","properties":{"tile":{"type":"string","examples":["Sense.TOF"]},"rev":{"type":"string"},"config":{"type":"object","description":"Per-tile configuration as saved."},"firmware":{"type":"object","description":"Behaviour DSL attached to this tile."}}}},"nets":{"type":"array","description":"The netlist — how the tiles are wired together.","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"role":{"type":"string"},"auto":{"type":"boolean","description":"True when auto-wiring produced this net."}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"links":{"type":"object","properties":{"studio":{"type":"string","format":"uri"}}}}},"CommonsList":{"type":"object","required":["projects","count"],"properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/CommonsProject"}},"count":{"type":"integer"}}},"SearchResults":{"type":"array","items":{"type":"object","required":["id","title","url","kind"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"kind":{"type":"string","enum":["Tile","Driver","Function","API","Reference","Doc","Event","Blog","Page"]},"snippet":{"type":"string"}}}}}}}