> ## Documentation Index > Fetch the complete documentation index at: https://docs.signalmd.dev/llms.txt > Use this file to discover all available pages before exploring further. # Test a draft > Runs the draft in Retell's simulation on a shadow copy at its exact text. attempt: the draft's new cases plus the guard set, refused with 422 `not_reproduced` until every new case reproduces the problem on the live agent. full_suite: every accepted case, the run a publish through the API needs. This spends like a run. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents/{agentId}/drafts/{draftId}/test openapi: 3.1.0 info: title: SignalMD API version: 1.0.0 description: >- SignalMD reads a voice agent's production calls and says what to fix, then tests whether the fix worked. This API exposes the same data the web app shows: agents, calls and their traces, signals, issues, versions and their comparisons, tests, and test runs. Authenticate with `Authorization: Bearer sig_...` (an API key from the API keys page). Read keys may call every `read` operation; write keys may also call `write` operations, within their monthly budget. Each operation's scope is in `x-signal-scope`. Errors share one envelope (`Error`), lists share one cursor scheme (`limit`, `cursor`, `hasMore`, `nextCursor`), and every response carries `Request-Id` and `RateLimit-*` headers. servers: - url: https://api.signalmd.dev description: Production - url: http://localhost:43124 description: Local development security: - bearerAuth: [] tags: - name: Account description: Who the token belongs to and what it may do. - name: Agents description: Voice agents connected to the workspace. - name: Calls description: Production calls, their traces and per-call signals. - name: Signals description: What SignalMD noticed across calls. - name: Issues description: 'Problems worth fixing: where, why, and what to change.' - name: Versions description: Agent versions and how each one did. - name: Comparisons description: Stored comparisons between two versions. - name: Tests description: Tests, test sets, personas and coverage. - name: Runs description: Test runs and the attempts inside them. paths: /v1/agents/{agentId}/drafts/{draftId}/test: post: tags: - Drafts summary: Test a draft description: >- Runs the draft in Retell's simulation on a shadow copy at its exact text. attempt: the draft's new cases plus the guard set, refused with 422 `not_reproduced` until every new case reproduces the problem on the live agent. full_suite: every accepted case, the run a publish through the API needs. This spends like a run. operationId: testDraft parameters: - schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f description: The agent's id. required: true description: The agent's id. name: agentId in: path - schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f description: The draft's id. required: true description: The draft's id. name: draftId in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestDraftRequest' responses: '202': description: The run started. content: application/json: schema: $ref: '#/components/schemas/DraftTestStarted' '400': description: 'Invalid request: a parameter or the body failed validation.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid or revoked credentials. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: The budget does not cover the run. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: A read-only key, or a write to the shared demo agent. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- The agent, or a resource under it, does not exist or is not visible to this key. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- A new case has not reproduced the problem (not_reproduced), the draft has none (no_new_cases), or the agent has no accepted case (no_accepted_cases). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. See Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Server error. The message is generic; quote the request id. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: curl source: >- curl -X POST "https://api.signalmd.dev/v1/agents/6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b/drafts//test" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: TestDraftRequest: type: object properties: scope: type: string enum: - attempt - full_suite goalId: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f required: - scope DraftTestStarted: type: object properties: object: type: string enum: - draft_test runId: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f scope: type: string enum: - attempt - full_suite draft: $ref: '#/components/schemas/Draft' required: - object - runId - scope - draft Error: type: object properties: error: type: object properties: type: $ref: '#/components/schemas/ErrorType' code: type: string example: agent_not_found description: The specific reason; stable within v1. message: type: string example: Agent not found. param: type: - string - 'null' description: The request field at fault, for a validation error. requestId: type: - string - 'null' example: req_8c1f0e2b4a6d9e3f7a5c1b0d quota: type: object properties: metric: type: string example: credits description: >- credits when the workspace's monthly credits are used up, or agents when the plan's agent limit is reached. activity: type: string enum: - observation - testing - chat example: testing description: >- With metric credits: what the request would have spent them on. observation is analysing calls, testing is test runs, chat is the copilot. requested: type: integer example: 18 description: >- With metric credits: the credits the request needed to start. limit: type: integer description: 'The plan''s limit: the month''s credits, or its agents.' used: type: integer description: How much of the limit is used this month. plan: type: string example: free_org description: The workspace's plan slug. upgradePath: type: string example: /billing description: Where in the web app the plan is changed. required: - metric - limit - used - plan - upgradePath description: >- Present when code is quota_exceeded: the plan limit the request would pass. proposalId: type: string format: uuid description: >- Present when code is criteria_locked: the pending criteria proposal the change was filed as. A person approves or rejects it. required: - type - code - message - param - requestId required: - error example: error: type: not_found_error code: agent_not_found message: Agent not found. param: null requestId: req_8c1f0e2b4a6d9e3f7a5c1b0d Draft: type: object properties: object: type: string enum: - draft id: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f agentId: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f title: type: string rationale: type: string status: type: string enum: - draft - testing - publishing - published - discarded baseVersion: type: integer baseHash: type: string draftHash: type: string description: 'The content hash of the draft''s text: what a publish must confirm.' revision: type: integer description: 'Bumped by every change to the text: what a publish must confirm.' stale: type: boolean canPublish: type: boolean publishBlockedReason: type: string newCaseIds: type: array items: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f suiteGate: type: object properties: mode: type: string enum: - ran - passed ok: type: boolean reason: type: string enum: - no_suite_run - suite_running - suite_failed - suite_incomplete detail: type: string batchId: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: 3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f required: - mode - ok description: >- Whether the whole accepted suite ran (and, for a key, passed) on this exact text. required: - object - id - agentId - title - rationale - status - baseVersion - baseHash - draftHash - revision - stale - canPublish additionalProperties: {} description: A draft, with its diff, its tests and why it can or cannot be published. ErrorType: type: string enum: - invalid_request_error - authentication_error - budget_error - permission_error - not_found_error - conflict_error - rate_limit_error - api_error securitySchemes: bearerAuth: type: http scheme: bearer description: An API key (`sig_...`), or a session token from the web app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.