{"openapi":"3.1.0","info":{"title":"counselorai API","version":"1.0.0","description":"Headless tool API. Every call is metered and billed in credits. Prices are published at GET /v1/tools."},"servers":[{"url":"https://api.counselorai.app"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}},"paths":{"/v1/tools/appeal":{"post":{"operationId":"counselorai_appeal","summary":"Financial aid appeal letter","description":"Draft a financial aid appeal letter to a college financial aid office. Call this when a family needs to ask for a review of an award: income dropped, an expense appeared, another school offered more, or the FAFSA was wrong. Returns the letter, not advice on whether to appeal. Runs a 5-step drafting pipeline, so it is the most expensive tool here and the slowest, typically 30 to 60 seconds.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"counselorName":{"type":"string","maxLength":100,"description":"Who the letter is from. The counselor stays the author; this tool drafts, it does not sign."},"schoolName":{"type":"string","maxLength":200,"description":"The institution the appeal goes to."},"appealType":{"type":"string","enum":["changed_circumstances","financial_hardship","competing_offer","special_circumstances","error_correction"],"default":"changed_circumstances","description":"What the appeal rests on. changed_circumstances is income loss or a new expense since the FAFSA, competing_offer is a match request, special_circumstances asks for a Professional Judgment review, error_correction fixes bad data on the original filing. financial_hardship is a legacy alias for changed_circumstances."},"currentAward":{"type":"string","maxLength":200,"description":"What the school offered, as written on the award letter."},"amountNeeded":{"type":"string","maxLength":200,"description":"The gap being asked for."},"keyDetails":{"type":"string","maxLength":3000,"description":"The circumstances, in the counselor or family's own words. This is what the letter is built out of, so specifics beat summaries."},"competing":{"type":"string","maxLength":3000,"description":"A competing offer to cite, if there is one."},"status":{"type":"array","maxItems":8,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster_youth","disability","housing_insecure","homeless","single_parent"]},"description":"Student circumstances the letter should carry without labeling them. homeless and housing_insecure are the same category."},"length":{"type":"string","enum":["short","standard","detailed"],"default":"standard","description":"Roughly 330, 440 or 560 words."},"naturalness":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How plainly the letter should read. 1 is formal institutional, 5 is conversational."}},"required":["keyDetails"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/appeal/quote":{"post":{"operationId":"counselorai_appeal_quote","summary":"Quote a Financial aid appeal letter call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"counselorName":{"type":"string","maxLength":100,"description":"Who the letter is from. The counselor stays the author; this tool drafts, it does not sign."},"schoolName":{"type":"string","maxLength":200,"description":"The institution the appeal goes to."},"appealType":{"type":"string","enum":["changed_circumstances","financial_hardship","competing_offer","special_circumstances","error_correction"],"default":"changed_circumstances","description":"What the appeal rests on. changed_circumstances is income loss or a new expense since the FAFSA, competing_offer is a match request, special_circumstances asks for a Professional Judgment review, error_correction fixes bad data on the original filing. financial_hardship is a legacy alias for changed_circumstances."},"currentAward":{"type":"string","maxLength":200,"description":"What the school offered, as written on the award letter."},"amountNeeded":{"type":"string","maxLength":200,"description":"The gap being asked for."},"keyDetails":{"type":"string","maxLength":3000,"description":"The circumstances, in the counselor or family's own words. This is what the letter is built out of, so specifics beat summaries."},"competing":{"type":"string","maxLength":3000,"description":"A competing offer to cite, if there is one."},"status":{"type":"array","maxItems":8,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster_youth","disability","housing_insecure","homeless","single_parent"]},"description":"Student circumstances the letter should carry without labeling them. homeless and housing_insecure are the same category."},"length":{"type":"string","enum":["short","standard","detailed"],"default":"standard","description":"Roughly 330, 440 or 560 words."},"naturalness":{"type":"integer","minimum":1,"maximum":5,"default":3,"description":"How plainly the letter should read. 1 is formal institutional, 5 is conversational."}},"required":["keyDetails"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/rec":{"post":{"operationId":"counselorai_rec","summary":"Letter of recommendation","description":"Draft a letter of recommendation from counselor notes. Call this to WRITE a letter. To critique one that already exists, call letterlens instead, which is much cheaper. Runs the same 5-step pipeline as appeal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"counselorName":{"type":"string","maxLength":100,"description":"Who the letter is from. The counselor stays the author; this tool drafts, it does not sign."},"purpose":{"type":"string","enum":["college_general","college_honors","scholarship","transfer","professional","employment","program","undergraduate","graduate","internship","other"],"default":"college_general","description":"What the letter is for. undergraduate, graduate, internship and other are legacy aliases kept working for existing integrations."},"profType":{"type":"string","enum":["law","medical","mba","dental","pharmacy","pa","nursing","socialwork"],"description":"Only when purpose is professional: which professional school, since each reads for different things."},"recipient":{"type":"string","maxLength":200,"description":"Who receives it, if named."},"schools":{"type":"string","maxLength":500,"description":"Target school or program."},"major":{"type":"string","maxLength":200},"selectivity":{"type":"string","maxLength":100,"description":"How selective the target is. Shifts how much evidence the letter has to carry."},"relationship":{"type":"string","maxLength":3000,"description":"How the counselor knows the student, and for how long."},"traits":{"type":"string","maxLength":3000,"description":"Three standout traits. Send prose, not a list of adjectives: the pipeline turns each one into a scene and needs something to work from."},"story":{"type":"string","maxLength":3000,"description":"A specific moment worth telling. The single highest-value field here."},"contribution":{"type":"string","maxLength":3000,"description":"What the student adds to a campus."},"resumeText":{"type":"string","maxLength":3000,"description":"Resume or activity list as plain text."},"sampleText":{"type":"string","maxLength":3000,"description":"A sample of the counselor's own writing, so the letter lands in their voice rather than a generic one."}},"required":["traits"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/rec/quote":{"post":{"operationId":"counselorai_rec_quote","summary":"Quote a Letter of recommendation call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"counselorName":{"type":"string","maxLength":100,"description":"Who the letter is from. The counselor stays the author; this tool drafts, it does not sign."},"purpose":{"type":"string","enum":["college_general","college_honors","scholarship","transfer","professional","employment","program","undergraduate","graduate","internship","other"],"default":"college_general","description":"What the letter is for. undergraduate, graduate, internship and other are legacy aliases kept working for existing integrations."},"profType":{"type":"string","enum":["law","medical","mba","dental","pharmacy","pa","nursing","socialwork"],"description":"Only when purpose is professional: which professional school, since each reads for different things."},"recipient":{"type":"string","maxLength":200,"description":"Who receives it, if named."},"schools":{"type":"string","maxLength":500,"description":"Target school or program."},"major":{"type":"string","maxLength":200},"selectivity":{"type":"string","maxLength":100,"description":"How selective the target is. Shifts how much evidence the letter has to carry."},"relationship":{"type":"string","maxLength":3000,"description":"How the counselor knows the student, and for how long."},"traits":{"type":"string","maxLength":3000,"description":"Three standout traits. Send prose, not a list of adjectives: the pipeline turns each one into a scene and needs something to work from."},"story":{"type":"string","maxLength":3000,"description":"A specific moment worth telling. The single highest-value field here."},"contribution":{"type":"string","maxLength":3000,"description":"What the student adds to a campus."},"resumeText":{"type":"string","maxLength":3000,"description":"Resume or activity list as plain text."},"sampleText":{"type":"string","maxLength":3000,"description":"A sample of the counselor's own writing, so the letter lands in their voice rather than a generic one."}},"required":["traits"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/letterlens":{"post":{"operationId":"counselorai_letterlens","summary":"Review a letter","description":"Analyze a finished recommendation letter and return specific fixes: what is vague, what is asserted without evidence, what reads as generated. Read-only and far cheaper than drafting. Use it to critique a draft, not to rewrite one, and use revision to apply the fixes.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"letterText":{"type":"string","minLength":50,"maxLength":3000,"description":"The letter to review, as plain text."},"purpose":{"type":"string","enum":["rec_college","rec_scholarship","rec_transfer","rec_professional","rec_employment","rec_program","undergraduate","graduate","scholarship","transfer","internship","other"],"default":"rec_college","description":"What the letter is for. A scholarship letter is read differently from a transfer letter."},"focus":{"type":"string","maxLength":500,"description":"A specific thing to look hardest at, if there is one."}},"required":["letterText"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/letterlens/quote":{"post":{"operationId":"counselorai_letterlens_quote","summary":"Quote a Review a letter call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"letterText":{"type":"string","minLength":50,"maxLength":3000,"description":"The letter to review, as plain text."},"purpose":{"type":"string","enum":["rec_college","rec_scholarship","rec_transfer","rec_professional","rec_employment","rec_program","undergraduate","graduate","scholarship","transfer","internship","other"],"default":"rec_college","description":"What the letter is for. A scholarship letter is read differently from a transfer letter."},"focus":{"type":"string","maxLength":500,"description":"A specific thing to look hardest at, if there is one."}},"required":["letterText"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/awardlens":{"post":{"operationId":"counselorai_awardlens","summary":"Read an award letter","description":"Break down one to three financial aid award letters: what is grant, what is loan, what is work-study that has to be earned, what the supported net price is, and what renewal conditions are buried in the language. Identifies missing facts and questions for the aid office. With more than one letter it compares them side by side. Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"letter1":{"type":"string","minLength":20,"maxLength":6000,"description":"First award letter, pasted as plain text."},"letter2":{"type":"string","maxLength":6000,"description":"Second award letter, to compare against the first."},"letter3":{"type":"string","maxLength":6000,"description":"Third award letter."},"scorecardData":{"type":"array","maxItems":6,"items":{"type":"string","maxLength":500},"description":"Optional College Scorecard lines to ground the comparison: acceptance rate, graduation rate, average net price. Include the original Letter number and school/campus; unverified caller-supplied context."}},"required":["letter1"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/awardlens/quote":{"post":{"operationId":"counselorai_awardlens_quote","summary":"Quote a Read an award letter call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"letter1":{"type":"string","minLength":20,"maxLength":6000,"description":"First award letter, pasted as plain text."},"letter2":{"type":"string","maxLength":6000,"description":"Second award letter, to compare against the first."},"letter3":{"type":"string","maxLength":6000,"description":"Third award letter."},"scorecardData":{"type":"array","maxItems":6,"items":{"type":"string","maxLength":500},"description":"Optional College Scorecard lines to ground the comparison: acceptance rate, graduation rate, average net price. Include the original Letter number and school/campus; unverified caller-supplied context."}},"required":["letter1"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/fafsa":{"post":{"operationId":"counselorai_fafsa","summary":"FAFSA checklist","description":"Produce a FAFSA action checklist for one student, keyed to their grade, dependency status and income band. Answers the process question a family actually has: what do we do, in what order, by when. Does not compute an award.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","enum":["9","10","11","12","transfer"],"default":"12","description":"How far out the family is. 12 means act now."},"dependency":{"type":"string","enum":["dependent","independent","unsure"],"default":"dependent","description":"Dependency drives whose income is reported. unsure is a valid answer and changes the checklist."},"income":{"type":"string","enum":["under30","30to60","60to100","over100","unknown"],"default":"unknown","description":"Household income band. Drives whether Pell is in play."},"specials":{"type":"array","maxItems":8,"items":{"type":"string","enum":["divorced","stepparent","sibling","undocumented","foster","homeless","disability","income_change"]},"description":"Situations that change the filing rules: divorced or separated parents, a stepparent, a sibling also in college, undocumented status, foster care, housing instability, disability, a mid-year income change."},"schools":{"type":"string","maxLength":1000,"description":"Schools on the list, if known. Deadlines differ by school."},"timeline":{"type":"string","maxLength":200,"description":"Where they are in the cycle."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/fafsa/quote":{"post":{"operationId":"counselorai_fafsa_quote","summary":"Quote a FAFSA checklist call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","enum":["9","10","11","12","transfer"],"default":"12","description":"How far out the family is. 12 means act now."},"dependency":{"type":"string","enum":["dependent","independent","unsure"],"default":"dependent","description":"Dependency drives whose income is reported. unsure is a valid answer and changes the checklist."},"income":{"type":"string","enum":["under30","30to60","60to100","over100","unknown"],"default":"unknown","description":"Household income band. Drives whether Pell is in play."},"specials":{"type":"array","maxItems":8,"items":{"type":"string","enum":["divorced","stepparent","sibling","undocumented","foster","homeless","disability","income_change"]},"description":"Situations that change the filing rules: divorced or separated parents, a stepparent, a sibling also in college, undocumented status, foster care, housing instability, disability, a mid-year income change."},"schools":{"type":"string","maxLength":1000,"description":"Schools on the list, if known. Deadlines differ by school."},"timeline":{"type":"string","maxLength":200,"description":"Where they are in the cycle."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/aid":{"post":{"operationId":"counselorai_aid","summary":"Aid estimate explainer","description":"Explain what a family is likely to see across a list of schools and why, in plain language. An explanation for a counselor to walk a family through, never an official determination, and the output says so.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"income":{"type":"string","maxLength":100,"description":"Household income, as the family stated it."},"schoolCount":{"type":"integer","minimum":1,"maximum":20,"description":"How many schools are being compared."},"schoolSummaries":{"type":"string","maxLength":3000,"description":"One line per school: name, cost of attendance, anything already known about the offer."},"context":{"type":"string","maxLength":3000,"description":"Household situation that affects the estimate."},"fafsaContext":{"type":"string","maxLength":3000,"description":"What is already known from the FAFSA, including the SAI if it has come back."},"repayContext":{"type":"string","maxLength":3000,"description":"What the family has said about borrowing and what they can carry."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/aid/quote":{"post":{"operationId":"counselorai_aid_quote","summary":"Quote a Aid estimate explainer call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"income":{"type":"string","maxLength":100,"description":"Household income, as the family stated it."},"schoolCount":{"type":"integer","minimum":1,"maximum":20,"description":"How many schools are being compared."},"schoolSummaries":{"type":"string","maxLength":3000,"description":"One line per school: name, cost of attendance, anything already known about the offer."},"context":{"type":"string","maxLength":3000,"description":"Household situation that affects the estimate."},"fafsaContext":{"type":"string","maxLength":3000,"description":"What is already known from the FAFSA, including the SAI if it has come back."},"repayContext":{"type":"string","maxLength":3000,"description":"What the family has said about borrowing and what they can carry."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/scholarship":{"post":{"operationId":"counselorai_scholarship","summary":"Scholarship research links","description":"Search for current scholarship pages to review. A page in the result is a research lead, not a verified match. Confirm program terms, deadline, and student eligibility on the sponsor page before advising the student. Live web search makes this slower and costlier than the other analysis tools.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","maxLength":20,"description":"Grade level or transfer status."},"gpa":{"type":"string","maxLength":20},"major":{"type":"string","maxLength":200,"description":"Intended field. Departmental awards are usually the least contested."},"state":{"type":"string","maxLength":50,"description":"State of residence. State and regional awards have far smaller applicant pools than national ones."},"backgrounds":{"type":"array","maxItems":14,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster","disability","rural","military","hispanic","black","indigenous","asian_pi","stem","arts","public_service"]},"description":"Eligibility categories that unlock specific award pools."},"activities":{"type":"string","maxLength":3000,"description":"Extracurriculars and leadership."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/scholarship/quote":{"post":{"operationId":"counselorai_scholarship_quote","summary":"Quote a Scholarship research links call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","maxLength":20,"description":"Grade level or transfer status."},"gpa":{"type":"string","maxLength":20},"major":{"type":"string","maxLength":200,"description":"Intended field. Departmental awards are usually the least contested."},"state":{"type":"string","maxLength":50,"description":"State of residence. State and regional awards have far smaller applicant pools than national ones."},"backgrounds":{"type":"array","maxItems":14,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster","disability","rural","military","hispanic","black","indigenous","asian_pi","stem","arts","public_service"]},"description":"Eligibility categories that unlock specific award pools."},"activities":{"type":"string","maxLength":3000,"description":"Extracurriculars and leadership."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/profile":{"post":{"operationId":"counselorai_profile","summary":"Student profile summary","description":"Turn raw counselor notes into a structured student profile. Run this first when working one student across several tools: it is cheap, and its output is good input for the relationship, traits and story fields on rec, or keyDetails on appeal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","maxLength":20},"school":{"type":"string","maxLength":200},"major":{"type":"string","maxLength":200},"academics":{"type":"string","maxLength":3000,"description":"Coursework, GPA, testing, academic trajectory."},"activities":{"type":"string","maxLength":3000},"strengths":{"type":"string","maxLength":3000,"description":"What the counselor has actually observed, not adjectives."},"challenges":{"type":"string","maxLength":3000,"description":"What the student has had to work around."},"goals":{"type":"string","maxLength":3000},"tags":{"type":"array","maxItems":14,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster","disability","rural","military","hispanic","black","indigenous","asian_pi","stem","arts","public_service"]},"description":"Background categories. Same vocabulary the scholarship tool uses, so a profile feeds straight into it."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/profile/quote":{"post":{"operationId":"counselorai_profile_quote","summary":"Quote a Student profile summary call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"studentName":{"type":"string","maxLength":100,"description":"The student this is about. Used in the output text."},"grade":{"type":"string","maxLength":20},"school":{"type":"string","maxLength":200},"major":{"type":"string","maxLength":200},"academics":{"type":"string","maxLength":3000,"description":"Coursework, GPA, testing, academic trajectory."},"activities":{"type":"string","maxLength":3000},"strengths":{"type":"string","maxLength":3000,"description":"What the counselor has actually observed, not adjectives."},"challenges":{"type":"string","maxLength":3000,"description":"What the student has had to work around."},"goals":{"type":"string","maxLength":3000},"tags":{"type":"array","maxItems":14,"items":{"type":"string","enum":["first_gen","low_income","undocumented","foster","disability","rural","military","hispanic","black","indigenous","asian_pi","stem","arts","public_service"]},"description":"Background categories. Same vocabulary the scholarship tool uses, so a profile feeds straight into it."},"notes":{"type":"string","maxLength":3000,"description":"Anything else that should shape the output."}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/revision":{"post":{"operationId":"counselorai_revision","summary":"Revise a draft","description":"Apply one instruction to an existing letter and return the revised text. Pair it with letterlens: review to find the problems, revise to fix them. Changes only what the instruction asks for.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentText":{"type":"string","minLength":50,"maxLength":3000,"description":"The letter as it stands."},"instruction":{"type":"string","minLength":3,"maxLength":1000,"description":"What to change. One instruction per call gets a cleaner result than a list."}},"required":["currentText","instruction"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/revision/quote":{"post":{"operationId":"counselorai_revision_quote","summary":"Quote a Revise a draft call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currentText":{"type":"string","minLength":50,"maxLength":3000,"description":"The letter as it stands."},"instruction":{"type":"string","minLength":3,"maxLength":1000,"description":"What to change. One instruction per call gets a cleaner result than a list."}},"required":["currentText","instruction"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/translate":{"post":{"operationId":"counselorai_translate","summary":"Translate for families","description":"Translate counselor-facing output into a family's language, holding the financial aid terms in English on purpose. FAFSA, Pell, SAI, COA and the loan names stay untranslated so a family can match what the school actually sends them against what they were told. Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceText":{"type":"string","minLength":10,"maxLength":12000,"description":"The text to translate. Usually the output of another tool."},"targetLang":{"type":"string","enum":["es","zh","vi","ar","tl","ko","pt","fr","ru","hi"],"description":"Target language code."}},"required":["sourceText","targetLang"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/translate/quote":{"post":{"operationId":"counselorai_translate_quote","summary":"Quote a Translate for families call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceText":{"type":"string","minLength":10,"maxLength":12000,"description":"The text to translate. Usually the output of another tool."},"targetLang":{"type":"string","enum":["es","zh","vi","ar","tl","ko","pt","fr","ru","hi"],"description":"Target language code."}},"required":["sourceText","targetLang"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}},"/v1/tools/humanize":{"post":{"operationId":"counselorai_humanize","summary":"Humanize reader-facing text","description":"Rewrite reader-facing prose so it sounds direct, specific, and personal without changing facts or inventing a voice. Use it for outreach, emails, letters, posts, and narrative copy. It preserves quoted text and checks the result against the source. It does not evade or promise to beat AI detectors. Do not use it for code, SQL, JSON, legal text, or technical specifications.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Retry-safe key. Guarantees the call is billed at most once."},{"name":"X-Max-Credits","in":"header","required":false,"schema":{"type":"integer","minimum":1,"maximum":2147483647},"description":"Maximum credits approved for this call. Rejects a larger hold and caps the final charge."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":50,"maxLength":12000,"description":"The reader-facing prose to edit."},"audience":{"type":"string","enum":["general","cold_outreach","parent","student","counselor","leadership","social"],"default":"general","description":"Who will read the text. This changes vocabulary and formality, not the facts."},"strength":{"type":"string","enum":["light","standard","aggressive"],"default":"standard","description":"light makes surface fixes, standard rewrites AI-sounding sentences, aggressive may rebuild paragraph flow."},"preserveFormatting":{"type":"boolean","default":true,"description":"Keep headings, lists, paragraph breaks, links, and other formatting."}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool output","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"tool":{"type":"string"},"output":{"type":"object","properties":{"text":{"type":"string","description":"The generated output."},"meta":{"type":"object","description":"Pipeline metadata (pipeline, verify status, fix pass)."},"verification":{"type":"object","description":"Whether a model verify pass checked this text, and its verdict.","properties":{"checked":{"type":"boolean"},"method":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["PASS","FAIL",null]},"score":{"type":["integer","null"]},"fix_applied":{"type":["boolean","null"]}}},"grounding":{"type":"object","description":"What the generation was anchored to. fact_sheet is the exact ground truth the verify pass checked dollar figures, names, and dates against; null for tools without a fact-grounded verify pass.","properties":{"fact_sheet":{"type":["string","null"]},"fields_reflected_in_prompt":{"type":"array","items":{"type":"string"}},"fields_mapped_or_transformed":{"type":"array","items":{"type":"string"}},"fields_not_reflected":{"type":"array","items":{"type":"string"}}}},"input_fidelity":{"type":"string","description":"'strict': this lane never truncates silently; an over-limit input is rejected with a validation error, so the output was built on exactly what was sent."}},"required":["text"]},"billing":{"type":"object","properties":{"status":{"type":"string","enum":["settled","pending"]},"credits_charged":{"type":["integer","null"]},"credits_remaining":{"type":["integer","null"]}}}}}}}},"402":{"description":"Insufficient credits or approved spending limit exceeded. Inspect error.code."},"429":{"description":"Rate limited. Retry after the Retry-After header."}}}},"/v1/tools/humanize/quote":{"post":{"operationId":"counselorai_humanize_quote","summary":"Quote a Humanize reader-facing text call (free)","description":"Free pre-flight. Validates the input and returns the exact credit hold a real call would take at this account's price, without billing anything. An invalid input is still a 200: the body carries valid:false and the validation errors.","x-billing":"free","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":50,"maxLength":12000,"description":"The reader-facing prose to edit."},"audience":{"type":"string","enum":["general","cold_outreach","parent","student","counselor","leadership","social"],"default":"general","description":"Who will read the text. This changes vocabulary and formality, not the facts."},"strength":{"type":"string","enum":["light","standard","aggressive"],"default":"standard","description":"light makes surface fixes, standard rewrites AI-sounding sentences, aggressive may rebuild paragraph flow."},"preserveFormatting":{"type":"boolean","default":true,"description":"Keep headings, lists, paragraph breaks, links, and other formatting."}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string"},"valid":{"type":"boolean"},"validation_errors":{"type":"array"},"estimated_credits":{"type":"integer"},"estimated_usd":{"type":"number"},"max_credits_held":{"type":"integer"},"max_credits_supported":{"type":"boolean"},"credit_balance":{"type":"integer"},"sufficient":{"type":"boolean"},"price_multiplier":{"type":"number"}}}}}}}}}}}