{
  "openapi": "3.1.0",
  "info": {
    "title": "HPH Integrations company context candidate",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/me": {
      "get": {
        "operationId": "GetCurrentActor",
        "x-runtime-status": "testing-available",
        "responses": {
          "200": {
            "description": "The current represented-company actor and effective public permissions.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CurrentActorResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "organization_id": "org-synthetic-0010",
                  "actor": { "type": "user" },
                  "permissions": ["company.capabilities.read", "identity.me.read"],
                  "evaluated_at": "2026-10-29T16:00:00Z"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/company/capabilities": {
      "get": {
        "operationId": "GetCompanyCapabilities",
        "x-runtime-status": "testing-available",
        "responses": {
          "200": {
            "description": "Current public capabilities derived for the represented company.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyCapabilitiesResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "capabilities": ["catalog_items", "hph_item_code", "labor_hours.mcaa", "material_vendors"],
                  "evaluated_at": "2026-10-29T16:00:00Z"
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/company/usage": {
      "get": {
        "operationId": "GetCompanyUsage",
        "x-runtime-status": "testing-available",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "First UTC usage date. Defaults to 29 days before through."
          },
          {
            "name": "through",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Last inclusive UTC usage date. Defaults to the current UTC date."
          }
        ],
        "responses": {
          "200": {
            "description": "Bounded API usage and current company quota status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyUsageResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "evaluated_at": "2026-10-29T16:00:00Z",
                  "data_through": "2026-10-29T15:55:00Z",
                  "period": { "from": "2026-10-01", "through": "2026-10-29", "timezone": "UTC" },
                  "api_usage": {
                    "summary": {
                      "request_count": 125,
                      "successful_request_count": 120,
                      "denied_request_count": 3,
                      "failed_request_count": 2,
                      "submitted_item_count": 40,
                      "returned_item_count": 310
                    },
                    "protected_content": {
                      "hph_item_codes_delivered": 200,
                      "unique_hph_item_codes_delivered": 75,
                      "hph_item_codes_withheld": 15,
                      "quota_denied_request_count": 1
                    },
                    "daily": [
                      {
                        "date": "2026-10-29",
                        "request_count": 12,
                        "returned_item_count": 30,
                        "hph_item_codes_delivered": 20,
                        "unique_hph_item_codes_delivered": 8
                      }
                    ]
                  },
                  "quotas": [
                    {
                      "quota": "daily_returned_items",
                      "maximum": 1000,
                      "consumed": 310,
                      "reserved": 10,
                      "remaining": 680,
                      "resets_at": "2026-10-30T00:00:00Z",
                      "measured_at": null
                    },
                    {
                      "quota": "active_catalog_items",
                      "maximum": 50000,
                      "consumed": 12000,
                      "reserved": null,
                      "remaining": 38000,
                      "resets_at": null,
                      "measured_at": "2026-10-29T15:45:00Z"
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CurrentActorResponseV1": {
        "type": "object",
        "additionalProperties": false,
        "required": ["contract_version", "organization_id", "actor", "permissions", "evaluated_at"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "organization_id": { "type": "string", "minLength": 1, "maxLength": 255 },
          "actor": { "$ref": "#/components/schemas/CurrentActorV1" },
          "permissions": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 128 } },
          "evaluated_at": { "type": "string", "format": "date-time" }
        }
      },
      "CurrentActorV1": {
        "oneOf": [
          { "$ref": "#/components/schemas/CurrentUserActorV1" },
          { "$ref": "#/components/schemas/CurrentPartnerApplicationActorV1" },
          { "$ref": "#/components/schemas/CurrentCompanyCredentialActorV1" }
        ],
        "discriminator": { "propertyName": "type" }
      },
      "CurrentUserActorV1": {
        "type": "object", "additionalProperties": false, "required": ["type"],
        "properties": { "type": { "type": "string", "const": "user" } }
      },
      "CurrentPartnerApplicationActorV1": {
        "type": "object", "additionalProperties": false, "required": ["type"],
        "properties": { "type": { "type": "string", "const": "partner_application" } }
      },
      "CurrentCompanyCredentialActorV1": {
        "type": "object", "additionalProperties": false, "required": ["type"],
        "properties": { "type": { "type": "string", "const": "company_credential" } }
      },
      "CompanyCapabilitiesResponseV1": {
        "type": "object", "additionalProperties": false,
        "required": ["contract_version", "capabilities", "evaluated_at"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "capabilities": { "type": "array", "maxItems": 32, "uniqueItems": true, "items": { "type": "string", "enum": ["catalog_items", "hph_item_code", "labor_hours.mcaa", "labor_hours.phcc", "material_vendors"] } },
          "evaluated_at": { "type": "string", "format": "date-time" }
        }
      },
      "CompanyUsageResponseV1": {
        "type": "object", "additionalProperties": false,
        "required": ["contract_version", "evaluated_at", "data_through", "period", "api_usage", "quotas"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "evaluated_at": { "type": "string", "format": "date-time" },
          "data_through": { "type": "string", "format": "date-time" },
          "period": { "$ref": "#/components/schemas/CompanyUsagePeriodV1" },
          "api_usage": { "$ref": "#/components/schemas/CompanyUsageV1" },
          "quotas": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/CompanyQuotaStatusV1" } }
        }
      },
      "CompanyUsagePeriodV1": {
        "type": "object", "additionalProperties": false, "required": ["from", "through", "timezone"],
        "properties": { "from": { "type": "string", "format": "date" }, "through": { "type": "string", "format": "date" }, "timezone": { "type": "string", "const": "UTC" } }
      },
      "CompanyUsageV1": {
        "type": "object", "additionalProperties": false, "required": ["summary", "protected_content", "daily"],
        "properties": {
          "summary": { "$ref": "#/components/schemas/CompanyUsageSummaryV1" },
          "protected_content": { "$ref": "#/components/schemas/CompanyProtectedContentUsageV1" },
          "daily": { "type": "array", "maxItems": 90, "items": { "$ref": "#/components/schemas/CompanyDailyUsageV1" } }
        }
      },
      "CompanyUsageSummaryV1": {
        "type": "object", "additionalProperties": false,
        "required": ["request_count", "successful_request_count", "denied_request_count", "failed_request_count", "submitted_item_count", "returned_item_count"],
        "properties": {
          "request_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "successful_request_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "denied_request_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "failed_request_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "submitted_item_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "returned_item_count": { "type": "integer", "format": "int64", "minimum": 0 }
        }
      },
      "CompanyProtectedContentUsageV1": {
        "type": "object", "additionalProperties": false,
        "required": ["hph_item_codes_delivered", "unique_hph_item_codes_delivered", "hph_item_codes_withheld", "quota_denied_request_count"],
        "properties": {
          "hph_item_codes_delivered": { "type": "integer", "format": "int64", "minimum": 0 },
          "unique_hph_item_codes_delivered": { "type": "integer", "format": "int64", "minimum": 0 },
          "hph_item_codes_withheld": { "type": "integer", "format": "int64", "minimum": 0 },
          "quota_denied_request_count": { "type": "integer", "format": "int64", "minimum": 0 }
        }
      },
      "CompanyDailyUsageV1": {
        "type": "object", "additionalProperties": false,
        "required": ["date", "request_count", "returned_item_count", "hph_item_codes_delivered", "unique_hph_item_codes_delivered"],
        "properties": {
          "date": { "type": "string", "format": "date" },
          "request_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "returned_item_count": { "type": "integer", "format": "int64", "minimum": 0 },
          "hph_item_codes_delivered": { "type": "integer", "format": "int64", "minimum": 0 },
          "unique_hph_item_codes_delivered": { "type": "integer", "format": "int64", "minimum": 0 }
        }
      },
      "CompanyQuotaStatusV1": {
        "type": "object", "additionalProperties": false,
        "required": ["quota", "maximum", "consumed", "reserved", "remaining", "resets_at", "measured_at"],
        "properties": {
          "quota": { "type": "string", "enum": ["active_catalog_items", "daily_cross_reference_alternatives_returned", "daily_delivered_hph_item_codes", "daily_returned_items", "daily_submitted_items", "hourly_cross_reference_requests", "hourly_requests", "monthly_new_unique_cross_reference_alternatives", "monthly_new_unique_hph_item_codes"] },
          "maximum": { "type": "integer", "format": "int64", "minimum": 0 },
          "consumed": { "type": "integer", "format": "int64", "minimum": 0 },
          "reserved": { "type": ["integer", "null"], "format": "int64", "minimum": 0 },
          "remaining": { "type": "integer", "format": "int64", "minimum": 0 },
          "resets_at": { "type": ["string", "null"], "format": "date-time" },
          "measured_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "StableProblemV1": { "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" } } } } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid bounded query.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Unauthorized": { "description": "Authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Forbidden": { "description": "The current actor lacks this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "NotFound": { "description": "Represented-company context was not found or is concealed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Unavailable": { "description": "A required authority or usage source is unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } }
    }
  }
}