> ## Documentation Index > Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt > Use this file to discover all available pages before exploring further. # Playground analysis > Lightweight single-item failure analysis for dashboard playground ## OpenAPI ````yaml openapi.json post /v2/failure-analysis/playground openapi: 3.1.0 info: title: Valiqor API description: >- The Valiqor API provides programmatic access to AI application testing, evaluation, failure analysis, and security auditing. ## Authentication All API requests require an API key passed as a Bearer token in the `Authorization` header: ``` Authorization: Bearer vq-xxxxxxxxxxxxxxxxxxxx ``` Get your API key from the [Valiqor Dashboard](https://app.valiqor.com) or via `valiqor login` CLI command. ## Base URL ``` https://api.valiqor.com ``` version: 2.0.0 contact: name: Valiqor Support url: https://valiqor.com email: support@valiqor.com servers: - url: https://api.valiqor.com description: Production security: [] tags: - name: Authentication description: >- API key validation, user management, device authorization flow, and CLI authentication. All SDK requests require a valid API key passed as a Bearer token. - name: Evaluation description: >- Run quality evaluations on datasets or traces. Compute metrics like faithfulness, relevance, coherence, and more. Compare runs and track trends over time. - name: Security description: >- Security audits (S1-S23 safety categories) and red team simulations. Detect prompt injection, harmful content, data leakage, and other vulnerabilities. - name: Failure Analysis description: >- Analyze AI app failures with root cause detection, severity scoring, and actionable fix suggestions. Supports both trace-based (full) and dataset-based (minimal) analysis modes. - name: Tracing description: >- Upload and query execution traces from AI applications. Traces capture messages, spans, tool calls, retrievals, and LLM interactions for debugging and evaluation. - name: Scanner description: >- Upload code scans to detect AI app features, workflows, and prompts. Generates evaluation configurations automatically from your codebase. - name: Projects description: >- Create and manage projects. Projects are containers that organize evaluation runs, security audits, traces, and failure analysis results. paths: /v2/failure-analysis/playground: post: tags: - Failure Analysis summary: Playground analysis description: Lightweight single-item failure analysis for dashboard playground operationId: playground_analysis_v2_failure_analysis_playground requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaygroundRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PlaygroundResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyAuth: [] components: schemas: PlaygroundRequest: properties: input: type: string maxLength: 2000 title: Input description: User prompt/query (max 2000 chars) output: type: string maxLength: 5000 title: Output description: AI response to analyze (max 5000 chars) context: anyOf: - type: string maxLength: 5000 - type: 'null' title: Context description: Retrieved documents or system prompt (max 5000 chars) tool_calls: anyOf: - items: additionalProperties: true type: object type: array maxItems: 5 - type: 'null' title: Tool Calls description: Tool invocations with outputs (max 5) type: object required: - input - output title: PlaygroundRequest description: >- Request for lightweight single-item failure analysis from dashboard playground. Security limits: - input: 2000 chars max (typical user prompts are <500) - output: 5000 chars max (enough for most responses) - context: 5000 chars max (sufficient for RAG demo) - Combined token budget: 4000 tokens max (checked at runtime) example: context: France is a country in Western Europe. Its capital is Paris. input: What is the capital of France? output: The capital of France is Berlin. PlaygroundResponse: properties: run_id: type: string title: Run Id summary: $ref: '#/components/schemas/FailureSummary' failure_tags: items: $ref: '#/components/schemas/FailureTagResponse' type: array title: Failure Tags checks_passed: type: integer title: Checks Passed description: Number of checks that passed (for showing thoroughness) security_flags: additionalProperties: type: string type: object title: Security Flags duration_ms: type: integer title: Duration Ms playground_runs_today: type: integer title: Playground Runs Today description: Number of playground runs used today default: 0 playground_limit_per_day: type: integer title: Playground Limit Per Day description: Daily playground run limit default: 10 type: object required: - run_id - summary - failure_tags - checks_passed - duration_ms title: PlaygroundResponse description: Response from playground analysis - simplified for dashboard UI. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FailureSummary: properties: primary_failure: anyOf: - type: string - type: 'null' title: Primary Failure description: Subcategory ID of highest severity failure primary_failure_name: anyOf: - type: string - type: 'null' title: Primary Failure Name description: Human-readable name of primary failure overall_severity: type: number title: Overall Severity description: Overall severity score default: 0 overall_confidence: type: number title: Overall Confidence description: Overall confidence score default: 0 total_failures_detected: type: integer title: Total Failures Detected default: 0 total_passes: type: integer title: Total Passes default: 0 total_uncertain: type: integer title: Total Uncertain default: 0 total_items: type: integer title: Total Items description: Total number of input items analyzed default: 0 items_with_failures: type: integer title: Items With Failures description: Number of items with at least one failure default: 0 items_all_passed: type: integer title: Items All Passed description: Number of items with zero failures default: 0 buckets_affected: items: type: string type: array title: Buckets Affected description: Bucket IDs with failures should_alert: type: boolean title: Should Alert description: Whether any failure should trigger alert default: false should_gate_ci: type: boolean title: Should Gate Ci description: Whether any failure should gate CI default: false needs_human_review: type: boolean title: Needs Human Review description: Whether manual review is recommended default: false type: object title: FailureSummary description: Summary of failure analysis results. FailureTagResponse: properties: tag_id: type: string title: Tag Id bucket_id: type: string title: Bucket Id description: Parent bucket ID (L1 category) bucket_name: type: string title: Bucket Name description: Human-readable bucket name subcategory_id: type: string title: Subcategory Id description: Failure subcategory ID (L2 category) subcategory_name: type: string title: Subcategory Name description: Human-readable subcategory name item_index: anyOf: - type: integer - type: 'null' title: Item Index description: 0-based index of the dataset item this tag belongs to decision: type: string title: Decision description: '''pass'', ''fail'', or ''unsure''' severity: type: number maximum: 5 minimum: 0 title: Severity description: Severity score 0-5 confidence: type: number maximum: 1 minimum: 0 title: Confidence description: Confidence score 0-1 detector_type_used: type: string title: Detector Type Used description: '''deterministic'', ''llm_judge'', or ''hybrid''' judge_rationale: anyOf: - type: string - type: 'null' title: Judge Rationale description: LLM judge explanation scoring_breakdown: $ref: '#/components/schemas/ScoringBreakdownResponse' eval_metric_values: additionalProperties: type: number type: object title: Eval Metric Values description: Correlated eval metric scores evidence_items: items: $ref: '#/components/schemas/EvidenceItemResponse' type: array title: Evidence Items type: object required: - tag_id - bucket_id - bucket_name - subcategory_id - subcategory_name - decision - severity - confidence - detector_type_used - scoring_breakdown title: FailureTagResponse description: Single failure tag response. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ScoringBreakdownResponse: properties: impact: type: integer title: Impact description: Impact level 0-3 risk: type: integer title: Risk description: Risk level 0-2 frequency_weight: type: number title: Frequency Weight default: 1 security_override: anyOf: - type: string - type: 'null' title: Security Override deterministic_weight: type: number title: Deterministic Weight default: 0 judge_weight: type: number title: Judge Weight default: 0 security_weight: type: number title: Security Weight default: 0 metric_agreement_bonus: type: number title: Metric Agreement Bonus default: 0 disagreement_penalty: type: number title: Disagreement Penalty default: 0 final_severity: type: number title: Final Severity final_confidence: type: number title: Final Confidence type: object required: - impact - risk - final_severity - final_confidence title: ScoringBreakdownResponse description: Scoring breakdown for a failure tag. EvidenceItemResponse: properties: item_id: type: string title: Item Id evidence_type: type: string title: Evidence Type description: 'Type: ''rationale'', ''unsupported_claim'', ''violation'', etc.' description: type: string title: Description content_snippet: anyOf: - type: string - type: 'null' title: Content Snippet source: type: string title: Source confidence: type: number maximum: 1 minimum: 0 title: Confidence default: 1 metadata: additionalProperties: true type: object title: Metadata type: object required: - item_id - evidence_type - description - source title: EvidenceItemResponse description: Evidence item in a failure tag response. securitySchemes: APIKeyAuth: type: http scheme: bearer description: >- Valiqor API key. Pass as Bearer token: `Authorization: Bearer vq-xxxxxxxxxxxxxxxxxxxx` ````