{
  "openapi": "3.1.0",
  "info": {
    "title": "MyBearings API (proposed contract)",
    "version": "0.1-draft",
    "description": "PROPOSED CONTRACT. No server implements this yet. Published for review; breaking changes are expected before v1."
  },
  "servers": [{ "url": "https://api.mybearings.world", "description": "Reserved. Not live." }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "Search public products",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Designation or text query" },
          { "name": "manufacturer", "in": "query", "schema": { "type": "string" } },
          { "name": "family", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Page of product summaries with next_cursor" }, "400": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/products/{id}": {
      "get": {
        "summary": "Get a versioned product record with attributes, evidence, missing fields and relationships",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Bearing record (schema 0.1-draft)" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/schemas/{family}": {
      "get": {
        "summary": "Get a family schema release with applicability rules",
        "parameters": [{ "name": "family", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Family schema" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/resolve": {
      "post": {
        "summary": "Resolve identifiers to exact or candidate products with explanations",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "properties": { "items": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "ref": { "type": "string" }, "manufacturer": { "type": "string" }, "designation": { "type": "string" }, "description": { "type": "string" }, "attributes": { "type": "object" } } } } } } } } },
        "responses": { "200": { "description": "Per item: status (exact_candidate | variant_discrepancy | multiple_candidates | insufficient_evidence), candidates, explanation" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/catalog-audits": {
      "post": {
        "summary": "Create an authorized private audit job",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "responses": { "202": { "description": "Job accepted; poll /v1/jobs/{id}" } }
      }
    },
    "/v1/enrichment-jobs": {
      "post": {
        "summary": "Start a scoped enrichment job with explicit source permissions",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }],
        "responses": { "202": { "description": "Job accepted" } }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "summary": "Job status, counters, errors and result access for the authorized tenant",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Job" }, "404": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/suppliers": {
      "get": {
        "summary": "Source-backed supplier identities and relationships (when available)",
        "responses": { "200": { "description": "Page of suppliers" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } },
    "responses": {
      "Error": {
        "description": "Error",
        "content": { "application/json": { "schema": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }
      }
    }
  }
}