{
  "openapi": "3.1.0",
  "info": {
    "title": "Hopeful Child educator brief",
    "version": "1.1.0",
    "description": "Paste a bill or school policy (200 to 60,000 characters) and get a parent briefing or a classroom outline. Quotas: free without a key, 3 a day per visitor; Family, Classroom, and School plans 50 a day (per license, or per seat for School). Quotas reset at midnight America/Phoenix. API keys (Classroom and School only) are created at https://hopefulchild.com/api-key and sent as Authorization: Bearer hck_live_... The tool reads only the text you send (the first 20,000 and last 4,000 characters of long text). It does not fetch URLs or look up bills. Nonpartisan. Not legal advice. Do not send student records.",
    "contact": {
      "email": "hope@hopefulchild.com"
    }
  },
  "servers": [
    {
      "url": "https://hopefulchild.com"
    }
  ],
  "paths": {
    "/api/tools/educator-brief": {
      "get": {
        "operationId": "getEducatorBriefStatus",
        "summary": "Quota and self-description",
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Status"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createEducatorBrief",
        "summary": "Make a parent briefing or classroom outline",
        "security": [
          {},
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "invalid key (code from key lookup) or plan_inactive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "400": {
            "description": "invalid_input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "ok": false,
                  "code": "invalid_input",
                  "error": "That is a little short. Paste at least a full paragraph of the bill or policy."
                }
              }
            }
          },
          "413": {
            "description": "too_long",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "not_policy or gate_failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota, cap, or rate_limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "ok": false,
                  "code": "quota",
                  "error": "You have used today's three free briefs. They come back tomorrow. Classroom gives you 50 a day.",
                  "upgradeUrl": "https://hopefulchild.com/subscribe?plan=classroom&from=educator-brief"
                }
              }
            }
          },
          "502": {
            "description": "upstream",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "paused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "timeout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/keys": {
      "get": {
        "operationId": "getApiKeyMeta",
        "summary": "Show the plan and when the current key was created (never the key)",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Key metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "plan": {
                      "type": "string"
                    },
                    "key": {
                      "type": "null"
                    },
                    "createdAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create (or replace) the API key for this Classroom license or School seat; shown once",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "New key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "key": {
                      "type": "string"
                    },
                    "createdAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "plan_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "paused",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "revokeApiKey",
        "summary": "Revoke the API key",
        "security": [
          {
            "session": []
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "sign_in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Classroom or School key. Format hck_live_ followed by a secret."
      },
      "session": {
        "type": "apiKey",
        "in": "cookie",
        "name": "hc_license",
        "description": "Paid license cookie set on hopefulchild.com after checkout, restore, or a seat sign-in link."
      }
    },
    "schemas": {
      "Request": {
        "type": "object",
        "required": [
          "text",
          "output"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 200,
            "maxLength": 60000
          },
          "output": {
            "type": "string",
            "enum": [
              "parent",
              "classroom"
            ]
          },
          "label": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional name for the bill or policy."
          },
          "gradeBand": {
            "type": "string",
            "enum": [
              "5",
              "8",
              "12"
            ],
            "default": "8"
          },
          "minutes": {
            "type": "integer",
            "enum": [
              30,
              45
            ],
            "default": 45
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "es"
            ],
            "default": "en"
          }
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "openapi": {
            "type": "string"
          },
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "family",
              "classroom",
              "school"
            ]
          },
          "remainingToday": {
            "type": "integer"
          },
          "resetAt": {
            "type": "string"
          },
          "limits": {
            "type": "object",
            "properties": {
              "minChars": {
                "type": "integer"
              },
              "maxChars": {
                "type": "integer"
              },
              "readChars": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Success": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "output": {
            "type": "string"
          },
          "result": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ParentBriefing"
              },
              {
                "$ref": "#/components/schemas/ClassroomOutline"
              }
            ]
          },
          "meta": {
            "type": "object",
            "properties": {
              "charsRead": {
                "type": "integer"
              },
              "truncated": {
                "type": "boolean"
              },
              "plan": {
                "type": "string",
                "enum": [
                  "free",
                  "family",
                  "classroom",
                  "school"
                ]
              },
              "remainingToday": {
                "type": "integer"
              },
              "resetAt": {
                "type": "string",
                "format": "date-time"
              },
              "generatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "disclaimer": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "code",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "code": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "upgradeUrl": {
            "type": "string"
          }
        }
      },
      "ParentBriefing": {
        "type": "object",
        "properties": {
          "kind": {
            "const": "parent"
          },
          "officialTitle": {
            "type": "string"
          },
          "plainTitle": {
            "type": "string"
          },
          "jurisdiction": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "lede": {
            "type": "string"
          },
          "whatChanged": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "whoItTouches": {
            "type": "string"
          },
          "whatItDoesNot": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "datesToKnow": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                }
              }
            }
          },
          "questionsForSchool": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "kitchenScript": {
            "type": "string"
          },
          "fiveMinuteAction": {
            "type": "string"
          }
        },
        "required": [
          "kind"
        ]
      },
      "ClassroomOutline": {
        "type": "object",
        "properties": {
          "kind": {
            "const": "classroom"
          },
          "officialTitle": {
            "type": "string"
          },
          "lessonTitle": {
            "type": "string"
          },
          "gradeBand": {
            "type": "string",
            "enum": [
              "5",
              "8",
              "12"
            ]
          },
          "minutes": {
            "type": "integer",
            "enum": [
              30,
              45
            ]
          },
          "objective": {
            "type": "string"
          },
          "vocabulary": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "term": {
                  "type": "string"
                },
                "kidDefinition": {
                  "type": "string"
                }
              }
            }
          },
          "readAloud": {
            "type": "object",
            "description": "A short story at the grade band's reading age."
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "minutes": {
                  "type": "integer"
                },
                "title": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              }
            }
          },
          "discussionQuestions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "activity": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "exitTicket": {
            "type": "string"
          },
          "nonpartisanNote": {
            "type": "string"
          }
        },
        "required": [
          "kind"
        ]
      }
    }
  },
  "security": [
    {}
  ]
}