{ "openapi": "3.1.0", "info": { "title": "Tallow Index API", "version": "1.1.0", "description": "Read-only, release-bound beef tallow skincare facts with criterion-level evidence, stable evidence receipts, and public release-change feeds." }, "servers": [ { "url": "https://tallowindex.com", "description": "Production" }, { "url": "http://localhost:8787", "description": "Local preview" } ], "paths": { "/api/v1/source-use-register": { "get": { "operationId": "getSourceUseRegister", "summary": "Read source roles, intended uses, and unresolved rights-review states", "responses": { "200": { "description": "Machine-readable source-use and rights-review register" }, "429": { "description": "API request budget exceeded" } } } }, "/api/v1/agent/query": { "get": { "operationId": "queryTallowIndex", "summary": "Query exact product variants with evidence-aware filters", "parameters": [ { "name": "brand", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "variant", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "required_ingredient", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "excluded_ingredient", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "fragrance_free", "in": "query", "schema": { "type": "boolean" } }, { "name": "essential_oil_free", "in": "query", "deprecated": true, "description": "Legacy name. Prefer no_named_essential_oil_listed.", "schema": { "type": "boolean" } }, { "name": "no_named_essential_oil_listed", "in": "query", "description": "Released evidence names no essential oil. This does not prove the complete formulation.", "schema": { "type": "boolean" } }, { "name": "grass_fed_claim", "in": "query", "schema": { "type": "boolean" } }, { "name": "max_ingredients", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 500 } }, { "name": "min_size_oz", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_size_oz", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "max_price_per_oz", "in": "query", "schema": { "type": "number", "minimum": 0 } }, { "name": "currency", "in": "query", "description": "Required with max_price or max_price_per_oz. Rejected when neither price filter is present.", "schema": { "type": "string", "enum": ["USD", "CAD", "AUD", "NZD", "GBP", "EUR"] } }, { "name": "availability", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": ["in_stock", "out_of_stock", "preorder", "unknown"] } }, "style": "form", "explode": true }, { "name": "evidence_state", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": ["verified", "corroborated", "single_source", "conflicted", "stale", "unknown", "rejected"] } }, "style": "form", "explode": true }, { "name": "checked_after", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "include_unknown", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "include_conflicted", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "explain", "in": "query", "schema": { "type": "string", "enum": ["matches", "all"], "default": "matches" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "A deterministic query result bound to one current release. The response includes a versioned Claim Ledger, evidence frontier, reasoning hash, and per-variant proof hashes.", "content": { "application/json": { "schema": { "type": "object", "required": ["contract_version", "release", "claim_ledger", "results"], "properties": { "contract_version": { "const": "agent-query/1" }, "claim_ledger": { "type": "object", "required": ["reasoning_version", "resolution_state", "evidence_frontier", "reasoning_hash"], "properties": { "reasoning_version": { "const": "claim-ledger/1" }, "resolution_state": { "type": "string", "enum": ["decided", "partial", "blocked"] }, "evidence_frontier": { "type": "array", "items": { "type": "object" } }, "reasoning_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "reasoning": { "type": "object", "description": "Inspectable conclusion with decisive criteria, blocking unknowns, counter-signals, needed evidence, and a stable proof hash." } } } } } } } } }, "422": { "description": "The strict query contract rejected a field or value", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "API request budget exceeded" } } } }, "/api/v1/products": { "get": { "operationId": "listTallowProducts", "summary": "List current exact product variants", "parameters": [{ "name": "q", "in": "query", "required": false, "description": "Catalog text search across product, brand, and exact variant names", "schema": { "type": "string" } }], "responses": { "200": { "description": "Current released variants" }, "422": { "description": "Unsupported catalog filter. Use the evidence-aware agent query for evidence and price filters." } } } }, "/api/v1/brands": { "get": { "operationId": "listTallowBrands", "summary": "Discover current brand display names and canonical query slugs", "responses": { "200": { "description": "Current brand index with name, slug, and released variant count" } } } }, "/api/v1/products/{variantSlug}": { "get": { "operationId": "getTallowProduct", "summary": "Read one exact variant with assertions and sources", "parameters": [{ "name": "variantSlug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Exact variant evidence record" }, "404": { "description": "Variant not found" } } } }, "/api/v1/releases/{releaseId}/evidence/{variantSlug}": { "get": { "operationId": "getTallowEvidenceReceipt", "summary": "Read one immutable, hash-bound exact-variant evidence receipt", "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "variantSlug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canonical JSON receipt with a release manifest hash, receipt hash, field evidence, source locators, checked dates, and snapshot hashes" }, "404": { "description": "Released receipt not found" }, "429": { "description": "API request budget exceeded" } } } }, "/feeds/releases.json": { "get": { "operationId": "getTallowReleaseJsonFeed", "summary": "Read approved public release changes as JSON Feed 1.1", "responses": { "200": { "description": "Public releases with manifest hashes and added, changed, and removed exact-variant IDs" } } } }, "/feeds/releases.xml": { "get": { "operationId": "getTallowReleaseRssFeed", "summary": "Read the same approved public release changes as RSS 2.0", "responses": { "200": { "description": "RSS representation of the public release-change feed" } } } }, "/api/v1/ingredients": { "get": { "operationId": "listTallowIngredients", "summary": "List reviewed canonical ingredient records", "responses": { "200": { "description": "Current ingredient knowledge release" } } } }, "/api/v1/ingredients/{ingredientSlug}": { "get": { "operationId": "getTallowIngredient", "summary": "Read one canonical ingredient record with sourced identity, listed functions, current-release occurrences, and a Claim Ledger", "parameters": [{ "name": "ingredientSlug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Canonical ingredient evidence record using ingredient-record/2, including reference_profile and claim_ledger" }, "404": { "description": "Ingredient record not found" } } } }, "/api/v1/label-ingredients": { "get": { "operationId": "listLabelIngredients", "summary": "List every supported ingredient name in the current product release", "responses": { "200": { "description": "Complete label ingredient index with occurrence counts, positions, evidence state, and stable record URLs" } } } }, "/api/v1/label-ingredients/{ingredientSlug}": { "get": { "operationId": "getLabelIngredient", "summary": "Read one release-bound label occurrence ledger", "parameters": [{ "name": "ingredientSlug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Exact label wording, listed positions, products, evidence receipts, and explicit inference limits" }, "404": { "description": "Label ingredient not found" } } } }, "/api/v1/ingredient-comparisons/{comparisonSlug}": { "get": { "operationId": "getIngredientComparison", "summary": "Read one curated comparison of label and occurrence facts", "parameters": [{ "name": "comparisonSlug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Curated ingredient comparison" }, "404": { "description": "Comparison not found" } } } }, "/api/v1/notes": { "get": { "operationId": "listLivingEvidenceNotes", "summary": "List configured questions and their current release-bound answers", "responses": { "200": { "description": "Current Living Evidence Note index with result hashes" } } } }, "/api/v1/notes/{noteSlug}": { "get": { "operationId": "getLivingEvidenceNote", "summary": "Read one deterministic current-release answer with evidence links and a result hash", "parameters": [{ "name": "noteSlug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Current Living Evidence Note answer" }, "404": { "description": "Note not found" } } } } } }