Worthune API

openapi: 3.1.0
info:
  title: Worthune API
  version: '2026-10-19'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-19: 22 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Worthune has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 6
    documentation: 16
    pages-with-code: 3
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-19'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://worthune.com/docs
  - https://worthune.com/docs/models/capital-gains
  - https://worthune.com/docs/models/retirement-income-cliffs
  - https://worthune.com/models
  - https://worthune.com/try
  - https://worthune.com/demo
  - https://worthune.com/household
  - https://worthune.com/proof
  - https://worthune.com/roadmap
  - https://worthune.com/evals
paths:
  /api/v1/book-scan:
    post:
      operationId: post_api_v1_book_scan
      tags:
      - Api
      summary: POST /api/v1/book-scan — the same coordination sweep across up to 250 households at once
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/decisions/{id}:
    get:
      operationId: get_api_v1_decisions_id
      tags:
      - Api
      summary: GET /api/v1/decisions/{id}
      x-source: https://worthune.com/docs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/embed-tokens:
    post:
      operationId: post_api_v1_embed_tokens
      tags:
      - Api
      summary: POST /api/v1/embed-tokens — mints a short‑lived, household‑scoped signed token
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/evals/refinance:
    get:
      operationId: get_api_v1_evals_refinance
      tags:
      - Api
      summary: GET /api/v1/evals/refinance
      x-source: https://worthune.com/evals
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl -s https://worthune.com/api/v1/evals/refinance | head -3
  /api/v1/grade/{model}:
    post:
      operationId: post_api_v1_grade_model
      tags:
      - Api
      summary: Worthune Evals — Ground Truth for Financial AI
      x-source: https://worthune.com/evals
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/households:
    post:
      operationId: post_api_v1_households
      tags:
      - Api
      summary: POST /api/v1/households — create the document (pass your own importKey and a retried create returns the household it already made)
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/households/import:
    post:
      operationId: post_api_v1_households_import
      tags:
      - Api
      summary: POST /api/v1/households/import — bulk migration, up to 200 households a batch
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/households/{id}/decisions:
    post:
      operationId: post_api_v1_households_id_decisions
      tags:
      - Api
      summary: Each strategy returns ranked alternatives with a computed dollar delta against the baseline — every option shown, never just a
        winner — and each decision carries its own evidence record.
      x-source: https://worthune.com/household
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1HouseholdsIdDecisionsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/households/{id}/project:
    post:
      operationId: post_api_v1_households_id_project
      tags:
      - Api
      summary: Run this yourself
      x-source: https://worthune.com/demo
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/models:
    get:
      operationId: get_api_v1_models
      tags:
      - Api
      summary: Discover models at GET /api/v1/models
      x-source: https://worthune.com/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/models/{model}:
    get:
      operationId: get_api_v1_models_model
      tags:
      - Api
      summary: 'Three endpoints per model: the JSON contract ( GET /api/v1/models/{model} )'
      x-source: https://worthune.com/docs
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_models_model
      tags:
      - Api
      summary: 'Three endpoints per model: execution ( POST /api/v1/models/{model} )'
      x-source: https://worthune.com/docs
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/models/{model}/report:
    post:
      operationId: post_api_v1_models_model_report
      tags:
      - Api
      summary: POST /api/v1/models/{model}/report takes the same JSON inputs as a run and returns a print‑ready HTML document
      x-source: https://worthune.com/docs
      parameters:
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/openapi.json:
    get:
      operationId: get_api_v1_openapi_json
      tags:
      - Api
      summary: The whole surface is described by GET /api/v1/openapi.json
      x-source: https://worthune.com/docs
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/project:
    get:
      operationId: get_api_v1_project
      tags:
      - Api
      summary: Run the Engine on Your Own Numbers — No Signup, Nothing Stored
      description: Lists all twelve example projects and the shape of the request.
      x-source: https://worthune.com/try
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ProjectResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_project
      tags:
      - Api
      summary: POST /api/v1/project — the full projection and optional Monte Carlo on a household document you send
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/project/examples/retired-couple-spousal:
    get:
      operationId: get_api_v1_project_examples_retired_couple_spousal
      tags:
      - Api
      summary: Run the Engine on Your Own Numbers — No Signup, Nothing Stored
      description: Provides an example household definition that can be piped into a POST to /api/v1/project.
      x-source: https://worthune.com/try
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1ProjectExamplesRetiredCoupleSpousalResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_project_examples_retired_couple_spousal
      tags:
      - Api
      summary: POST /api/v1/project/examples/retired-couple-spousal
      x-source: https://worthune.com/try
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl -s https://worthune.com/api/v1/project/examples/retired-couple-spousal  | jq .body  | curl -s -X POST https://worthune.com/api/v1/project  -H
          "authorization: Bearer $WORTHUNE_KEY"  -H ''content-type: application/json'' -d @- From code the engine takes a key; a free sandbox
          key works. GET /api/v1/project lists all twelve and the shape of the request. Post the same document twice and the evidence'
  /api/v1/records/verify:
    post:
      operationId: post_api_v1_records_verify
      tags:
      - Api
      summary: POST /api/v1/records/verify — verify a decision record’s digest
      x-source: https://worthune.com/docs
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/telemetry:
    get:
      operationId: get_api_v1_telemetry
      tags:
      - Api
      summary: 63 models in the catalog today.
      description: Aggregate API usage, updated daily, honest zeros included.
      x-source: https://worthune.com/proof
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/verify:
    post:
      operationId: post_api_v1_verify
      tags:
      - Api
      summary: Documents A run you can hand to a reviewer
      description: Any computation renders as a print‑ready report that carries the payload its own hash was taken over, so it can be checked
        with nothing but the file.
      x-source: https://worthune.com/proof
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/verify/emergency-fund:
    post:
      operationId: post_api_v1_verify_emergency_fund
      tags:
      - Api
      summary: POST /api/v1/verify/emergency-fund
      x-source: https://worthune.com/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1VerifyEmergencyFundRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s https://worthune.com/api/v1/verify/emergency-fund  -X POST -H 'content-type: application/json'  -d '{\n \"inputs\":\
          \ { \"monthlyExpenses\": 4000, \"targetMonths\": 6,\n \"currentSavings\": 8000, \"monthlySavings\": 500,\n \"savingsAccountRate\": 0.04\
          \ },\n \"claims\": [\n { \"path\": \"targetAmount\", \"value\": 24000 },\n { \"path\": \"monthsToGoal\", \"op\": \"<=\", \"value\":\
          \ 30 }\n ]\n }'"
components:
  schemas:
    PostApiV1HouseholdsIdDecisionsRequest:
      type: object
      properties:
        strategy:
          type: string
          description: e.g., "withdrawal-sequencing"
      required:
      - strategy
    GetApiV1ProjectResponse:
      type: object
      properties:
        projects:
          type: array
          description: List of example projects and request shapes
    GetApiV1ProjectExamplesRetiredCoupleSpousalResponse:
      type: object
      properties:
        body:
          type: object
          description: Example household JSON for a retired couple with spousal earnings.
    PostApiV1VerifyEmergencyFundRequest:
      type: object
      properties:
        inputs:
          type: object
          properties:
            monthlyExpenses:
              type: integer
            targetMonths:
              type: integer
            currentSavings:
              type: integer
            monthlySavings:
              type: integer
            savingsAccountRate:
              type: number
        claims:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              value:
                type: integer
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api