---
title: "Post Taxonomy Proposal"
method: POST
path: "/api/v1/classification/taxonomy-proposal"
tags: ["classification"]
---

# Post Taxonomy Proposal

`POST /api/v1/classification/taxonomy-proposal`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/classification/taxonomy-proposal`
- Auth: API key in header `X-API-Key`

Accept a structured taxonomy proposal from the agent and persist it
as an AgentFinding (finding_type='revenue_opportunity', domain='data_quality').

The proposal action + target + evidence land in the finding's
evidence JSONB so the existing approval queue (and the agent's
`evaluate_peer_findings` skill) reads them with the same machinery
it uses for every other finding type. Proposals are always created
`pending` — no auto-approval path; Gib reviews on the standard
cadence (Tenet #31 — blast radius must be visible before approval).

## Request body

- TaxonomyProposalRequest
  - `agent_id` string, required: Agent that authored the proposal
  - `action` string, required: One of: ['add_keyword', 'add_sub', 'merge', 'split']
  - `target` object, required: What the proposal is changing. Shape depends on action: {industry_id} for merge, {sector, name} for split/add_sub, {keyword, industry_id_or_industry_sub_id, tier} for add_keyword.
  - `evidence` object, required: Supporting data: corpus_frequency, sample_records, blast_radius (records newly classified / rebucketed / confidence-tier shifted), source_findings.
  - `title` string, required: One-line summary for the findings table
  - `description` string, required: Full proposal narrative
  - `state` string, nullable
  - `session_id` string, nullable

## Response `201`

Successful Response

- TaxonomyProposalResponse
  - `finding_id` string, required
  - `status` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)