{
  "components": {
    "schemas": {
      "Author": {
        "properties": {
          "name": {
            "type": "string"
          },
          "role": {
            "description": "Why this person is the signatory for this piece.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "role"
        ],
        "type": "object"
      },
      "Company": {
        "properties": {
          "contact": {
            "properties": {
              "email": {
                "format": "email",
                "type": "string"
              },
              "phone": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "entity": {
            "description": "The registered company behind the site.",
            "properties": {
              "companyNumber": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "disambiguation": {
                "description": "Which HIVO this is: the registered entity, and the similarly named companies it is not affiliated with.",
                "type": "string"
              },
              "founded": {
                "format": "date",
                "type": "string"
              },
              "incorporated": {
                "format": "date",
                "type": "string"
              },
              "legalName": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "founders": {
            "items": {
              "$ref": "#/components/schemas/Founder"
            },
            "type": "array"
          },
          "intro": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "sections": {
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title",
          "founders",
          "entity"
        ],
        "type": "object"
      },
      "Endpoint": {
        "properties": {
          "description": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "returns": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "description",
          "returns"
        ],
        "type": "object"
      },
      "Error": {
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "Founder": {
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "paragraphs": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "role": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "role"
        ],
        "type": "object"
      },
      "HowWeWork": {
        "properties": {
          "sections": {
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "type": "array"
          },
          "stages": {
            "items": {
              "$ref": "#/components/schemas/Stage"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title",
          "stages"
        ],
        "type": "object"
      },
      "Industry": {
        "properties": {
          "intro": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "sections": {
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "type": "array"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "name",
          "url"
        ],
        "type": "object"
      },
      "IndustryList": {
        "properties": {
          "count": {
            "type": "integer"
          },
          "sectors": {
            "items": {
              "$ref": "#/components/schemas/IndustrySummary"
            },
            "type": "array"
          }
        },
        "required": [
          "count",
          "sectors"
        ],
        "type": "object"
      },
      "IndustrySummary": {
        "properties": {
          "api": {
            "format": "uri",
            "type": "string"
          },
          "indexDescription": {
            "type": "string"
          },
          "indexTitle": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "name",
          "url",
          "api"
        ],
        "type": "object"
      },
      "Insight": {
        "allOf": [
          {
            "$ref": "#/components/schemas/InsightSummary"
          },
          {
            "properties": {
              "body": {
                "description": "The article body as authored blocks, not flattened prose. Each block carries a `type`: h2, h3, p, stat, list, table, claim or note. A `stat` block carries its own source, which is why the body is not collapsed to a string.",
                "items": {
                  "type": "object"
                },
                "type": "array"
              },
              "faq": {
                "items": {
                  "$ref": "#/components/schemas/Question"
                },
                "type": "array"
              },
              "image": {
                "properties": {
                  "alt": {
                    "type": "string"
                  },
                  "src": {
                    "format": "uri",
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "related": {
                "items": {
                  "$ref": "#/components/schemas/RelatedArticle"
                },
                "type": "array"
              },
              "sources": {
                "items": {
                  "$ref": "#/components/schemas/Source"
                },
                "type": "array"
              },
              "text_format": {
                "description": "The markup convention used inside every prose string in this response. `inline-markdown` means `[label](href)` links and `**bold**` appear literally and should be parsed, not printed.",
                "enum": [
                  "inline-markdown"
                ],
                "type": "string"
              }
            },
            "required": [
              "body",
              "text_format",
              "sources"
            ],
            "type": "object"
          }
        ]
      },
      "InsightList": {
        "properties": {
          "articles": {
            "items": {
              "$ref": "#/components/schemas/InsightSummary"
            },
            "type": "array"
          },
          "count": {
            "type": "integer"
          }
        },
        "required": [
          "count",
          "articles"
        ],
        "type": "object"
      },
      "InsightSummary": {
        "properties": {
          "answer": {
            "description": "A self-contained passage of 40 to 60 words that answers `question` without the rest of the page. It is included in the list response so a client can answer without a second request.",
            "type": "string"
          },
          "api": {
            "format": "uri",
            "type": "string"
          },
          "author": {
            "$ref": "#/components/schemas/Author"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "publishedAt": {
            "format": "date",
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "updatedAt": {
            "format": "date",
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "title",
          "question",
          "answer",
          "url"
        ],
        "type": "object"
      },
      "Manifest": {
        "properties": {
          "contact": {
            "format": "email",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "documentation": {
            "format": "uri",
            "type": "string"
          },
          "endpoints": {
            "items": {
              "$ref": "#/components/schemas/Endpoint"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "notes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "site": {
            "format": "uri",
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "version",
          "site",
          "endpoints"
        ],
        "type": "object"
      },
      "Model": {
        "properties": {
          "intro": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "sections": {
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title",
          "sections"
        ],
        "type": "object"
      },
      "Question": {
        "properties": {
          "answer": {
            "type": "string"
          },
          "question": {
            "type": "string"
          }
        },
        "required": [
          "question",
          "answer"
        ],
        "type": "object"
      },
      "RelatedArticle": {
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "title",
          "url"
        ],
        "type": "object"
      },
      "SectionItem": {
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "line": {
            "description": "The single line that says what this item actually means.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "label"
        ],
        "type": "object"
      },
      "Section": {
        "properties": {
          "groups": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "description": "The stable role this section plays on the page.",
            "type": "string"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SectionItem"
            },
            "type": "array"
          },
          "paragraphs": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title"
        ],
        "type": "object"
      },
      "Source": {
        "properties": {
          "date": {
            "type": "string"
          },
          "href": {
            "format": "uri",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "publisher",
          "href"
        ],
        "type": "object"
      },
      "Stage": {
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "line": {
            "type": "string"
          },
          "number": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "number",
          "label"
        ],
        "type": "object"
      }
    }
  },
  "externalDocs": {
    "description": "Developer and agent documentation",
    "url": "https://www.hi-vo.io/docs"
  },
  "info": {
    "contact": {
      "email": "office@hi-vo.io",
      "name": "HIVO",
      "url": "https://www.hi-vo.io/contact"
    },
    "description": "The public read-only API for the HIVO website. It serves the same authored content the\npages render, as JSON.\n\nRead-only: every operation is a GET and nothing here changes anything. No authentication\nis required. CORS is open to any origin.\n\nNo rate limit is enforced and none is advertised. Every response is prerendered at build\ntime and served from a CDN, revalidated every 10 minutes, so there is no per-client\nbudget to report and no `RateLimit` header to honour.\n\nEvery page of the website is also available as markdown: send `Accept: text/markdown` to\nany URL on this host.\n\nVERSIONING AND DEPRECATION. The version is in the path: `/agent/v1`. A change that would\nbreak a client - a field removed, a type changed, a path retired - arrives as a new\nversion alongside this one, never as an edit to it. Fields may be ADDED to a response\nwithout a version change, so parse permissively and ignore what you do not recognise.\n\nWhen a version is retired it is announced before it stops answering, not after: every\nresponse from the retiring version carries `Deprecation` and `Sunset` headers (RFC 8594)\nfrom the announcement until the sunset date, and that date is at least 180 days out. A\nclient that reads those two headers has half a year of warning and never has to poll\nthis document to find out.",
    "license": {
      "name": "Content is published by HIVO IO Technologies Ltd",
      "url": "https://www.hi-vo.io/terms"
    },
    "title": "HIVO public API",
    "version": "1"
  },
  "openapi": "3.1.0",
  "paths": {
    "/agent/v1": {
      "get": {
        "description": "Start here. Lists every endpoint on this API, the site it describes, and how the responses are cached.",
        "operationId": "getManifest",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            },
            "description": "The API manifest."
          }
        },
        "summary": "The manifest: name, version, site, contact, the endpoint list, and caching notes.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/company": {
      "get": {
        "description": "Who HIVO is, who runs it, and the registered entity behind it, with the public contact address.",
        "operationId": "getCompany",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            },
            "description": "The company page."
          }
        },
        "summary": "The company page, the founders as a first-class list, the registered entity, and the contact details.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/how-we-work": {
      "get": {
        "description": "What HIVO does inside a client organization, in order, from discovery through adoption.",
        "operationId": "getHowWeWork",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HowWeWork"
                }
              }
            },
            "description": "The six delivery stages."
          }
        },
        "summary": "The six delivery stages, each with its number and what happens in it, plus the page.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/industries": {
      "get": {
        "description": "Every sector HIVO works in, with the central operating object each one is built around. This is where a sector slug comes from.",
        "operationId": "listIndustries",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IndustryList"
                }
              }
            },
            "description": "Every sector HIVO works in."
          }
        },
        "summary": "One entry per sector: slug, name, its central object, and links to the page and to its own endpoint.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/industries/{sector}": {
      "get": {
        "description": "One sector in full. The sector value is a slug from the industries list; any other value returns 404.",
        "operationId": "getIndustry",
        "parameters": [
          {
            "description": "A sector slug, as returned by listIndustries, e.g. logistics.",
            "in": "path",
            "name": "sector",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Industry"
                }
              }
            },
            "description": "One sector."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No such slug. The index endpoint lists every value this segment accepts."
          }
        },
        "summary": "The sector page: name, title, intro, and its sections.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/insights": {
      "get": {
        "description": "Every published article. Each entry carries the self-contained answer to the question the article was written for, so a question can be answered without a second request.",
        "operationId": "listInsights",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InsightList"
                }
              }
            },
            "description": "Every published article."
          }
        },
        "summary": "One entry per article: the extractable answer, the author, the dates, and the links.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/insights/{slug}": {
      "get": {
        "description": "One article in full, with the body as structured blocks rather than as a wall of text. The slug comes from the insights list; any other value returns 404.",
        "operationId": "getInsight",
        "parameters": [
          {
            "description": "An article slug, as returned by listInsights.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Insight"
                }
              }
            },
            "description": "One article in full."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "description": "No such slug. The index endpoint lists every value this segment accepts."
          }
        },
        "summary": "The full article: body blocks, questions and answers, cited sources, related articles, and the image.",
        "tags": [
          "HIVO"
        ]
      }
    },
    "/agent/v1/model": {
      "get": {
        "description": "How HIVO structures an organization around the object it earns from, what the two connected middle layers are, what still requires human judgement, and why the record compounds.",
        "operationId": "getModel",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            },
            "description": "The operating model."
          }
        },
        "summary": "The model page: title, intro, and every section with its id and title, plus its paragraphs, items or groups depending on the section.",
        "tags": [
          "HIVO"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://www.hi-vo.io"
    }
  ],
  "tags": [
    {
      "description": "Everything this API serves is content published on the HIVO website.",
      "name": "HIVO"
    }
  ]
}