{
  "openapi": "3.0.0",
  "info": {
    "title": "Defrag API",
    "version": "1.0.0",
    "description": "Public read API for the Defrag publication (`/api/articles`) plus the auth-gated internal API used by the brand-os-seed and signal-seed skills (`/api/v1/*`). Excluded by design: MCP routes (JSON-RPC, separate protocol with runtime tools/list discovery) and `/api/stripe/webhook` (service-to-service, signature-validated)."
  },
  "servers": [
    {
      "url": "https://thedefrag.ai",
      "description": "Production publication"
    },
    {
      "url": "https://dfp.thedefrag.ai",
      "description": "Production internal API"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "DEFRAG_API_KEY (format `dfp_<32-byte-hex>`) passed as `Authorization: Bearer <key>`. Supabase session cookies also authenticate when calling from a browser context. Resolved via resolveDefragUser() in src/lib/defrag-auth.ts."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sb-access-token",
        "description": "Supabase session cookie. Used by admin endpoints (api-key, grant-self, toggle-entitlement) where the Bearer token alone is not sufficient."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "ArticleErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error",
          "message"
        ]
      },
      "ArticleListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "eyebrow": {
                  "type": "string"
                },
                "category": {
                  "type": "string",
                  "enum": [
                    "loop",
                    "install",
                    "pattern",
                    "read"
                  ]
                },
                "publishedAt": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "hub": {
                  "type": "string",
                  "nullable": true
                },
                "spokes": {
                  "type": "array",
                  "nullable": true,
                  "items": {
                    "type": "string"
                  }
                },
                "readingMinutes": {
                  "type": "integer"
                },
                "urls": {
                  "type": "object",
                  "properties": {
                    "html": {
                      "type": "string",
                      "format": "uri"
                    },
                    "json": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "required": [
                    "html",
                    "json"
                  ]
                }
              },
              "required": [
                "slug",
                "title",
                "eyebrow",
                "category",
                "publishedAt",
                "summary",
                "readingMinutes",
                "urls"
              ]
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer"
              },
              "filters": {
                "type": "object",
                "properties": {
                  "since": {
                    "type": "string",
                    "nullable": true
                  },
                  "category": {
                    "type": "string",
                    "nullable": true
                  },
                  "hub": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "since",
                  "category",
                  "hub"
                ]
              }
            },
            "required": [
              "count",
              "filters"
            ]
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ArticleDetailResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "eyebrow": {
                "type": "string"
              },
              "category": {
                "type": "string",
                "enum": [
                  "loop",
                  "install",
                  "pattern",
                  "read"
                ]
              },
              "publishedAt": {
                "type": "string"
              },
              "summary": {
                "type": "string"
              },
              "hub": {
                "type": "string",
                "nullable": true
              },
              "spokes": {
                "type": "array",
                "nullable": true,
                "items": {
                  "type": "string"
                }
              },
              "readingMinutes": {
                "type": "integer"
              },
              "urls": {
                "type": "object",
                "properties": {
                  "html": {
                    "type": "string",
                    "format": "uri"
                  },
                  "json": {
                    "type": "string",
                    "format": "uri"
                  }
                },
                "required": [
                  "html",
                  "json"
                ]
              },
              "body": {
                "type": "string"
              },
              "bodyFormat": {
                "type": "string",
                "enum": [
                  "markdown"
                ]
              }
            },
            "required": [
              "slug",
              "title",
              "eyebrow",
              "category",
              "publishedAt",
              "summary",
              "readingMinutes",
              "urls",
              "body",
              "bodyFormat"
            ]
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "status",
          "timestamp"
        ]
      },
      "EmailCaptureBody": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "device_token": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ]
      },
      "EmailCaptureResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "ok"
        ]
      },
      "DefragOsIntakeBody": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "linkedin": {
            "type": "string"
          },
          "twitter": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "youtube": {
            "type": "string"
          },
          "substack": {
            "type": "string"
          },
          "instagram": {
            "type": "string"
          },
          "tiktok": {
            "type": "string"
          },
          "freestyle": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ]
      },
      "DefragOsIntakeResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "ok"
        ]
      },
      "ProfilePostBody": {
        "type": "object",
        "properties": {
          "profile_type": {
            "type": "string",
            "enum": [
              "subdomain",
              "signal",
              "defrag_os"
            ]
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-z0-9-]+$"
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "image_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          }
        },
        "required": [
          "profile_type",
          "slug",
          "data"
        ]
      },
      "ProfilePatchBody": {
        "type": "object",
        "properties": {
          "image_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          }
        }
      },
      "ProfileWriteResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-z0-9-]+$"
          },
          "version": {
            "type": "integer"
          },
          "created": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "id",
          "slug",
          "version",
          "created"
        ]
      },
      "ProfilePatchResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "slug": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-z0-9-]+$"
          },
          "image_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          }
        },
        "required": [
          "ok",
          "slug",
          "image_url"
        ]
      },
      "ProfileGetResponse": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "minLength": 1,
            "pattern": "^[a-z0-9-]+$"
          },
          "profile_type": {
            "type": "string",
            "enum": [
              "subdomain",
              "signal",
              "defrag_os"
            ]
          },
          "version": {
            "type": "integer"
          },
          "published_at": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "image_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          },
          "data": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          }
        },
        "required": [
          "slug",
          "profile_type",
          "version",
          "published_at",
          "image_url",
          "data"
        ]
      },
      "ScrapePostBody": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "minLength": 1
          },
          "external_handle": {
            "type": "string",
            "minLength": 1
          },
          "context": {
            "type": "string",
            "enum": [
              "subdomain",
              "signal",
              "research",
              "ai-ecosystem"
            ]
          },
          "raw_json": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          },
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "signal_slug": {
            "type": "string"
          },
          "scraped_at": {
            "type": "string",
            "format": "date-time"
          },
          "image_url": {
            "type": "string",
            "nullable": true,
            "format": "uri"
          }
        },
        "required": [
          "platform",
          "external_handle",
          "context",
          "raw_json"
        ]
      },
      "ScrapePostResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "ok",
          "id",
          "created_at"
        ]
      },
      "ScrapeListResponse": {
        "type": "object",
        "properties": {
          "scrapes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "platform": {
                  "type": "string"
                },
                "externalHandle": {
                  "type": "string"
                },
                "context": {
                  "type": "string"
                },
                "signalSlug": {
                  "type": "string",
                  "nullable": true
                },
                "scrapedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "rawJson": {
                  "type": "object",
                  "additionalProperties": {
                    "nullable": true
                  }
                }
              },
              "required": [
                "id",
                "platform",
                "externalHandle",
                "context",
                "signalSlug",
                "scrapedAt",
                "createdAt"
              ]
            }
          },
          "count": {
            "type": "integer"
          }
        },
        "required": [
          "scrapes",
          "count"
        ]
      },
      "DigestPostBody": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "summary": {
            "type": "string",
            "minLength": 1
          },
          "digest_markdown": {
            "type": "string",
            "minLength": 1
          },
          "issued_at": {
            "type": "string",
            "format": "date-time"
          },
          "human_link": {
            "type": "string",
            "maxLength": 500,
            "format": "uri"
          }
        },
        "required": [
          "id",
          "title",
          "summary",
          "digest_markdown",
          "issued_at"
        ]
      },
      "DigestPostResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "id",
          "created_at",
          "updated"
        ]
      },
      "DigestListResponse": {
        "type": "object",
        "properties": {
          "digests": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "digestMarkdown": {
                  "type": "string"
                },
                "issuedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "humanLink": {
                  "type": "string",
                  "nullable": true
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "title",
                "summary",
                "digestMarkdown",
                "issuedAt",
                "humanLink",
                "createdAt"
              ]
            }
          },
          "count": {
            "type": "integer"
          }
        },
        "required": [
          "digests",
          "count"
        ]
      },
      "DigestDetailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "digestMarkdown": {
            "type": "string"
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "humanLink": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "title",
          "summary",
          "digestMarkdown",
          "issuedAt",
          "humanLink",
          "createdAt"
        ]
      },
      "JobInput": {
        "type": "object",
        "properties": {
          "instagram": {
            "type": "string"
          },
          "admired_handles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "linkedin": {
            "type": "string"
          },
          "youtube": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "design_prompt": {
            "type": "string"
          },
          "chosen_slug": {
            "type": "string"
          }
        }
      },
      "JobPostResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "job_id": {
            "type": "string",
            "format": "uuid"
          },
          "job_type": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "job_id",
          "job_type"
        ]
      },
      "JobListResponse": {
        "type": "object",
        "properties": {
          "jobs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "jobType": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "finishedAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "jobType",
                "status",
                "createdAt",
                "finishedAt"
              ]
            }
          }
        },
        "required": [
          "jobs"
        ]
      },
      "JobDetailResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "jobType": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          },
          "output": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "nullable": true
            }
          },
          "error": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "jobType",
          "status",
          "createdAt",
          "finishedAt"
        ]
      },
      "SuggestSlugBody": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "instagram_handle": {
            "type": "string"
          }
        }
      },
      "SuggestSlugResponse": {
        "type": "object",
        "properties": {
          "suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "suggestions"
        ]
      },
      "AgentUpdatesListResponse": {
        "type": "object",
        "properties": {
          "updates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "step": {
                  "type": "integer"
                },
                "align": {
                  "type": "string"
                },
                "eyebrow": {
                  "type": "string"
                },
                "headline": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "attribution": {
                  "type": "string"
                },
                "published": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "updatedAt": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "step",
                "align",
                "eyebrow",
                "headline",
                "body",
                "attribution",
                "published",
                "createdAt",
                "updatedAt"
              ]
            }
          }
        },
        "required": [
          "updates"
        ]
      },
      "DebugMeResponse": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "nullable": true,
            "format": "email"
          },
          "via": {
            "type": "string",
            "enum": [
              "bearer",
              "session"
            ]
          }
        },
        "required": [
          "userId",
          "email"
        ]
      },
      "ApiKeyResponse": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "message"
        ]
      },
      "GrantSelfResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "ok"
        ]
      },
      "ToggleEntitlementBody": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "format": "uuid"
          },
          "grant": {
            "type": "boolean"
          }
        },
        "required": [
          "userId",
          "grant"
        ]
      },
      "ToggleEntitlementResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "userId": {
            "type": "string",
            "format": "uuid"
          },
          "grant": {
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "userId",
          "grant"
        ]
      },
      "StripeCheckoutBody": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string",
            "enum": [
              "pro",
              "premium"
            ]
          },
          "device_token": {
            "type": "string"
          }
        },
        "required": [
          "tier"
        ]
      },
      "StripeCheckoutResponse": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "ok",
              "url"
            ]
          },
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "error": {
                "type": "string"
              }
            },
            "required": [
              "ok",
              "error"
            ]
          }
        ]
      },
      "StripePortalBody": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "switch_to": {
            "type": "string",
            "enum": [
              "pro",
              "premium"
            ]
          }
        },
        "required": [
          "email"
        ]
      },
      "StripePortalResponse": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "ok",
              "url"
            ]
          },
          {
            "type": "object",
            "properties": {
              "ok": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "error": {
                "type": "string"
              }
            },
            "required": [
              "ok",
              "error"
            ]
          }
        ]
      },
      "SignOutResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "ok"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/articles": {
      "get": {
        "summary": "List published articles",
        "tags": [
          "articles"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "since",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "loop",
                "install",
                "pattern",
                "read"
              ]
            },
            "required": false,
            "name": "category",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "hub",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Article list with metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/articles/{slug}": {
      "get": {
        "summary": "Fetch a single article including full markdown body",
        "tags": [
          "articles"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": true,
            "name": "slug",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Single article with full body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "No article with that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticleErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Liveness check",
        "tags": [
          "health"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/healthz": {
      "get": {
        "summary": "v1 liveness check",
        "tags": [
          "health"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/email-capture": {
      "post": {
        "summary": "Subscribe an email address",
        "tags": [
          "email-capture"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailCaptureBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email captured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailCaptureResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "head": {
        "summary": "Check if an email is already subscribed",
        "description": "Returns 200 if subscribed, 404 if not. Pass email as the `email` query param.",
        "tags": [
          "email-capture"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "email"
            },
            "required": true,
            "name": "email",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Email is subscribed."
          },
          "404": {
            "description": "Email is not subscribed."
          }
        }
      }
    },
    "/api/defrag-os/intake": {
      "post": {
        "summary": "Defrag OS onboarding intake",
        "tags": [
          "defrag-os"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DefragOsIntakeBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Intake captured; draft profile created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DefragOsIntakeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/feed": {
      "get": {
        "summary": "Publication feed (RSS / Atom / JSON)",
        "tags": [
          "feed"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "rss",
                "atom",
                "json"
              ]
            },
            "required": false,
            "name": "format",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Feed body.",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/atom+xml": {
                "schema": {
                  "type": "string"
                }
              },
              "application/feed+json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/profiles": {
      "post": {
        "summary": "Create or update a synthesized profile",
        "description": "Used by the defrag-brand-os-seed and defrag-signal-seed skills. On conflict (existing slug), increments version and updates data + published_at. image_url is optional; pass null to explicitly unset on update, omit to leave the existing value alone.",
        "tags": [
          "profiles"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfilePostBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileWriteResponse"
                }
              }
            }
          },
          "201": {
            "description": "Profile created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileWriteResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/profiles/{slug}": {
      "get": {
        "summary": "Fetch a published profile by slug",
        "description": "Public — no auth required. Returns 404 if slug not found or publishedAt is null.",
        "tags": [
          "profiles"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[a-z0-9-]+$"
            },
            "required": true,
            "name": "slug",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Published profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileGetResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update image_url on an existing profile",
        "description": "Image-only update endpoint. Used by the upload utility (see ADR 0017) after uploading to Vercel Blob. Pass image_url: null to unset. Does not bump synthesis version.",
        "tags": [
          "profiles"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[a-z0-9-]+$"
            },
            "required": true,
            "name": "slug",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfilePatchBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "image_url updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfilePatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scrapes": {
      "get": {
        "summary": "List raw scrapes",
        "description": "Used by defrag-brand-os-seed and defrag-signal-seed to fetch unincorporated scrapes for incremental synthesis.",
        "tags": [
          "scrapes"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "signal_slug",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "since",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "subdomain",
                "signal",
                "research",
                "ai-ecosystem"
              ]
            },
            "required": false,
            "name": "context",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            },
            "required": false,
            "name": "include_raw",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "required": false,
            "name": "order",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Scrape list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScrapeListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Ingest a raw scrape payload",
        "description": "Writes a row to defrag_scrapes. The optional image_url body field is merged into raw_json under the 'image_url' key so downstream profile synthesis can pick it up.",
        "tags": [
          "scrapes"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScrapePostBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scrape created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScrapePostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/digests": {
      "get": {
        "summary": "List published, non-revoked digests",
        "description": "Public. Used by the /agents/updates page and the defrag_get_ai_ecosystem_updates MCP tool.",
        "tags": [
          "digests"
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            },
            "required": false,
            "name": "order",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Digest list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Publish a weekly digest",
        "description": "Used by the defrag-digest-publish skill (called from the infra-improver agent's Step 5b). Idempotent on `id`: existing rows are updated (200); new rows are created (201). Published rows surface on agents.thedefrag.ai/updates and via the `defrag_get_ai_ecosystem_updates` MCP tool.",
        "tags": [
          "digests"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DigestPostBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Digest updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestPostResponse"
                }
              }
            }
          },
          "201": {
            "description": "Digest created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestPostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/digests/{id}": {
      "get": {
        "summary": "Fetch a single non-revoked digest by id",
        "description": "Public. Used by the /agents/updates/[id] detail page.",
        "tags": [
          "digests"
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Digest detail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DigestDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs": {
      "post": {
        "summary": "Submit a subdomain generation job",
        "tags": [
          "jobs"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JobInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Job created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobPostResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List the authenticated user's jobs",
        "tags": [
          "jobs"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Jobs list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "Fetch a single job",
        "tags": [
          "jobs"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Job detail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobDetailResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/suggest-slug": {
      "post": {
        "summary": "Suggest slug candidates from job inputs",
        "tags": [
          "jobs"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestSlugBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Slug suggestions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestSlugResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent-updates": {
      "get": {
        "summary": "Fetch published agent updates ordered by step",
        "tags": [
          "agents"
        ],
        "responses": {
          "200": {
            "description": "Agent updates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentUpdatesListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/debug/me": {
      "get": {
        "summary": "Echo the resolved authenticated user",
        "description": "Development helper to verify the auth pattern is working.",
        "tags": [
          "debug"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Resolved user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DebugMeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/api-key": {
      "post": {
        "summary": "Generate or regenerate the caller's API key",
        "description": "Returns the plaintext key once. Server stores only the SHA-256 hash. Requires Supabase session.",
        "tags": [
          "admin"
        ],
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "API key issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/grant-self": {
      "post": {
        "summary": "Grant the calling user the entitlement",
        "tags": [
          "admin"
        ],
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Entitlement granted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantSelfResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/admin/toggle-entitlement": {
      "post": {
        "summary": "Admin-only: toggle a user's entitlement",
        "tags": [
          "admin"
        ],
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToggleEntitlementBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Entitlement toggled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToggleEntitlementResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/stripe/checkout": {
      "post": {
        "summary": "Create a Stripe Checkout session",
        "tags": [
          "stripe"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StripeCheckoutBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StripeCheckoutResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/stripe/portal": {
      "post": {
        "summary": "Create a Stripe Billing Portal session",
        "tags": [
          "stripe"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StripePortalBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Portal URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StripePortalResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/sign-out": {
      "get": {
        "summary": "Sign out and redirect to the auth surface",
        "description": "GET (not POST) because cross-subdomain sign-out is initiated from a Link or anchor href. Clears the Supabase session cookie and redirects to NEXT_PUBLIC_AUTH_URL/sign-in.",
        "tags": [
          "auth"
        ],
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect after sign-out."
          }
        }
      }
    },
    "/api/auth/signout": {
      "post": {
        "summary": "Legacy sign-out alias",
        "description": "Kept for back-compat with older clients. New clients should use /api/auth/sign-out.",
        "tags": [
          "auth"
        ],
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Signed out.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignOutResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}