{
  "openapi": "3.1.0",
  "info": {
    "title": "Pyromanic API",
    "version": "2026-08-11",
    "description": "Everything the Pyromanic app can do, available over HTTP. Authenticate with a secret key as a bearer token. Breaking changes are announced by date-pinned version; send `Pyromanic-Version` to pin one."
  },
  "servers": [
    {
      "url": "https://api.pyromanic.com"
    }
  ],
  "paths": {
    "/v1/companies": {
      "get": {
        "operationId": "listCompanies",
        "summary": "List the companies this key can act on.",
        "description": "A key is scoped to a single company, so this returns exactly one. Use it to discover the id for every other endpoint rather than hard-coding one.",
        "tags": [
          "company"
        ],
        "security": [
          {
            "secretKey": [
              "company:read"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Display name."
                          },
                          "slug": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "summary": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "One or two sentences describing the product."
                          },
                          "websiteUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "repositoryUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "industry": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "stage": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "idea | mvp | growth | scale"
                          },
                          "teamSize": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "targetMarket": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "b2b | b2c | b2b2c"
                          },
                          "primaryLanguage": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "ISO 639-1, e.g. \"en\"."
                          },
                          "timezone": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "IANA name, e.g. \"Australia/Melbourne\"."
                          },
                          "emailDomain": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "onboardingStatus": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "slug",
                          "summary",
                          "websiteUrl",
                          "repositoryUrl",
                          "industry",
                          "stage",
                          "teamSize",
                          "targetMarket",
                          "primaryLanguage",
                          "timezone",
                          "emailDomain",
                          "onboardingStatus",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}": {
      "get": {
        "operationId": "getCompany",
        "summary": "Fetch a company.",
        "description": "The company your key is scoped to. Any other id returns 404.",
        "tags": [
          "company"
        ],
        "security": [
          {
            "secretKey": [
              "company:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Display name."
                    },
                    "slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "One or two sentences describing the product."
                    },
                    "websiteUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositoryUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "industry": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "stage": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "idea | mvp | growth | scale"
                    },
                    "teamSize": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetMarket": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "b2b | b2c | b2b2c"
                    },
                    "primaryLanguage": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "ISO 639-1, e.g. \"en\"."
                    },
                    "timezone": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "IANA name, e.g. \"Australia/Melbourne\"."
                    },
                    "emailDomain": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "onboardingStatus": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "slug",
                    "summary",
                    "websiteUrl",
                    "repositoryUrl",
                    "industry",
                    "stage",
                    "teamSize",
                    "targetMarket",
                    "primaryLanguage",
                    "timezone",
                    "emailDomain",
                    "onboardingStatus",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "operationId": "updateCompany",
        "summary": "Update a company.",
        "tags": [
          "company"
        ],
        "security": [
          {
            "secretKey": [
              "company:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Display name."
                    },
                    "slug": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "One or two sentences describing the product."
                    },
                    "websiteUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "repositoryUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "industry": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "stage": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "idea | mvp | growth | scale"
                    },
                    "teamSize": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetMarket": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "b2b | b2c | b2b2c"
                    },
                    "primaryLanguage": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "ISO 639-1, e.g. \"en\"."
                    },
                    "timezone": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "IANA name, e.g. \"Australia/Melbourne\"."
                    },
                    "emailDomain": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "onboardingStatus": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "slug",
                    "summary",
                    "websiteUrl",
                    "repositoryUrl",
                    "industry",
                    "stage",
                    "teamSize",
                    "targetMarket",
                    "primaryLanguage",
                    "timezone",
                    "emailDomain",
                    "onboardingStatus",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "summary": {
                    "type": "string"
                  },
                  "websiteUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "repositoryUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "industry": {
                    "type": "string"
                  },
                  "stage": {
                    "type": "string",
                    "enum": [
                      "idea",
                      "mvp",
                      "growth",
                      "scale"
                    ]
                  },
                  "targetMarket": {
                    "type": "string",
                    "enum": [
                      "b2b",
                      "b2c",
                      "b2b2c"
                    ]
                  },
                  "primaryLanguage": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/metrics/definitions": {
      "get": {
        "operationId": "listMetricDefinitions",
        "summary": "List metric definitions.",
        "description": "What this company measures. Read this to learn the keys the points endpoint accepts.",
        "tags": [
          "metrics"
        ],
        "security": [
          {
            "secretKey": [
              "metrics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 100,
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "needsReview",
            "in": "query",
            "required": false,
            "schema": {
              "description": "Filter to keys auto-created by an unrecognised push and not yet confirmed.",
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Filter to keys auto-created by an unrecognised push and not yet confirmed."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "key": {
                            "type": "string",
                            "description": "Stable slug, e.g. \"revenue.net\". Anything bespoke is namespaced \"custom.*\"."
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "description": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "unit": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "currency_minor | count | ratio | duration_ms | score | bytes"
                          },
                          "aggregation": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "How days roll into weeks and months. Not cosmetic — summing a ratio across days is wrong."
                          },
                          "polarity": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "up_is_good | down_is_good | neutral"
                          },
                          "kind": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "measured | derived | split"
                          },
                          "formula": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Derived metrics only, e.g. \"revenue.net / users.active.monthly\"."
                          },
                          "dimensions": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "source": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "needsReview": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "True for keys auto-created by an unrecognised push, so instrumentation is never blocked."
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "key",
                          "name",
                          "description",
                          "unit",
                          "aggregation",
                          "polarity",
                          "kind",
                          "formula",
                          "dimensions",
                          "source",
                          "needsReview",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/metrics/points": {
      "get": {
        "operationId": "listMetricPoints",
        "summary": "Read a metric series.",
        "description": "Values for one metric over a date range. Points are keyed so a re-send overwrites in place, which is why a backfill and a nightly recompute both look like this.",
        "tags": [
          "metrics"
        ],
        "security": [
          {
            "secretKey": [
              "metrics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metricKey",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Required. From the definitions endpoint."
            },
            "description": "Required. From the definitions endpoint."
          },
          {
            "name": "grain",
            "in": "query",
            "required": true,
            "schema": {
              "default": "day",
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "description": "ISO date, inclusive.",
              "type": "string"
            },
            "description": "ISO date, inclusive."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "description": "ISO date, inclusive.",
              "type": "string"
            },
            "description": "ISO date, inclusive."
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 365,
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "seriesId": {
                            "type": "string"
                          },
                          "pointKey": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "metricKey": {
                            "type": "string"
                          },
                          "grain": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "day | week | month"
                          },
                          "ts": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "dims": {
                            "anyOf": [
                              {},
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "value": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "currency": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "baseValue": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Converted to the company's base currency; the original is never overwritten."
                          },
                          "source": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "ingestedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "seriesId",
                          "pointKey",
                          "companyId",
                          "metricKey",
                          "grain",
                          "ts",
                          "dims",
                          "value",
                          "currency",
                          "baseValue",
                          "source",
                          "ingestedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/optimise/sites": {
      "get": {
        "operationId": "listSites",
        "summary": "List measured sites.",
        "tags": [
          "optimise"
        ],
        "security": [
          {
            "secretKey": [
              "optimise:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "siteKey": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Publishable. Pasted into the customer's pages alongside the collector."
                          },
                          "domains": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "timezone": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "active": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "lastEventAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "When the collector last reported. A flat line here means it stopped."
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "name",
                          "siteKey",
                          "domains",
                          "timezone",
                          "active",
                          "lastEventAt",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/optimise/sites/{siteId}/goals": {
      "get": {
        "operationId": "listSiteGoals",
        "summary": "List goals defined on a site.",
        "tags": [
          "optimise"
        ],
        "security": [
          {
            "secretKey": [
              "optimise:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "siteId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "siteId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "kind": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "path | event"
                          },
                          "matchType": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "exact | prefix | contains | regex"
                          },
                          "pattern": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "value": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "order": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "active": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "siteId",
                          "name",
                          "kind",
                          "matchType",
                          "pattern",
                          "value",
                          "order",
                          "active",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/optimise/audits": {
      "get": {
        "operationId": "listSiteAudits",
        "summary": "List site audits.",
        "description": "Scores and summaries. Fetch one audit for its per-page findings.",
        "tags": [
          "optimise"
        ],
        "security": [
          {
            "secretKey": [
              "optimise:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 20,
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "siteId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "running",
                "complete",
                "failed"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "siteId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "rootUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "running | complete | failed"
                          },
                          "startedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "finishedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "scoreSeo": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "scoreAeo": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "scoreGeo": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "pagesAudited": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "summary": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "error": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "siteId",
                          "rootUrl",
                          "status",
                          "startedAt",
                          "finishedAt",
                          "scoreSeo",
                          "scoreAeo",
                          "scoreGeo",
                          "pagesAudited",
                          "summary",
                          "error",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/optimise/audits/{auditId}": {
      "get": {
        "operationId": "getSiteAudit",
        "summary": "Fetch one audit, with findings.",
        "tags": [
          "optimise"
        ],
        "security": [
          {
            "secretKey": [
              "optimise:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "auditId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "siteId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "rootUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "running | complete | failed"
                    },
                    "startedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "finishedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scoreSeo": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scoreAeo": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scoreGeo": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pagesAudited": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "error": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "findings": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Per-page findings. Large — only returned for a single audit."
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "siteId",
                    "rootUrl",
                    "status",
                    "startedAt",
                    "finishedAt",
                    "scoreSeo",
                    "scoreAeo",
                    "scoreGeo",
                    "pagesAudited",
                    "summary",
                    "error",
                    "createdAt",
                    "updatedAt",
                    "findings"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/feedback": {
      "get": {
        "operationId": "listFeedback",
        "summary": "List reviews and mentions.",
        "tags": [
          "feedback"
        ],
        "security": [
          {
            "secretKey": [
              "feedback:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "app_store",
                "google_play",
                "reddit"
              ]
            }
          },
          {
            "name": "sentiment",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "positive",
                "neutral",
                "negative"
              ]
            }
          },
          {
            "name": "replyStatus",
            "in": "query",
            "required": false,
            "schema": {
              "description": "Filter to a stage of the reply workflow — \"needs_review\" is the queue.",
              "type": "string",
              "enum": [
                "none",
                "draft",
                "needs_review",
                "approved",
                "posting",
                "posted",
                "failed",
                "skipped"
              ]
            },
            "description": "Filter to a stage of the reply workflow — \"needs_review\" is the queue."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "source": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "app_store | google_play | reddit"
                          },
                          "kind": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "review | mention"
                          },
                          "externalId": {
                            "type": "string",
                            "description": "The platform's own id."
                          },
                          "externalUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "authorName": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "title": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "body": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "rating": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Null for mentions, which carry no rating."
                          },
                          "appVersion": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "territory": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "locale": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "postedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "fetchedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "flags": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Risk labels: money, defect, legal, safety, churn."
                          },
                          "priority": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Lower sorts first."
                          },
                          "sentiment": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "positive | neutral | negative"
                          },
                          "replyBody": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "replyStatus": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "none | draft | needs_review | approved | posting | posted | failed | skipped"
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "source",
                          "kind",
                          "externalId",
                          "externalUrl",
                          "authorName",
                          "title",
                          "body",
                          "rating",
                          "appVersion",
                          "territory",
                          "locale",
                          "postedAt",
                          "fetchedAt",
                          "flags",
                          "priority",
                          "sentiment",
                          "replyBody",
                          "replyStatus",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/feedback/{feedbackId}": {
      "get": {
        "operationId": "getFeedback",
        "summary": "Fetch one review or mention.",
        "tags": [
          "feedback"
        ],
        "security": [
          {
            "secretKey": [
              "feedback:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "feedbackId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "source": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "app_store | google_play | reddit"
                    },
                    "kind": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "review | mention"
                    },
                    "externalId": {
                      "type": "string",
                      "description": "The platform's own id."
                    },
                    "externalUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "authorName": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "body": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "rating": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Null for mentions, which carry no rating."
                    },
                    "appVersion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "territory": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "locale": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "postedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "fetchedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "flags": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Risk labels: money, defect, legal, safety, churn."
                    },
                    "priority": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lower sorts first."
                    },
                    "sentiment": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "positive | neutral | negative"
                    },
                    "replyBody": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "replyStatus": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "none | draft | needs_review | approved | posting | posted | failed | skipped"
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "source",
                    "kind",
                    "externalId",
                    "externalUrl",
                    "authorName",
                    "title",
                    "body",
                    "rating",
                    "appVersion",
                    "territory",
                    "locale",
                    "postedAt",
                    "fetchedAt",
                    "flags",
                    "priority",
                    "sentiment",
                    "replyBody",
                    "replyStatus",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/feedback/{feedbackId}/reply": {
      "patch": {
        "operationId": "updateFeedbackReply",
        "summary": "Write or update the reply to a review.",
        "description": "Stores the reply text and its workflow status. This does not send anything — posting back to the platform is a separate, human-confirmed step, and several sources are read-only. Set status to \"approved\" to mark a reply ready to send.",
        "tags": [
          "feedback"
        ],
        "security": [
          {
            "secretKey": [
              "feedback:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "feedbackId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "source": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "app_store | google_play | reddit"
                    },
                    "kind": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "review | mention"
                    },
                    "externalId": {
                      "type": "string",
                      "description": "The platform's own id."
                    },
                    "externalUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "authorName": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "body": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "rating": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Null for mentions, which carry no rating."
                    },
                    "appVersion": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "territory": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "locale": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "postedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "fetchedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "flags": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Risk labels: money, defect, legal, safety, churn."
                    },
                    "priority": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Lower sorts first."
                    },
                    "sentiment": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "positive | neutral | negative"
                    },
                    "replyBody": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "replyStatus": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "none | draft | needs_review | approved | posting | posted | failed | skipped"
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "source",
                    "kind",
                    "externalId",
                    "externalUrl",
                    "authorName",
                    "title",
                    "body",
                    "rating",
                    "appVersion",
                    "territory",
                    "locale",
                    "postedAt",
                    "fetchedAt",
                    "flags",
                    "priority",
                    "sentiment",
                    "replyBody",
                    "replyStatus",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "replyBody": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "replyStatus": {
                    "type": "string",
                    "enum": [
                      "none",
                      "draft",
                      "needs_review",
                      "approved",
                      "skipped"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/boards": {
      "get": {
        "operationId": "listPlanBoards",
        "summary": "List roadmap boards.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 25,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "publicKey": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Publishable. Selects this board for the delivery API; authorises nothing."
                          },
                          "allowedOrigins": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Domains permitted to submit feedback. Empty admits any origin."
                          },
                          "publishedVersion": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "publishedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "active": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "name",
                          "publicKey",
                          "allowedOrigins",
                          "publishedVersion",
                          "publishedAt",
                          "active",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/boards/{boardId}": {
      "get": {
        "operationId": "getPlanBoard",
        "summary": "Fetch one roadmap board.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "publicKey": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Publishable. Selects this board for the delivery API; authorises nothing."
                    },
                    "allowedOrigins": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Domains permitted to submit feedback. Empty admits any origin."
                    },
                    "publishedVersion": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "publishedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "active": {
                      "anyOf": [
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "name",
                    "publicKey",
                    "allowedOrigins",
                    "publishedVersion",
                    "publishedAt",
                    "active",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/boards/{boardId}/items": {
      "get": {
        "operationId": "listPlanItems",
        "summary": "List items on a board.",
        "description": "Includes drafts. This is the authoring view, not what visitors see.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "in_review",
                "published",
                "archived"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "roadmapId": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "slug": {
                            "type": "string",
                            "description": "Stable public identifier. Frozen after creation."
                          },
                          "title": {
                            "type": "string"
                          },
                          "summary": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "columnId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Which column it sits in on the public board."
                          },
                          "categoryIds": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "draft | in_review | published | archived. Editorial only — never leaves this API."
                          },
                          "sortOrder": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "targetLabel": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Free text, e.g. \"Q3\" — deliberately not a date."
                          },
                          "publishedVersion": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "roadmapId",
                          "companyId",
                          "slug",
                          "title",
                          "summary",
                          "columnId",
                          "categoryIds",
                          "status",
                          "sortOrder",
                          "targetLabel",
                          "publishedVersion",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createPlanItem",
        "summary": "Add an item to a board.",
        "description": "Created as a draft unless a status is given. Nothing becomes visible until you publish.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "roadmapId": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string",
                      "description": "Stable public identifier. Frozen after creation."
                    },
                    "title": {
                      "type": "string"
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "columnId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Which column it sits in on the public board."
                    },
                    "categoryIds": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "draft | in_review | published | archived. Editorial only — never leaves this API."
                    },
                    "sortOrder": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetLabel": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Free text, e.g. \"Q3\" — deliberately not a date."
                    },
                    "publishedVersion": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "roadmapId",
                    "companyId",
                    "slug",
                    "title",
                    "summary",
                    "columnId",
                    "categoryIds",
                    "status",
                    "sortOrder",
                    "targetLabel",
                    "publishedVersion",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "summary": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "slug": {
                    "description": "Derived from the title when omitted. Frozen afterwards — links depend on it.",
                    "type": "string",
                    "maxLength": 80,
                    "pattern": "^[a-z0-9-]+$"
                  },
                  "columnId": {
                    "type": "string"
                  },
                  "categoryIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "default": "draft",
                    "type": "string",
                    "enum": [
                      "draft",
                      "in_review",
                      "published",
                      "archived"
                    ]
                  },
                  "sortOrder": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  "targetLabel": {
                    "type": "string",
                    "maxLength": 60
                  }
                },
                "required": [
                  "title",
                  "status"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/items/{itemId}": {
      "get": {
        "operationId": "getPlanItem",
        "summary": "Fetch one item.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "roadmapId": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string",
                      "description": "Stable public identifier. Frozen after creation."
                    },
                    "title": {
                      "type": "string"
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "columnId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Which column it sits in on the public board."
                    },
                    "categoryIds": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "draft | in_review | published | archived. Editorial only — never leaves this API."
                    },
                    "sortOrder": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetLabel": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Free text, e.g. \"Q3\" — deliberately not a date."
                    },
                    "publishedVersion": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "roadmapId",
                    "companyId",
                    "slug",
                    "title",
                    "summary",
                    "columnId",
                    "categoryIds",
                    "status",
                    "sortOrder",
                    "targetLabel",
                    "publishedVersion",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "operationId": "updatePlanItem",
        "summary": "Update an item.",
        "description": "Slug is deliberately not updatable — changing it breaks every link already shared.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "roadmapId": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string",
                      "description": "Stable public identifier. Frozen after creation."
                    },
                    "title": {
                      "type": "string"
                    },
                    "summary": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "columnId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Which column it sits in on the public board."
                    },
                    "categoryIds": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "draft | in_review | published | archived. Editorial only — never leaves this API."
                    },
                    "sortOrder": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "targetLabel": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Free text, e.g. \"Q3\" — deliberately not a date."
                    },
                    "publishedVersion": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "roadmapId",
                    "companyId",
                    "slug",
                    "title",
                    "summary",
                    "columnId",
                    "categoryIds",
                    "status",
                    "sortOrder",
                    "targetLabel",
                    "publishedVersion",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "summary": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "columnId": {
                    "type": "string"
                  },
                  "categoryIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "in_review",
                      "published",
                      "archived"
                    ]
                  },
                  "sortOrder": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  "targetLabel": {
                    "type": "string",
                    "maxLength": 60
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePlanItem",
        "summary": "Delete an item.",
        "description": "Removes the authoring record. Anything already published stays visible until the next publish.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "id",
                    "deleted"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/boards/{boardId}/publish/preview": {
      "post": {
        "operationId": "previewPlanPublish",
        "summary": "See exactly what publishing would make visible.",
        "description": "A dry run. Nothing changes. Worth calling first from automation, since publishing is the point at which drafts become public and there is no undo beyond republishing.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "diff": {}
                  },
                  "required": [
                    "diff"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/plan/boards/{boardId}/publish": {
      "post": {
        "operationId": "publishPlanBoard",
        "summary": "Publish the board.",
        "description": "Makes published items visible to the delivery API. Call the preview first — this is the moment drafts become public.",
        "tags": [
          "plan"
        ],
        "security": [
          {
            "secretKey": [
              "plan:publish"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "boardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "result": {}
                  },
                  "required": [
                    "result"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/broadcast/plans": {
      "get": {
        "operationId": "listContentPlans",
        "summary": "List content plans.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 25,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "goal": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "pillars": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Themes this plan keeps returning to."
                          },
                          "startDate": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "endDate": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "draft | active | complete | archived"
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "name",
                          "goal",
                          "pillars",
                          "startDate",
                          "endDate",
                          "status",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/broadcast/ideas": {
      "get": {
        "operationId": "listContentIdeas",
        "summary": "List content ideas.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "planId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "suggested",
                "accepted",
                "rejected"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "planId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "title": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "brief": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "pillar": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "source": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "agent | user | learning_loop"
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "suggested | accepted | rejected"
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "planId",
                          "title",
                          "brief",
                          "pillar",
                          "source",
                          "status",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/broadcast/posts": {
      "get": {
        "operationId": "listPosts",
        "summary": "List posts.",
        "description": "Drafts, scheduled and published. Filter by status to get a queue.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "platform",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "x",
                "instagram",
                "tiktok",
                "facebook",
                "reddit",
                "push"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "description": "e.g. draft, scheduled, published, failed",
              "type": "string"
            },
            "description": "e.g. draft, scheduled, published, failed"
          },
          {
            "name": "ideaId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "ideaId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "platform": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "title": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "body": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "threadParts": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Set when the body exceeds one post."
                          },
                          "hashtags": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "media": {
                            "anyOf": [
                              {},
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "destination": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "deepLink": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "scheduledFor": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "publishedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "externalId": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "externalUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "failureReason": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "ideaId",
                          "platform",
                          "title",
                          "body",
                          "threadParts",
                          "hashtags",
                          "media",
                          "destination",
                          "deepLink",
                          "scheduledFor",
                          "status",
                          "publishedAt",
                          "externalId",
                          "externalUrl",
                          "failureReason",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createPost",
        "summary": "Draft a post.",
        "description": "Created as a draft. Set scheduledFor and status to \"scheduled\" to queue it — the dispatcher picks it up from there. Nothing here sends anything itself.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "ideaId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "platform": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "body": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "threadParts": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Set when the body exceeds one post."
                    },
                    "hashtags": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "media": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "destination": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "deepLink": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scheduledFor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "publishedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "failureReason": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "ideaId",
                    "platform",
                    "title",
                    "body",
                    "threadParts",
                    "hashtags",
                    "media",
                    "destination",
                    "deepLink",
                    "scheduledFor",
                    "status",
                    "publishedAt",
                    "externalId",
                    "externalUrl",
                    "failureReason",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": [
                      "x",
                      "instagram",
                      "tiktok",
                      "facebook",
                      "reddit",
                      "push"
                    ]
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000
                  },
                  "hashtags": {
                    "maxItems": 30,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "ideaId": {
                    "type": "string"
                  },
                  "destination": {
                    "description": "push only: the segment to send to.",
                    "type": "string",
                    "maxLength": 300
                  },
                  "deepLink": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "scheduledFor": {
                    "description": "ISO 8601. Omit to leave it unscheduled.",
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  "status": {
                    "default": "draft",
                    "type": "string",
                    "enum": [
                      "draft",
                      "scheduled"
                    ]
                  }
                },
                "required": [
                  "platform",
                  "body",
                  "status"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/broadcast/posts/{postId}": {
      "get": {
        "operationId": "getPost",
        "summary": "Fetch one post.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "ideaId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "platform": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "body": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "threadParts": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Set when the body exceeds one post."
                    },
                    "hashtags": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "media": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "destination": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "deepLink": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scheduledFor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "publishedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "failureReason": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "ideaId",
                    "platform",
                    "title",
                    "body",
                    "threadParts",
                    "hashtags",
                    "media",
                    "destination",
                    "deepLink",
                    "scheduledFor",
                    "status",
                    "publishedAt",
                    "externalId",
                    "externalUrl",
                    "failureReason",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "operationId": "updatePost",
        "summary": "Update or schedule a post.",
        "description": "Only unsent posts can be edited.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "ideaId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "platform": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "title": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "body": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "threadParts": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Set when the body exceeds one post."
                    },
                    "hashtags": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "media": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "destination": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "deepLink": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scheduledFor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "status": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "publishedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalId": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalUrl": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "failureReason": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "ideaId",
                    "platform",
                    "title",
                    "body",
                    "threadParts",
                    "hashtags",
                    "media",
                    "destination",
                    "deepLink",
                    "scheduledFor",
                    "status",
                    "publishedAt",
                    "externalId",
                    "externalUrl",
                    "failureReason",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000
                  },
                  "hashtags": {
                    "maxItems": 30,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "destination": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "deepLink": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "scheduledFor": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "scheduled",
                      "cancelled"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePost",
        "summary": "Delete an unsent post.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean",
                      "const": true
                    }
                  },
                  "required": [
                    "id",
                    "deleted"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/broadcast/channels": {
      "get": {
        "operationId": "listChannels",
        "summary": "List connected channels.",
        "description": "Which platforms are connected and whether their credentials still work.",
        "tags": [
          "broadcast"
        ],
        "security": [
          {
            "secretKey": [
              "broadcast:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "platform": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "handle": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "displayName": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "status": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "connected | expired | revoked | error"
                          },
                          "connectedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "lastCheckedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "platform",
                          "handle",
                          "displayName",
                          "status",
                          "connectedAt",
                          "lastCheckedAt",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/v1/companies/{companyId}/context/brand-kit": {
      "get": {
        "operationId": "getBrandKit",
        "summary": "Fetch the brand kit.",
        "description": "Voice, colours and art direction. Read this before generating anything.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "companyId": {
                          "type": "string"
                        },
                        "voiceTone": {
                          "anyOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Descriptors, e.g. ['direct', 'wry']."
                        },
                        "voiceGuidelines": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Prose do/don't rules the generators follow."
                        },
                        "voiceExamples": {
                          "anyOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Phrases that sound like this company."
                        },
                        "avoidWords": {
                          "anyOf": [
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Words and phrases never to use."
                        },
                        "colors": {
                          "anyOf": [
                            {},
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "fonts": {
                          "anyOf": [
                            {},
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "artStyle": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "artDirection": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "imageryNotes": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "context": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Anything else a writer should know."
                        },
                        "extractedFrom": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "Where this was read from, if it was extracted."
                        },
                        "lastExtractedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "createdAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "updatedAt": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "companyId",
                        "voiceTone",
                        "voiceGuidelines",
                        "voiceExamples",
                        "avoidWords",
                        "colors",
                        "fonts",
                        "artStyle",
                        "artDirection",
                        "imageryNotes",
                        "context",
                        "extractedFrom",
                        "lastExtractedAt",
                        "createdAt",
                        "updatedAt"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "patch": {
        "operationId": "updateBrandKit",
        "summary": "Update the brand kit.",
        "description": "Creates it if the company has none. Changing voice guidelines changes every future draft.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "voiceTone": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Descriptors, e.g. ['direct', 'wry']."
                    },
                    "voiceGuidelines": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Prose do/don't rules the generators follow."
                    },
                    "voiceExamples": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Phrases that sound like this company."
                    },
                    "avoidWords": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Words and phrases never to use."
                    },
                    "colors": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "fonts": {
                      "anyOf": [
                        {},
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "artStyle": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "artDirection": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "imageryNotes": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "context": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Anything else a writer should know."
                    },
                    "extractedFrom": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Where this was read from, if it was extracted."
                    },
                    "lastExtractedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "voiceTone",
                    "voiceGuidelines",
                    "voiceExamples",
                    "avoidWords",
                    "colors",
                    "fonts",
                    "artStyle",
                    "artDirection",
                    "imageryNotes",
                    "context",
                    "extractedFrom",
                    "lastExtractedAt",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "voiceTone": {
                    "description": "Descriptors, e.g. ['direct', 'wry']. Replaces the whole list.",
                    "maxItems": 20,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "voiceGuidelines": {
                    "type": "string",
                    "maxLength": 8000
                  },
                  "voiceExamples": {
                    "description": "Replaces the whole list.",
                    "maxItems": 50,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 500
                    }
                  },
                  "avoidWords": {
                    "description": "Replaces the whole list.",
                    "maxItems": 200,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 60
                    }
                  },
                  "artStyle": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "artDirection": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "imageryNotes": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "context": {
                    "type": "string",
                    "maxLength": 8000
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/context/content-types": {
      "get": {
        "operationId": "listContentTypes",
        "summary": "List content types.",
        "description": "The kinds of post this company publishes, and how each should be written.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "description": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "guidance": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "How to write this kind of post."
                          },
                          "defaultPlatforms": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "cadence": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "active": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "name",
                          "description",
                          "guidance",
                          "defaultPlatforms",
                          "cadence",
                          "active",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "operationId": "createContentType",
        "summary": "Add a content type.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "guidance": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "How to write this kind of post."
                    },
                    "defaultPlatforms": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "cadence": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "active": {
                      "anyOf": [
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "name",
                    "description",
                    "guidance",
                    "defaultPlatforms",
                    "cadence",
                    "active",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "guidance": {
                    "description": "How this kind of post should read.",
                    "type": "string",
                    "maxLength": 4000
                  },
                  "defaultPlatforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "instagram",
                        "tiktok",
                        "facebook",
                        "reddit"
                      ]
                    }
                  },
                  "cadence": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "active": {
                    "default": true,
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "active"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/context/content-types/{contentTypeId}": {
      "patch": {
        "operationId": "updateContentType",
        "summary": "Update a content type.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contentTypeId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "companyId": {
                      "type": "string"
                    },
                    "name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "description": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "guidance": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "How to write this kind of post."
                    },
                    "defaultPlatforms": {
                      "anyOf": [
                        {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "cadence": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "active": {
                      "anyOf": [
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "companyId",
                    "name",
                    "description",
                    "guidance",
                    "defaultPlatforms",
                    "cadence",
                    "active",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "guidance": {
                    "type": "string",
                    "maxLength": 4000
                  },
                  "defaultPlatforms": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "x",
                        "instagram",
                        "tiktok",
                        "facebook",
                        "reddit"
                      ]
                    }
                  },
                  "cadence": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "active": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/v1/companies/{companyId}/context/goals": {
      "get": {
        "operationId": "listBrandGoals",
        "summary": "List brand goals.",
        "tags": [
          "context"
        ],
        "security": [
          {
            "secretKey": [
              "context:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "schema": {
              "default": 50,
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "https://json-schema.org/draft/2020-12/schema",
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "companyId": {
                            "type": "string"
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "metricKey": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "comparator": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "at_least | at_most"
                          },
                          "target": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "period": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "week | month | quarter"
                          },
                          "active": {
                            "anyOf": [
                              {
                                "type": "boolean"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "companyId",
                          "name",
                          "metricKey",
                          "comparator",
                          "target",
                          "period",
                          "active",
                          "createdAt",
                          "updatedAt"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "items"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "The request was malformed.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "Missing or invalid key.",
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "description": "The key may not act on this resource.",
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "description": "No such resource.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "Too many requests.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Error": {
        "description": "Something went wrong.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "errors"
              ],
              "properties": {
                "errors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "code",
                      "message"
                    ],
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "bad_request",
                          "unauthorised",
                          "forbidden_origin",
                          "not_found",
                          "method_not_allowed",
                          "rate_limited",
                          "payload_too_large",
                          "internal"
                        ],
                        "description": "Stable, machine-readable. Branch on this, never on message."
                      },
                      "message": {
                        "type": "string"
                      },
                      "retryAfter": {
                        "type": "integer",
                        "description": "Seconds. Only on rate_limited."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "secretKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A secret key, `sk_live_…`. Server-side only — never ship it to a browser."
      }
    }
  }
}