Zeroheight Styleguides API

openapi: 3.2.0
info:
  title: zeroheight Styleguides API
  version: v2
  summary: The zeroheight public REST API for design system styleguides, pages, page statuses and token sets.
  description: The zeroheight REST API can be used to automate your design system workflow, make use of your content in new ways and leverage external tools to empower your design system.
  contact:
    name: zeroheight Support
    url: https://help.zeroheight.com/
    email: support@zeroheight.com
  termsOfService: https://terms.zeroheight.com/18bfef5dc/p/24f1a8-website-terms
  x-provenance:
    method: derived
    generated: '2026-08-28'
    derived-by: API Evangelist enrichment pipeline (pipeline-enrich.md STEP 0b)
    sources:
    - https://www.postman.com/zeroheight-0379/zeroheight/overview
    - postman/zeroheight-api.postman_collection.json
    - https://help.zeroheight.com/hc/en-us/articles/35887050539035
    - https://developers.zeroheight.com/
    - live 401/404 route probes of https://zeroheight.com/open_api/v2 on 2026-08-28
    not-published-by-provider: true
servers:
- url: https://zeroheight.com/open_api/v2
  description: zeroheight public API v2 (production)
security:
- apiClient: []
  apiKey: []
tags:
- name: Styleguides
  description: Design systems documented in zeroheight. A styleguide is the top-level container for pages, categories and versions.
paths:
  /styleguides:
    get:
      operationId: listStyleguides
      summary: List styleguides
      description: Lists the styleguides the authenticated token can read. Verified live — returns 401 without credentials.
      tags:
      - Styleguides
      responses:
        '200':
          description: A list of styleguides accessible to the token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /styleguides/{styleguide_id}/pages:
    parameters:
    - $ref: '#/components/parameters/StyleguideId'
    get:
      operationId: listStyleguidePages
      summary: List the pages in a styleguide
      description: Returns the pages belonging to a styleguide. Used by zeroheight's own page-status and release tutorials.
      tags:
      - Styleguides
      responses:
        '200':
          description: The pages in the styleguide.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /styleguides/{styleguide_id}/versions:
    parameters:
    - $ref: '#/components/parameters/StyleguideId'
    get:
      operationId: listStyleguideVersions
      summary: List the released versions of a styleguide
      description: Returns the published releases/versions of a styleguide, as used in zeroheight's "add design system releases to any website" tutorial.
      tags:
      - Styleguides
      responses:
        '200':
          description: The versions of the styleguide.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /styleguides/{styleguide_id}/categories:
    parameters:
    - $ref: '#/components/parameters/StyleguideId'
    get:
      operationId: listStyleguideCategories
      summary: List the categories in a styleguide
      description: Returns the styleguide's categories — the grouping layer of the navigation tree above pages.
      tags:
      - Styleguides
      responses:
        '200':
          description: The categories in the styleguide.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    SuccessEnvelope:
      type: object
      description: zeroheight wraps responses in a status/data envelope. The `data` payload shape is behind authentication and is not published, so it is intentionally unconstrained here.
      properties:
        status:
          type: string
          examples:
          - success
        data:
          type: object
    ErrorEnvelope:
      type: object
      description: Observed verbatim on unauthenticated probes of the live API on 2026-08-28. Every error carries a `request_id` suitable for support correlation.
      required:
      - status
      - message
      properties:
        status:
          type: string
          description: '`fail` for client authentication/validation failures, `error` for routing and server failures.'
          examples:
          - fail
          - error
        message:
          type: string
          examples:
          - Unauthorized
          - Not Found
        data:
          type: object
          properties:
            request_id:
              type: string
              description: Correlation identifier for the request, echoed on every error.
              examples:
              - f9510eb94423d255c30947c718bf58e0
  responses:
    Unauthorized:
      description: The Client ID or Access Token is missing, malformed or invalid. Observed live as `{"status":"fail","message":"Unauthorized","data":{"request_id":"..."}}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            observed:
              summary: Live unauthenticated response
              value:
                status: fail
                message: Unauthorized
                data:
                  request_id: f9510eb94423d255c30947c718bf58e0
    TooManyRequests:
      description: The per-API-key rate limit has been exceeded. zeroheight publishes a limit of 30 requests per 30 seconds per API key and returns X-RateLimit-* headers on every response.
      headers:
        X-RateLimit-Limit:
          description: The maximum number of requests the consumer is permitted to make per minute.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: The number of requests remaining in the current rate limit window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: The time at which the current rate limit window resets, in UTC epoch seconds.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The path is not routed, or the referenced resource does not exist. Observed live as `{"status":"error","message":"Not Found","data":{"request_id":"..."}}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            observed:
              summary: Live response for an unrouted path
              value:
                status: error
                message: Not Found
                data:
                  request_id: 7f86f819024dc13e2fa52484928fb481
  parameters:
    StyleguideId:
      name: styleguide_id
      in: path
      required: true
      description: The styleguide identifier.
      schema:
        type: string
  securitySchemes:
    apiClient:
      type: apiKey
      in: header
      name: X-API-CLIENT
      description: The Client ID generated in the Developers section of zeroheight organization or workspace settings. Client IDs are prefixed `zhci_`.
    apiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: The Access Token generated alongside the Client ID. Shown once only, treated like a password. Access tokens are prefixed `zhat_`.