{"id":19466,"plugin_id":"plugins_6a99b26dd5f08191ae2c40cf2f63d2b2","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:36.133Z","digest":"f1a32eb8aad383fcaa2460fa18cefe130810d72a8bff28a818ba2f48fbef9e08","against":null,"payload":{"description":"Design, create, inspect, update, attach, detach, preview, execute, and verify reusable Vapi Structured Outputs through public API or Server SDK workflows. Use for post-call extraction, typed call artifacts, AI-versus-regex extraction, JSON Schema design, backfilling existing calls, or retrieving structured results programmatically.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":209},{"relative_path":"references/api-examples.md","size_in_bytes":9076}],"name":"create-structured-output","skill_md_contents":"---\nname: create-structured-output\ndescription: Design, create, inspect, update, attach, detach, preview, execute, and verify reusable Vapi Structured Outputs through public API or Server SDK workflows. Use for post-call extraction, typed call artifacts, AI-versus-regex extraction, JSON Schema design, backfilling existing calls, or retrieving structured results programmatically.\nlicense: MIT\n---\n\n# Vapi Structured Output Creation\n\nBuild the smallest reusable post-call extraction that represents the user's actual downstream contract. Keep definition creation, assistant attachment, execution, and result retrieval separate: success at one stage does not prove the next stage occurred.\n\n## Source and Safety Rules\n\n- Use the configured Vapi documentation MCP when available. Otherwise use current public Vapi API documentation and [API Examples](references/api-examples.md). Revalidate request fields and SDK methods before final implementation.\n- Use a private Vapi API key only on a trusted server. Read it from `VAPI_API_KEY`; never print, request in chat, or embed it in source, client-side code, or examples.\n- Never invent resource IDs, call IDs, extraction fields, enum values, data-retention requirements, or customer data.\n- Do not enable `compliancePlan.forceStoreOnHipaaEnabled` unless the user explicitly requests it and confirms that the output cannot contain PHI or other sensitive data.\n- Treat call transcripts, messages, tool results, and extracted values as sensitive customer data. Minimize what is logged or reproduced.\n\n## Procedure\n\n1. Choose the output mode.\n   - For a schema, payload, review, or implementation example, return an artifact without calling Vapi. State that nothing was saved, attached, or executed.\n   - For a reusable saved definition, use `POST /structured-output` only when the user asks to create or save it and credentials are available.\n   - For a one-call experiment that does not need a saved definition, pass a transient `structuredOutput` to `POST /structured-output/run` with `previewEnabled: true`.\n   - Treat attachment, detachment, and execution against existing calls as separate requested actions. Do not infer them from creation alone.\n\n2. Define the extraction contract.\n   - Identify the downstream consumer, required fields, optional fields, allowed categories, formats, and behavior when evidence is absent or ambiguous.\n   - Ask only for missing facts that materially change the schema. State safe assumptions for the rest.\n   - Split unrelated outputs when they have different consumers, retention policies, or iteration cycles. Keep one output when the fields form one stable business record.\n\n3. Choose AI or regex.\n   - Use `type: \"ai\"` for meaning, classification, summarization, sentiment, outcome detection, normalization, or facts expressed in varied language.\n   - Use `type: \"regex\"` only for deterministic transcript matching with a stable pattern. Use RE2-compatible syntax and choose a top-level schema type that matches the documented regex result: boolean, string, number/integer, or array.\n   - Do not use regex to infer meaning. Do not use AI when a literal, stable pattern is the entire requirement.\n\n4. Design the smallest useful JSON Schema.\n   - Include only fields the caller can provide or the call evidence can support.\n   - Add concise descriptions that distinguish semantically similar fields.\n   - Use `enum` for a closed category set, `format` or `pattern` for externally validated strings, and numeric bounds when the business contract defines them.\n   - Mark a field required only when every valid call should produce it. Make conditionally available values optional instead of forcing guesses.\n   - Prefer a primitive schema for a single value and an object only for a cohesive record. Avoid deep nesting unless the downstream contract needs it.\n   - Validate the schema with a standard JSON Schema validator before sending it.\n\n5. Create, inspect, or update the definition.\n   - Keep saved names between 1 and 40 characters.\n   - On create, send `name` and `schema`; add `type`, `description`, `regex`, `model`, or `compliancePlan` only when intentional.\n   - On inspect, resolve the exact resource with list filters or a verified ID, then use `GET /structured-output/{id}`. Do not guess from a partial name.\n   - On update, read the current definition first and send only fields that should change. Use `schemaOverride=true` only when intentionally changing the schema's top-level type; otherwise do not use it to bypass schema safety.\n   - Re-fetch after mutation and compare the requested fields. A successful HTTP status without the expected returned state is not verified success.\n\n6. Attach or detach safely.\n   - Prefer the saved Structured Output's documented `assistantIds` relationship for attachment. Read its current `assistantIds`, add or remove exactly the resolved assistant ID, and preserve every unrelated ID.\n   - Patch only `assistantIds` on the Structured Output for this operation. Re-fetch the Structured Output and assistant; verify the relationship and the assistant's `artifactPlan.structuredOutputIds` when returned.\n   - If the implementation instead patches the assistant, first read the assistant and send the complete existing `artifactPlan` with only `structuredOutputIds` changed. Preserve recording, logging, transcript, scorecard, storage, and other artifact settings.\n   - Do not claim that creating a definition attached it. Do not claim that detaching deleted it or removed results already stored on past calls.\n\n7. Preview before broad execution.\n   - Use `POST /structured-output/run` with one real call ID and `previewEnabled: true`. Supply either `structuredOutputId` or a transient `structuredOutput`, not both.\n   - Confirm the selected call contains representative evidence and that the returned value satisfies the schema and business meaning.\n   - State that preview does not update the call artifact.\n   - If extraction is wrong, simplify the schema or improve descriptions before changing models or custom extraction prompts.\n\n8. Execute or backfill only when requested.\n   - Use `previewEnabled: false` or omit it to update call artifacts. Pass no more than the currently documented maximum of 100 call IDs per request.\n   - Before a multi-call run, state the exact output, call count, and that existing values for this output may be replaced while other structured-output values remain.\n   - Use only call IDs supplied by the user or returned by a verified public API query. Report partial failures by call ID; do not imply an all-or-nothing transaction.\n\n9. Retrieve and verify results.\n   - After a normal attached call finishes, allow for post-call processing before checking the call.\n   - Retrieve each call with `GET /call/{id}` and read `call.artifact.structuredOutputs[structuredOutputId].result`.\n   - Validate the result against the intended schema and inspect representative source evidence before calling it accurate. Schema validity proves shape, not factual correctness.\n   - Report separately: definition saved, assistant linked, preview returned, call artifact updated, and result validated. Mention only stages actually verified.\n\n## Error Handling\n\n- On `400`, inspect the response for schema, regex, model, relationship, or run constraints. Correct one unambiguous documented issue and retry once; never repeat an unchanged request.\n- On `401` or `403`, stop and report authentication or permission failure.\n- On `404`, report the missing Structured Output, assistant, or call and identify the exact unresolved ID.\n- On `409`, re-read current state before deciding whether the intended relationship or update already exists.\n- On `429` or `5xx`, preserve the request context, report the service condition, and do not claim success.\n- If a result is absent, distinguish processing delay, missing attachment, disabled artifact storage, insufficient call evidence, and extraction failure before recommending a change.\n\n## API Implementation Examples\n\nRead [API Examples](references/api-examples.md) when implementation code is needed. Use the official TypeScript or Python Server SDK only after confirming the generated method in its current official reference; use direct REST when SDK syntax is unavailable or unstable.\n\n## Output Contract\n\nReturn only the sections relevant to the request:\n\n- Mode: artifact-only, saved definition, relationship change, preview, or artifact-writing run\n- Assumptions or blocking questions\n- Final schema and Structured Output configuration\n- Created or updated resource ID and verified fields, when mutated\n- Attachment state and preserved relationships, when changed\n- Preview or execution result, affected call IDs, and whether artifacts changed\n- Retrieved result plus schema and evidence limitations\n- Remaining configuration or validation work\n\n## Public Sources\n\n- [Structured Outputs quickstart](https://docs.vapi.ai/assistants/structured-outputs-quickstart/)\n- [Create Structured Output API](https://docs.vapi.ai/api-reference/structured-outputs/structured-output-controller-create)\n- [List Structured Outputs API](https://docs.vapi.ai/api-reference/structured-outputs/structured-output-controller-find-all)\n- [Get Structured Output API](https://docs.vapi.ai/api-reference/structured-outputs/structured-output-controller-find-one)\n- [Update Structured Output API](https://docs.vapi.ai/api-reference/structured-outputs/structured-output-controller-update)\n- [Run Structured Output API](https://docs.vapi.ai/api-reference/structured-outputs/structured-output-controller-run)\n- [Get Call API](https://docs.vapi.ai/api-reference/calls/get/)\n- [Official TypeScript Server SDK reference](https://github.com/VapiAI/server-sdk-typescript/blob/main/reference.md)\n- [Official Python Server SDK reference](https://github.com/VapiAI/server-sdk-python/blob/main/reference.md)\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}