{
  "openapi": "3.1.0",
  "info": {
    "title": "NEST VMS Public Content API",
    "version": "1.0.0",
    "summary": "Read-only public API describing NEST VMS: company identity, contact routing, site structure, platform modules and solutions.",
    "description": "The NEST VMS public content API lets developers and AI agents read structured information about NEST VMS without scraping HTML. It is unauthenticated and read-only, and exposes no customer or worker data.\n\nNEST VMS is a Vendor Management System for organizations running a mixed workforce of employees, contingent workers, staffing vendors, sub-vendors, independent contractors and statement-of-work project teams.\n\nThis is the public discovery surface, not the product API. The authenticated NEST VMS tenant API covering job orders, workers, timesheets, compliance records and invoices is provisioned per customer; contact support@nestvms.com for access.\n\nAll responses are JSON. Errors use a single documented envelope so a client never has to parse an HTML error page.",
    "termsOfService": "https://nestvms.com/terms",
    "contact": {
      "name": "NEST VMS Support",
      "email": "support@nestvms.com",
      "url": "https://nestvms.com/developers"
    },
    "license": {
      "name": "Proprietary - NEST VMS",
      "url": "https://nestvms.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://nestvms.com/api/v1",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "NEST VMS API documentation",
    "url": "https://nestvms.com/docs"
  },
  "tags": [
    { "name": "system", "description": "Service health and version information." },
    { "name": "company", "description": "Company identity, offices and contact routing." },
    { "name": "content", "description": "Site structure, platform modules and solution information." }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "tags": ["system"],
        "summary": "Check API availability",
        "description": "Returns the current status and version of the NEST VMS public content API. Call this first to confirm connectivity before issuing other requests.",
        "responses": {
          "200": {
            "description": "The API is reachable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/company": {
      "get": {
        "operationId": "getCompany",
        "tags": ["company"],
        "summary": "Get company identity and offices",
        "description": "Returns the NEST VMS company profile: legal name, description, slogan, website, ownership note, office addresses and departmental contact points. Use this to verify who NEST VMS is and how to reach the right team.",
        "responses": {
          "200": {
            "description": "The company profile.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Company" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/contact": {
      "get": {
        "operationId": "getContactRoutes",
        "tags": ["company"],
        "summary": "Get contact routing",
        "description": "Returns machine-readable contact routing for NEST VMS: the general support email and phone number, per-department contact points (sales, support, vendor relations, billing, contracts) and office addresses. Use this to answer questions about how to contact NEST VMS.",
        "responses": {
          "200": {
            "description": "Contact routing information.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactRoutes" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/pages": {
      "get": {
        "operationId": "listPages",
        "tags": ["content"],
        "summary": "List public pages",
        "description": "Returns every public page on nestvms.com with its path, canonical URL, title, description and markdown URL. Use this to enumerate the site instead of crawling it, then fetch a page's markdownUrl for its full text.",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "Return only the page whose route path matches this value exactly, for example /platform. Omit to return every page.",
            "schema": {
              "type": "string",
              "pattern": "^/[a-z0-9\\-/]*$",
              "examples": ["/platform"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching pages.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PageList" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/platform": {
      "get": {
        "operationId": "getPlatform",
        "tags": ["content"],
        "summary": "Get platform modules and program models",
        "description": "Returns the modules that make up the NEST VMS platform (contingent workforce platform, VMS, timesheets, SOW and project management, reporting, integrations) and the three program models NEST VMS is delivered under (VMS-Only, VMS + Support, MSP Program).",
        "responses": {
          "200": {
            "description": "Platform modules and program models.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Platform" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/solutions": {
      "get": {
        "operationId": "getSolutions",
        "tags": ["content"],
        "summary": "Get solutions by audience",
        "description": "Returns NEST VMS solutions grouped by audience (enterprises, MSPs and program owners, procurement and finance), the core product capabilities, and the business outcomes customers use NEST VMS to achieve. Use this to judge whether NEST VMS fits a described problem.",
        "responses": {
          "200": {
            "description": "Solutions, capabilities and outcomes.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Solutions" }
              }
            }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "The requested resource does not exist.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "The HTTP method is not supported. This API is read-only.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      },
      "InternalError": {
        "description": "An unexpected error occurred.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "description": "Service liveness information.",
        "required": ["status", "version", "timestamp"],
        "properties": {
          "status": {
            "type": "string",
            "description": "Always \"ok\" when the API is serving requests.",
            "enum": ["ok"]
          },
          "version": {
            "type": "string",
            "description": "Semantic version of the public content API."
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Server time when the response was generated, in ISO-8601 format."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "URL of the human-readable API documentation."
          }
        }
      },
      "Address": {
        "type": "object",
        "description": "A postal address for a NEST VMS office.",
        "required": ["label", "streetAddress", "addressLocality", "addressCountry"],
        "properties": {
          "label": { "type": "string", "description": "Human-readable name of the office." },
          "streetAddress": { "type": "string", "description": "Street address line." },
          "addressLocality": { "type": "string", "description": "City." },
          "addressRegion": { "type": "string", "description": "Province or state." },
          "postalCode": { "type": "string", "description": "Postal or ZIP code." },
          "addressCountry": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code.",
            "pattern": "^[A-Z]{2}$"
          }
        }
      },
      "ContactPoint": {
        "type": "object",
        "description": "A department that can be contacted directly.",
        "required": ["contactType", "email"],
        "properties": {
          "contactType": {
            "type": "string",
            "description": "The kind of enquiry this contact handles.",
            "examples": ["customer support", "sales", "vendor relations", "billing", "contracts"]
          },
          "email": { "type": "string", "format": "email", "description": "Email address." },
          "telephone": {
            "type": "string",
            "description": "Telephone number in E.164-style international format, when one is published for this department."
          }
        }
      },
      "Company": {
        "type": "object",
        "description": "The NEST VMS company profile.",
        "required": ["name", "url", "description", "offices", "contactPoints"],
        "properties": {
          "name": { "type": "string", "description": "Trading name." },
          "legalName": { "type": "string", "description": "Registered legal name." },
          "url": { "type": "string", "format": "uri", "description": "Company website." },
          "description": { "type": "string", "description": "What NEST VMS does." },
          "slogan": { "type": "string", "description": "Company slogan." },
          "ownership": {
            "type": "string",
            "description": "Ownership and founding note, for example Indigenous-owned and women-led."
          },
          "email": { "type": "string", "format": "email", "description": "General contact email." },
          "telephone": { "type": "string", "description": "General contact telephone number." },
          "offices": {
            "type": "array",
            "description": "All NEST VMS office locations.",
            "items": { "$ref": "#/components/schemas/Address" }
          },
          "contactPoints": {
            "type": "array",
            "description": "Departmental contact routing.",
            "items": { "$ref": "#/components/schemas/ContactPoint" }
          }
        }
      },
      "ContactRoutes": {
        "type": "object",
        "description": "How to reach NEST VMS.",
        "required": ["email", "telephone", "contactPoints", "offices"],
        "properties": {
          "email": { "type": "string", "format": "email", "description": "General contact email." },
          "telephone": { "type": "string", "description": "General contact telephone number." },
          "contactPoints": {
            "type": "array",
            "description": "Departmental contact routing.",
            "items": { "$ref": "#/components/schemas/ContactPoint" }
          },
          "offices": {
            "type": "array",
            "description": "All NEST VMS office locations.",
            "items": { "$ref": "#/components/schemas/Address" }
          },
          "vendorApplicationUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where a prospective vendor applies to join the NEST VMS supplier network."
          },
          "demoRequestUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where a prospective customer requests a product demo."
          }
        }
      },
      "Page": {
        "type": "object",
        "description": "A public page on nestvms.com.",
        "required": ["path", "url", "title", "description", "markdownUrl"],
        "properties": {
          "path": { "type": "string", "description": "Route path, for example /platform." },
          "url": { "type": "string", "format": "uri", "description": "Canonical absolute URL." },
          "title": { "type": "string", "description": "Document title." },
          "description": { "type": "string", "description": "Meta description." },
          "heading": { "type": "string", "description": "Primary heading of the page." },
          "markdownUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL serving this page as markdown."
          }
        }
      },
      "PageList": {
        "type": "object",
        "description": "A list of public pages.",
        "required": ["pages"],
        "properties": {
          "pages": {
            "type": "array",
            "description": "The matching pages.",
            "items": { "$ref": "#/components/schemas/Page" }
          },
          "count": { "type": "integer", "description": "Number of pages returned.", "minimum": 0 }
        }
      },
      "NamedItem": {
        "type": "object",
        "description": "A named entity with a stable identifier and a description.",
        "required": ["id", "name", "description"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable lowercase identifier.",
            "pattern": "^[a-z0-9\\-]+$"
          },
          "name": { "type": "string", "description": "Display name." },
          "description": { "type": "string", "description": "What it does or means." }
        }
      },
      "Platform": {
        "type": "object",
        "description": "The NEST VMS platform surface.",
        "required": ["modules", "programModels"],
        "properties": {
          "modules": {
            "type": "array",
            "description": "Functional modules of the platform.",
            "items": { "$ref": "#/components/schemas/NamedItem" }
          },
          "programModels": {
            "type": "array",
            "description": "Delivery models NEST VMS is offered under.",
            "items": { "$ref": "#/components/schemas/NamedItem" }
          }
        }
      },
      "Solutions": {
        "type": "object",
        "description": "Who NEST VMS is for and what it delivers.",
        "required": ["audiences", "capabilities", "outcomes"],
        "properties": {
          "audiences": {
            "type": "array",
            "description": "Audience segments NEST VMS serves.",
            "items": { "$ref": "#/components/schemas/NamedItem" }
          },
          "capabilities": {
            "type": "array",
            "description": "Core product capabilities.",
            "items": { "$ref": "#/components/schemas/NamedItem" }
          },
          "outcomes": {
            "type": "array",
            "description": "Business outcomes customers achieve.",
            "items": { "$ref": "#/components/schemas/NamedItem" }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "The single error envelope used by every failing request.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "description": "Details of the failure: what went wrong, and what the caller should do about it.",
            "required": ["code", "message", "status"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code.",
                "enum": ["not_found", "method_not_allowed", "not_acceptable", "internal_error"]
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of what went wrong."
              },
              "status": {
                "type": "integer",
                "description": "HTTP status code, repeated in the body for clients that only read the payload."
              },
              "resolution": {
                "type": "string",
                "description": "What the caller should do next to succeed."
              },
              "documentation": {
                "type": "string",
                "format": "uri",
                "description": "URL of the documentation covering this error."
              }
            }
          }
        }
      }
    }
  }
}