{
  "openapi": "3.1.1",
  "info": {
    "title": "HPH Integrations company catalog-item creation",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/catalog/items": {
      "post": {
        "operationId": "CreateCompanyCatalogItem",
        "summary": "Add one governed HPH Item Code to the represented company catalog.",
        "x-runtime-status": "testing-available",
        "x-required-permission": "company-catalog-item.create",
        "x-idempotency-key-required": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateCompanyCatalogItemRequestV1" },
              "example": {
                "hph_item_code": "780TA5241",
                "company_item_id": "COMPANY-1001",
                "alternate_company_item_id": "ALT-1001",
                "company_description": "Synthetic catalog item",
                "reason": "Add the governed item to the company material catalog"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The item was already present, was previously retired, or an exact completed request was replayed.",
            "headers": {
              "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateCompanyCatalogItemResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "operation_reference": "catalogcreate_0123456789abcdef0123456789abcdef",
                  "outcome": "already_present",
                  "item": {
                    "item_skey": "11111111-1111-4111-8111-111111111111",
                    "company_item_id": "COMPANY-1001",
                    "alternate_company_item_id": "ALT-1001",
                    "company_description": "Synthetic catalog item",
                    "lifecycle": "active",
                    "item_history_revision": 7,
                    "observed_at": "2026-11-05T12:00:00Z"
                  },
                  "reused": true
                }
              }
            }
          },
          "201": {
            "description": "A new active company catalog item was created.",
            "headers": {
              "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateCompanyCatalogItemResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "operation_reference": "catalogcreate_0123456789abcdef0123456789abcdef",
                  "outcome": "created",
                  "item": {
                    "item_skey": "11111111-1111-4111-8111-111111111111",
                    "company_item_id": "COMPANY-1001",
                    "alternate_company_item_id": null,
                    "company_description": "Synthetic catalog item",
                    "lifecycle": "active",
                    "item_history_revision": 1,
                    "observed_at": "2026-11-05T12:00:00Z"
                  },
                  "reused": false
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Problem" },
          "401": { "$ref": "#/components/responses/Problem" },
          "403": { "$ref": "#/components/responses/Problem" },
          "409": { "$ref": "#/components/responses/Problem" },
          "429": { "$ref": "#/components/responses/Problem" },
          "503": { "$ref": "#/components/responses/Problem" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Problem": {
        "description": "A stable minimized public problem.",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ExternalProblem" }
          }
        }
      }
    },
    "schemas": {
      "CreateCompanyCatalogItemRequestV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["hph_item_code"],
        "properties": {
          "hph_item_code": { "$ref": "#/components/schemas/HphItemCode" },
          "company_item_id": {
            "type": ["string", "null"],
            "minLength": 1,
            "maxLength": 512
          },
          "alternate_company_item_id": {
            "type": ["string", "null"],
            "minLength": 1,
            "maxLength": 512
          },
          "company_description": {
            "type": ["string", "null"],
            "minLength": 1,
            "maxLength": 4096
          },
          "reason": {
            "type": ["string", "null"],
            "minLength": 1,
            "maxLength": 512
          }
        }
      },
      "CreateCompanyCatalogItemResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contract_version", "operation_reference", "outcome", "item", "reused"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "operation_reference": {
            "type": "string",
            "pattern": "^catalogcreate_[0-9a-f]{32}$"
          },
          "outcome": {
            "type": "string",
            "enum": ["created", "already_present", "inactive_existing"]
          },
          "item": { "$ref": "#/components/schemas/CompanyCatalogItemV1" },
          "reused": { "type": "boolean" }
        }
      },
      "CompanyCatalogItemV1": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "item_skey",
          "company_item_id",
          "alternate_company_item_id",
          "company_description",
          "lifecycle",
          "item_history_revision",
          "observed_at"
        ],
        "properties": {
          "item_skey": { "type": "string", "format": "uuid" },
          "company_item_id": { "type": ["string", "null"], "maxLength": 512 },
          "alternate_company_item_id": { "type": ["string", "null"], "maxLength": 512 },
          "company_description": { "type": ["string", "null"], "maxLength": 4096 },
          "lifecycle": { "type": "string", "enum": ["active", "inactive"] },
          "item_history_revision": { "type": "integer", "format": "int64", "minimum": 1 },
          "observed_at": { "type": "string", "format": "date-time" }
        }
      },
      "HphItemCode": {
        "type": "string",
        "minLength": 9,
        "maxLength": 10,
        "pattern": "^(?:[0-9]{3}[A-Z]{2}|010C |210C |275C1)[0-9]{4}[A-Z]?$"
      },
      "ExternalProblem": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "code", "correlation_id", "retryable", "errors"], "description": "Problem details as sent on the wire (application/problem+json). Field names are snake_case, like every other request and response body.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "retryable": { "type": "boolean" }, "errors": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }
    }
  }
}