---
title: "Set extraction schema"
method: POST
path: "/api/v1/initiatives/{id}/extraction-schema"
tags: ["Initiatives"]
---

# Set extraction schema

`POST /api/v1/initiatives/{id}/extraction-schema`

## Request

- Base URL: `https://www.useboom.ai`
- URL: `https://www.useboom.ai/api/v1/initiatives/{id}/extraction-schema`
- Auth: HTTP bearer

Author or replace an initiative's extraction schema — the typed fields (bool/int/enum/string) pulled from each conversation. Replaces the schema wholesale; submit the complete set of fields, not a diff. A version is created only when the schema actually changes.

## Path parameters

- `id` string, required: The initiative id.

## Request body

- object
  - `schema` object, required: The complete extraction schema: `{ fields: { <slug>: { type, label, description, ... } } }`. Replaces the current schema.
    - `fields` object, required
  - `notes` string: Optional note recorded on this schema version.

## Response `201`

Success

- object
  - `initiativeId` string, required
  - `version` integer, required: The extraction schema version now current for the initiative. Unchanged when the submitted schema was semantically identical to the current one.
  - `changed` boolean, required: Whether a new version was created. False when the submitted schema was semantically identical to the current one — no version bump, and the submitted `notes` were NOT recorded.
  - `fieldCount` integer, required: Number of fields in the schema.
  - `notes` string, nullable, required: The note on the current version — not necessarily the submitted note when `changed` is false.
  - `createdAt` string, required: ISO 8601 timestamp of this version.

## Other responses

- `400`: Validation failed or the request cannot proceed.
- `401`: Missing, malformed, or revoked API key.
- `404`: The resource does not exist in this organization.
- `409`: Conflicts with the current state (duplicates, wrong lifecycle state).
- `422`: The request is well-formed but semantically invalid.
- `429`: Rate limit exceeded — retry after `Retry-After`.
- `500`: Internal server error.
- `503`: Transient error — retry with a narrower request.

## Changes

- **2026-11-03** `7c7a773b12ce`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/useboom/apis/boom-api/changes/api/v1/initiatives/:id/extraction-schema/post.md)

---

[API](https://skmtc.dev/useboom/apis/boom-api.md) - [All operations](https://skmtc.dev/useboom/apis/boom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/useboom/apis/boom-api/revisions/d596d92ed092?raw)