{
  "openapi": "3.1.0",
  "info": {
    "title": "Бонихуа Knowledge API",
    "description": "Read-only integration API for the Бонихуа supplier-message task journey, its source entities, and source-backed freshness metadata. It does not create messages, submit forms, or expose private user data.",
    "version": "1.0.0",
    "contact": {
      "email": "hello@bonihua.ru",
      "url": "https://www.bonihua.com"
    },
    "termsOfService": "https://www.bonihua.com/legal/terms/"
  },
  "servers": [
    {
      "url": "https://www.bonihua.com",
      "description": "Canonical production origin"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Supplier tasks",
      "description": "Structured, read-only supplier-message workflow resources."
    },
    {
      "name": "Source entities",
      "description": "Dataset entities explicitly referenced by supplier tasks."
    },
    {
      "name": "Freshness",
      "description": "Latest source-backed dataset lifecycle snapshot."
    },
    {
      "name": "Legacy discovery",
      "description": "Existing static discovery resources retained for compatibility."
    }
  ],
  "paths": {
    "/api/v1/tasks": {
      "get": {
        "tags": ["Supplier tasks"],
        "summary": "List supplier-message tasks and their graph",
        "operationId": "listSupplierMessageTasks",
        "parameters": [{ "$ref": "#/components/parameters/IfNoneMatch" }],
        "responses": {
          "200": {
            "description": "Task collection with graph relations and source metadata.",
            "headers": {
              "ETag": { "$ref": "#/components/headers/ETag" },
              "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
              "X-Bonihua-API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCollection" } } }
          },
          "304": { "$ref": "#/components/responses/NotModified" }
        }
      }
    },
    "/api/v1/tasks/{id}": {
      "get": {
        "tags": ["Supplier tasks"],
        "summary": "Get one supplier-message task by stable ID",
        "operationId": "getSupplierMessageTask",
        "parameters": [
          { "$ref": "#/components/parameters/TaskId" },
          { "$ref": "#/components/parameters/IfNoneMatch" }
        ],
        "responses": {
          "200": {
            "description": "Full task, graph relations, provenance, and canonical/source links.",
            "headers": {
              "ETag": { "$ref": "#/components/headers/ETag" },
              "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
              "X-Bonihua-API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResource" } } }
          },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/terms/{id}": {
      "get": {
        "tags": ["Source entities"],
        "summary": "Resolve a source entity referenced by supplier tasks",
        "description": "Returns only entities that are referenced by supplier-message sourceIds and resolve through the Бонихуа dataset registry. Despite the path name, a source entity can be a term, message template, communication pattern, mistake, vocabulary set, or industry use case.",
        "operationId": "getSupplierSourceEntity",
        "parameters": [
          { "$ref": "#/components/parameters/SourceId" },
          { "$ref": "#/components/parameters/IfNoneMatch" }
        ],
        "responses": {
          "200": {
            "description": "Resolved public source entity and the tasks that cite it.",
            "headers": {
              "ETag": { "$ref": "#/components/headers/ETag" },
              "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
              "X-Bonihua-API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEntityResource" } } }
          },
          "304": { "$ref": "#/components/responses/NotModified" },
          "400": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/changes": {
      "get": {
        "tags": ["Freshness"],
        "summary": "Get the latest supplier-task lifecycle snapshot",
        "description": "Returns the latest source-backed publish/update event from the dataset manifest. This endpoint is a current snapshot, not a historical changelog, and lastReviewedAt remains null when no review date is verified.",
        "operationId": "getSupplierTaskLatestChangeSnapshot",
        "parameters": [{ "$ref": "#/components/parameters/IfNoneMatch" }],
        "responses": {
          "200": {
            "description": "Latest source-backed lifecycle snapshot.",
            "headers": {
              "ETag": { "$ref": "#/components/headers/ETag" },
              "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
              "X-Bonihua-API-Version": { "$ref": "#/components/headers/ApiVersion" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSnapshot" } } }
          },
          "304": { "$ref": "#/components/responses/NotModified" }
        }
      }
    },
    "/ai/faqs.json": {
      "get": {
        "tags": ["Legacy discovery"],
        "summary": "Fetch the existing static FAQ export",
        "operationId": "getFaqs",
        "responses": {
          "200": {
            "description": "Static FAQ export.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqExport" } } }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "TaskId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "URL-encoded stable task ID.",
        "schema": { "type": "string", "pattern": "^worktask:[a-z0-9-]+$" },
        "example": "worktask:rfq"
      },
      "SourceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "URL-encoded sourceId referenced by at least one supplier task.",
        "schema": { "type": "string", "pattern": "^[a-z][a-z0-9-]*:[a-z0-9-]+$" },
        "example": "workterm:moq"
      },
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "Return 304 when this value matches the current representation ETag.",
        "schema": { "type": "string" }
      }
    },
    "headers": {
      "ETag": {
        "description": "Weak ETag for the exact JSON representation.",
        "schema": { "type": "string" }
      },
      "CacheControl": {
        "description": "Public cache policy.",
        "schema": { "type": "string" }
      },
      "ApiVersion": {
        "description": "Knowledge API contract version.",
        "schema": { "type": "string", "const": "1.0.0" }
      }
    },
    "responses": {
      "NotModified": {
        "description": "Representation has not changed for the supplied If-None-Match value.",
        "headers": {
          "ETag": { "$ref": "#/components/headers/ETag" },
          "Cache-Control": { "$ref": "#/components/headers/CacheControl" },
          "X-Bonihua-API-Version": { "$ref": "#/components/headers/ApiVersion" }
        }
      },
      "Error": {
        "description": "Invalid or unknown stable ID.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "DatasetSource": {
        "type": "object",
        "required": ["datasetId", "version", "license", "publishedAt", "updatedAt", "lastReviewedAt", "sha256", "sourceUrl", "manifestUrl"],
        "properties": {
          "datasetId": { "type": "string" },
          "version": { "type": ["string", "null"] },
          "license": { "type": ["string", "null"] },
          "publishedAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "lastReviewedAt": { "type": ["string", "null"], "format": "date-time" },
          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "sourceUrl": { "type": "string", "format": "uri" },
          "manifestUrl": { "type": "string", "format": "uri" }
        }
      },
      "Link": {
        "type": "object",
        "required": ["href"],
        "properties": {
          "href": { "type": "string", "format": "uri" },
          "rel": { "type": "string" }
        }
      },
      "TaskSummary": {
        "type": "object",
        "required": ["id", "slug", "name", "description", "journeyId", "order", "channel", "nextTaskIds", "sourceIds", "provenance", "indexability", "links"],
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "journeyId": { "type": "string" },
          "order": { "type": "integer" },
          "channel": { "type": "string", "enum": ["email", "chat"] },
          "tags": { "type": "array", "items": { "type": "string" } },
          "nextTaskIds": { "type": "array", "items": { "type": "string" } },
          "sourceIds": { "type": "array", "items": { "type": "string" } },
          "provenance": { "type": "string" },
          "indexability": { "type": "object", "additionalProperties": true },
          "links": { "type": "object", "additionalProperties": { "anyOf": [{ "$ref": "#/components/schemas/Link" }, { "type": "null" }] } }
        }
      },
      "TaskCollection": {
        "type": "object",
        "required": ["apiVersion", "kind", "source", "links", "items", "graph"],
        "properties": {
          "apiVersion": { "type": "string", "const": "1.0.0" },
          "kind": { "type": "string", "const": "SupplierMessageTaskCollection" },
          "source": { "$ref": "#/components/schemas/DatasetSource" },
          "links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Link" } },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSummary" } },
          "graph": { "type": "object", "required": ["version", "nodes", "edges", "aggregates"], "additionalProperties": true }
        }
      },
      "TaskResource": {
        "type": "object",
        "required": ["apiVersion", "kind", "source", "links", "relations", "data"],
        "properties": {
          "apiVersion": { "type": "string", "const": "1.0.0" },
          "kind": { "type": "string", "const": "SupplierMessageTask" },
          "source": { "$ref": "#/components/schemas/DatasetSource" },
          "links": { "type": "object", "additionalProperties": { "anyOf": [{ "$ref": "#/components/schemas/Link" }, { "type": "null" }] } },
          "relations": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": ["id", "href"] } } },
          "data": { "type": "object", "additionalProperties": true }
        }
      },
      "SourceEntityResource": {
        "type": "object",
        "required": ["apiVersion", "kind", "source", "links", "usedByTasks", "data"],
        "properties": {
          "apiVersion": { "type": "string", "const": "1.0.0" },
          "kind": { "type": "string", "const": "SupplierMessageSourceEntity" },
          "source": { "$ref": "#/components/schemas/DatasetSource" },
          "links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Link" } },
          "usedByTasks": { "type": "array", "items": { "type": "object", "required": ["id", "href"] } },
          "data": { "type": "object", "additionalProperties": true }
        }
      },
      "ChangeSnapshot": {
        "type": "object",
        "required": ["apiVersion", "kind", "description", "asOf", "source", "links", "changes"],
        "properties": {
          "apiVersion": { "type": "string", "const": "1.0.0" },
          "kind": { "type": "string", "const": "SupplierMessageLatestChangeSnapshot" },
          "description": { "type": "string" },
          "asOf": { "type": "string", "format": "date-time" },
          "source": { "$ref": "#/components/schemas/DatasetSource" },
          "links": { "type": "object", "additionalProperties": true },
          "changes": {
            "type": "array",
            "maxItems": 1,
            "items": {
              "type": "object",
              "required": ["id", "datasetId", "changeType", "occurredAt", "version", "lastReviewedAt", "sourceUrl", "evidence"],
              "properties": {
                "changeType": { "type": "string", "enum": ["published", "updated"] },
                "lastReviewedAt": { "type": ["string", "null"], "format": "date-time" }
              },
              "additionalProperties": true
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["apiVersion", "error"],
        "properties": {
          "apiVersion": { "type": "string" },
          "error": { "type": "string" },
          "id": { "type": "string" }
        }
      },
      "FaqEntry": {
        "type": "object",
        "required": ["id", "url", "title", "locale", "items"],
        "additionalProperties": true
      },
      "FaqExport": {
        "type": "object",
        "required": ["generatedAt", "source", "entries"],
        "properties": {
          "generatedAt": { "type": "string", "format": "date-time" },
          "source": { "type": "string", "format": "uri" },
          "entries": { "type": "array", "items": { "$ref": "#/components/schemas/FaqEntry" } }
        }
      }
    }
  }
}