Quickstart

curl -s https://api.taxorch.com/api/v1/tax-assistant/answer \
  -H "Authorization: Bearer $TAXORCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the income tax on £60,000 in the UK for 2024/25?",
    "site": 1
  }'

const response = await fetch(
  "https://api.taxorch.com/api/v1/tax-assistant/answer",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TAXORCH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "What is the income tax on £60,000 in the UK for 2024/25?",
      site: 1,
    }),
  },
);

// 200 even when the system declines to answer. Read the contract, not the code.
const answer = await response.json();

import os
import httpx

response = httpx.post(
    "https://api.taxorch.com/api/v1/tax-assistant/answer",
    headers={"Authorization": f"Bearer {os.environ['TAXORCH_API_KEY']}"},
    json={
        "question": "What is the income tax on £60,000 in the UK for 2024/25?",
        "site": 1,
    },
    timeout=60,
)

# 200 even when the system declines to answer. Read the contract, not the code.
answer = response.json()

type Outcome =
  | { kind: "answer"; total: string; citations: Citation[] }
  | { kind: "ask"; questions: MissingFact[] }
  | { kind: "escalate"; reason: string };

/**
 * There is no fourth branch, and no default that renders a number.
 *
 * Anything that is not `verified` and not `needs_facts` goes to a person.
 * Treating the rest as "close enough to show" is the single mistake this
 * contract exists to make impossible.
 */
function interpret(answer: AnswerContract): Outcome {
  if (answer.human_review_required) {
    return { kind: "escalate", reason: answer.next_actions[0] };
  }

  switch (answer.verification_status) {
    case "verified":
      return {
        kind: "answer",
        total: answer.calculations[0].total_tax,
        citations: answer.citations,
      };

    case "needs_facts":
      return { kind: "ask", questions: answer.missing_facts };

    default:
      return { kind: "escalate", reason: answer.next_actions[0] };
  }
}

def interpret(answer: dict) -> Outcome:
    """
    There is no fourth branch, and no default that renders a number.

    Anything that is not verified and not needs_facts goes to a person.
    Treating the rest as "close enough to show" is the single mistake this
    contract exists to make impossible.
    """
    if answer["human_review_required"]:
        return Escalate(reason=answer["next_actions"][0])

    status = answer["verification_status"]

    if status == "verified":
        return Answer(
            total=answer["calculations"][0]["total_tax"],
            citations=answer["citations"],
        )

    if status == "needs_facts":
        return Ask(questions=answer["missing_facts"])

    return Escalate(reason=answer["next_actions"][0])