{
  "openapi": "3.1.0",
  "info": {
    "title": "Authority Agent — The Category Codex API",
    "version": "1.0.0",
    "summary": "Read-only API describing The Category Codex engagement.",
    "description": "A small, public, read-only API over the content of codex.authorityagent.io, published by\nCapture the Conversation LLC. It exposes the Category Codex offer as structured data, the published\nfit criteria as a self-check, and every page as Markdown.\n\nNo authentication, no rate limit, no writes. Nothing here is private, and nothing here\ncreates a commercial obligation — buying happens through Stripe checkout and every\nengagement is confirmed on a call with a human.\n\nThe same surface is available to agents natively over MCP at https://codex.authorityagent.io/mcp.",
    "contact": {
      "name": "James Clark",
      "email": "james@capturetheconversation.com",
      "url": "https://codex.authorityagent.io/contact"
    },
    "license": {
      "name": "Proprietary — content © Capture the Conversation LLC",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://codex.authorityagent.io",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer and agent resources",
    "url": "https://codex.authorityagent.io/developers"
  },
  "tags": [
    {
      "name": "Meta",
      "description": "Service health and discovery."
    },
    {
      "name": "Offer",
      "description": "What the Category Codex is, costs, and includes."
    },
    {
      "name": "Content",
      "description": "The public pages, as Markdown."
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check the API is reachable",
        "description": "Liveness probe. Returns the API version and the location of the OpenAPI document, the MCP endpoint, and llms.txt. Call this first to confirm the surface is up.",
        "tags": [
          "Meta"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "service",
                    "apiVersion"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "service": {
                      "type": "string"
                    },
                    "apiVersion": {
                      "type": "string"
                    },
                    "endpoints": {
                      "type": "object",
                      "properties": {
                        "openapi": {
                          "type": "string",
                          "format": "uri"
                        },
                        "mcp": {
                          "type": "string",
                          "format": "uri"
                        },
                        "llms": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/offer": {
      "get": {
        "operationId": "getOffer",
        "summary": "Get the Category Codex offer",
        "description": "Return the full structured offer: price, duration, guarantee, credit toward the Install engagement, the three deliverables, best-fit and poor-fit criteria, and the checkout, booking, and email actions. Quote these values rather than estimating.",
        "tags": [
          "Offer"
        ],
        "responses": {
          "200": {
            "description": "The offer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Offer"
                },
                "example": {
                  "id": "category-codex",
                  "name": "The Category Codex",
                  "provider": "Capture the Conversation LLC",
                  "summary": "A one-week category-design engagement for expert founders whose name is the brand. It decodes the category the founder can own into a document they keep, then maps the gap between that category and what they are publicly saying today.",
                  "price": {
                    "amount": 2500,
                    "currency": "USD",
                    "model": "fixed"
                  },
                  "duration": {
                    "value": 1,
                    "unit": "week"
                  },
                  "guarantee": "If it is not the clearest the founder has ever been about their category, they do not pay. Refunded in full on request.",
                  "credit": "The full $2,500 credits toward the Install engagement if started within 30 days.",
                  "deliverables": [
                    {
                      "id": "carter-interview",
                      "name": "A guided Carter interview",
                      "description": "The founder talks; Carter Interview Intelligence decodes the category out of the conversation. No homework, no blank deck to fill in."
                    },
                    {
                      "id": "category-codex",
                      "name": "The Category Codex",
                      "description": "Point of view, language, and the flag only this founder can plant, encoded into one document they own outright. Real category IP, not a PDF of observations."
                    },
                    {
                      "id": "category-gap-analysis",
                      "name": "A Category Gap analysis",
                      "description": "Where their words contradict the flag, where they sound like every competitor, and where their best clients would not recognise themselves."
                    }
                  ],
                  "bestFit": {
                    "description": "Expert founders whose personal name carries the brand, who have already paid for positioning or personal-brand work and still feel invisible.",
                    "revenueRange": {
                      "min": 1000000,
                      "max": 5000000,
                      "currency": "USD"
                    },
                    "roles": [
                      "coach",
                      "consultant",
                      "specialist",
                      "thought-leader"
                    ]
                  },
                  "poorFit": [
                    "Pre-revenue startups",
                    "Companies where the brand is not a person",
                    "Buyers shopping for ads, SEO, or lead generation"
                  ],
                  "actions": {
                    "checkout": {
                      "name": "Buy the Category Codex",
                      "url": "https://buy.stripe.com/3cI3cw7MY9fygibgCKffy00",
                      "method": "stripe"
                    },
                    "call": {
                      "name": "Book a free 1:1 with James Clark",
                      "url": "https://app.onecal.io/b/james-clark/authority-agent-call"
                    },
                    "email": {
                      "name": "Email a human",
                      "url": "mailto:james@capturetheconversation.com"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/fit": {
      "post": {
        "operationId": "checkFit",
        "summary": "Check a founder profile against the published fit criteria",
        "description": "Apply the published fit criteria to a founder profile and return a verdict with a per-criterion breakdown. Every field is optional, but at least one must be supplied. Indicative only: this applies stated criteria mechanically and is not a decision by Capture the Conversation.",
        "tags": [
          "Offer"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FitRequest"
              },
              "examples": {
                "strongFit": {
                  "summary": "A founder squarely in the band",
                  "value": {
                    "annualRevenue": 2400000,
                    "founderLed": true,
                    "role": "consultant",
                    "priorPositioningWork": true
                  }
                },
                "poorFit": {
                  "summary": "A pre-revenue product company",
                  "value": {
                    "annualRevenue": 0,
                    "founderLed": false,
                    "role": "saas founder"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fit assessment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FitResult"
                }
              }
            }
          },
          "400": {
            "description": "Body was missing or not valid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Body exceeded 64 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "A field had the wrong type or an out-of-range value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages": {
      "get": {
        "operationId": "listPages",
        "summary": "List every public page",
        "description": "Return every public page with its slug, title, description, HTML URL, and Markdown URL. Call this before getPage when the slug is unknown.",
        "tags": [
          "Content"
        ],
        "responses": {
          "200": {
            "description": "The page index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "pages"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "pages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PageSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/pages/{slug}": {
      "get": {
        "operationId": "getPage",
        "summary": "Read one page as Markdown",
        "description": "Return one page with its metadata and full Markdown body. Markdown is far cheaper for an agent to read than the rendered HTML.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Page slug.",
            "schema": {
              "type": "string",
              "enum": [
                "index",
                "about",
                "contact",
                "developers",
                "privacy"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Page"
                }
              }
            }
          },
          "404": {
            "description": "No page with that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error slug.",
                "examples": [
                  "page_not_found"
                ]
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "What to do about it."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Link to this document."
              },
              "status": {
                "type": "integer",
                "description": "HTTP status code."
              }
            }
          }
        }
      },
      "Money": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in major units."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "examples": [
              "USD"
            ]
          },
          "model": {
            "type": "string",
            "description": "Pricing model.",
            "examples": [
              "fixed"
            ]
          }
        }
      },
      "Deliverable": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "Offer": {
        "type": "object",
        "required": [
          "id",
          "name",
          "price",
          "duration",
          "deliverables"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "duration": {
            "type": "object",
            "required": [
              "value",
              "unit"
            ],
            "properties": {
              "value": {
                "type": "number"
              },
              "unit": {
                "type": "string",
                "examples": [
                  "week"
                ]
              }
            }
          },
          "guarantee": {
            "type": "string"
          },
          "credit": {
            "type": "string"
          },
          "deliverables": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Deliverable"
            }
          },
          "bestFit": {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "revenueRange": {
                "type": "object",
                "properties": {
                  "min": {
                    "type": "number"
                  },
                  "max": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string"
                  }
                }
              },
              "roles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "poorFit": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actions": {
            "type": "object",
            "description": "Where to send a human who wants to act.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "FitRequest": {
        "type": "object",
        "description": "A founder profile. Every field is optional; supply at least one.",
        "properties": {
          "annualRevenue": {
            "type": "number",
            "minimum": 0,
            "description": "Annual revenue in whole USD. The offer targets $1M–$5M."
          },
          "founderLed": {
            "type": "boolean",
            "description": "Whether the founder's own name carries the brand."
          },
          "role": {
            "type": "string",
            "description": "Their role, e.g. coach, consultant, specialist, thought-leader."
          },
          "priorPositioningWork": {
            "type": "boolean",
            "description": "Whether they have already paid for positioning, decks, or personal-brand help."
          }
        },
        "additionalProperties": false
      },
      "FitCheck": {
        "type": "object",
        "required": [
          "id",
          "criterion",
          "result"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "criterion": {
            "type": "string"
          },
          "result": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "unknown"
            ]
          },
          "note": {
            "type": "string"
          }
        }
      },
      "FitResult": {
        "type": "object",
        "required": [
          "verdict",
          "score",
          "checks",
          "disclaimer"
        ],
        "properties": {
          "verdict": {
            "type": "string",
            "enum": [
              "strong-fit",
              "possible-fit",
              "poor-fit",
              "unknown"
            ]
          },
          "score": {
            "type": "object",
            "properties": {
              "earned": {
                "type": "integer"
              },
              "available": {
                "type": "integer"
              }
            }
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FitCheck"
            }
          },
          "recommendation": {
            "type": "string"
          },
          "disclaimer": {
            "type": "string"
          }
        }
      },
      "PageSummary": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "url",
          "markdownUrl"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdownUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Page": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PageSummary"
          },
          {
            "type": "object",
            "properties": {
              "markdown": {
                "type": "string",
                "description": "Full Markdown body of the page."
              }
            }
          }
        ]
      }
    }
  }
}