---
title: "Propose Thesis Match"
method: POST
path: "/thesis-commands/match-proposals"
tags: ["thesis commands"]
---

# Propose Thesis Match

`POST /thesis-commands/match-proposals`

## Request

- Base URL: `https://api.tickertrac.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tickertrac.com/thesis-commands/match-proposals`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Review one exact private Match without reserving usage or starting work.

## Request body

- ThesisMatchProposalIn: One model-free preflight for a private Match against an exact saved thesis.
  - `schema_version` 'thesis-match-proposal-v1', required
  - `idempotency_key` string, uuid, required
  - `operation` 'propose_match', required
  - `confirmation_policy` 'explicit_approval_required', required
  - `requested_window` 'current_match_catalog', required
  - `result_limit` 5, required
  - `subject_type` 'company_thesis' | 'investment_theme', required
  - `subject_version` integer, required
  - `watchlist_id` integer, nullable
  - `ticker` string, nullable
  - `shared_thesis_id` integer, nullable

## Response `200`

Successful Response

- ThesisMatchProposalOut
  - `schema_version` 'thesis-match-proposal-v1', required
  - `idempotency_key` string, uuid, required
  - `operation` 'propose_match', required
  - `confirmation_policy` 'explicit_approval_required', required
  - `requested_window` 'current_match_catalog', required
  - `result_limit` 5, required
  - `proposal_status` 'confirmation_available' | 'subject_inactive' | 'allowance_exhausted' | 'in_progress', required
  - `approval_available` boolean, required
  - `subject` ThesisReadSubjectOut, required
    - `subject_type` 'company_thesis' | 'investment_theme', required
    - `subject_key` string, required
    - `label` string, required
    - `narrative` string, required
    - `version_number` integer, required
    - `updated_at` string, date-time, required
    - `is_active` boolean, required
    - `workspace_path` string, required
  - `generated_at` string, date-time, required
  - `allowance` ThesisMatchAllowanceOut, required
    - `action` 'match'
    - `unit` 'match'
    - `daily_limit` integer, nullable, required
    - `used_today` integer, required
    - `remaining_today` integer, nullable, required
    - `monthly_limit` integer, nullable, required
    - `used_month` integer, required
    - `remaining_month` integer, nullable, required
    - `resets_at` string, date-time, required
    - `daily_resets_at` string, date-time, required
    - `admin_bypass` boolean, required
  - `usage_reserved` false
  - `model_evaluations_started` 0
  - `transcript_persisted` false
  - `relationships_changed` false
  - `recovery_path` string, required
  - `match` MatchRunOut
    - `id` integer, required
    - `thesis_shape` string, required
    - `thesis_source` 'preset' | 'shared_thesis' | 'company_thesis'
    - `shared_thesis_id` integer, nullable
    - `thesis_title` string, nullable
    - `top_n` integer, required
    - `status` 'pending' | 'scoring' | 'confirming' | 'ready' | 'failed', required
    - `error` string, nullable, required
    - `result_summary` string, nullable
    - `candidate_count` integer
    - `created_at` string, date-time, required
    - `tier1_cached_at` string, date-time, nullable
    - `force_fresh` boolean
    - `is_template_snapshot` boolean
    - `selection_policy_version` string, nullable
    - `economics` MatchEconomicsOut: Run-local counters used to price the watchlist-aware result policy.
      - `eligible_candidate_count` integer
      - `discovery_candidate_count` integer
      - `watched_candidate_count` integer
      - `linked_candidate_count` integer
      - `source_company_candidate_count` integer
      - `tier1_batch_count` integer
      - `discovery_only_tier1_batch_count` integer
      - `confirmation_selected_count` integer
      - `confirmation_reused_count` integer
      - `confirmation_computed_count` integer
      - `validation_reused_count` integer
      - `prior_policy_reusable_confirmation_count` integer
    - `candidates` MatchCandidateOut[], required
      - `ticker` string, required
      - `tier1_score` integer, required
      - `tier1_descriptor` string, required
      - `tier1_rank` integer, required
      - `verdict` string, nullable, required
      - `reasoning` string, nullable, required
      - `evidence` MatchEvidenceOut[]
        - `chunk_id` integer, required
        - `form_type` string, required
        - `fiscal_period` string, required
        - `filed_date` string, date, required
        - `section` string, required
        - `chunk_index` integer, required
        - `source_url` string, required
        - `excerpt` string, required
      - `is_tracked` boolean
      - `result_lane` 'discovery' | 'validation'
      - `selection_role` 'discovery' | 'watched' | 'linked' | 'source_company'
      - `selected_for_confirmation` boolean
      - `confirmation_reused` boolean, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tickertrac/apis/tickerrag-api.md) · [All operations](https://skmtc.dev/tickertrac/apis/tickerrag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tickertrac/apis/tickerrag-api/revisions/3c7eb0f6425d?raw)