Prompts API for schema outputs

Summary

Prompts define the extraction contract. The public API supports prompt CRUD, schema testing, usage inspection, and prompt-definition draft generation.

Prompt endpoints

Method	Path	Purpose
`POST`	`/api/v2/prompts`	Create a prompt
`GET`	`/api/v2/prompts`	List prompts
`GET`	`/api/v2/prompts/{prompt_id}`	Retrieve one prompt
`PUT`	`/api/v2/prompts/{prompt_id}`	Replace selected prompt fields
`DELETE`	`/api/v2/prompts/{prompt_id}`	Delete or deactivate a prompt
`POST`	`/api/v2/prompts/test-schema`	Validate sample data against a schema
`GET`	`/api/v2/prompts/{prompt_id}/usage`	Inspect usage and safety-to-delete signals
`POST`	`/api/v2/prompts/generate`	Generate a draft prompt definition for the creation flow

Request shape

Public prompt creation supports these top-level fields:

Field	Type	Notes
`name`	`string`	Human-readable prompt name
`description`	`string`	Optional description
`prompt_text`	`string`	Instructions for extraction
`json_schema`	`object`	Segment-level JSON Schema
`video_level`	`object`	Optional media-wide synthesis contract
`semantic_indexing`	`object`	Optional per-field semantic indexing controls

Example: create a prompt

curl -X POST /api/v2/prompts \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prompt-create-scene-v1" \
  -d '{
    "name": "Scene extractor",
    "description": "Extract structured scene evidence per segment.",
    "prompt_text": "Extract the requested fields from this media segment.",
    "json_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" },
        "scene": {
          "type": "object",
          "properties": {
            "location": { "type": "string" },
            "people": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "emotion": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "video_level": {
      "instructions_text": "Summarize the entire asset from the extracted segment evidence.",
      "included_segment_fields": ["headline", "scene.location", "transcription"],
      "json_schema": {
        "type": "object",
        "properties": {
          "program_summary": { "type": "string" }
        }
      }
    },
    "semantic_indexing": {
      "disabled_segment_fields": [],
      "disabled_video_level_fields": []
    }
  }'

Schema validation

Use /api/v2/prompts/test-schema before saving a production contract.

curl -X POST /api/v2/prompts/test-schema \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "json_schema": {
      "type": "object",
      "properties": {
        "headline": { "type": "string" }
      }
    },
    "sample_data": {
      "headline": "Reporter outside station"
    }
  }'

Update semantics

PUT /api/v2/prompts/{prompt_id} supports partial replacement of documented prompt fields. Public update behavior includes:

replacing prompt_text
replacing json_schema
replacing video_level
replacing semantic_indexing
clearing video_level with clear_video_level: true

Legacy index prompt attachment

The route /api/v2/indexes/{index_id}/prompt still exists, but the route implementation explicitly warns that index-level prompt attachment is deprecated. New integrations should execute prompts through prompt runs.