> ## 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. # Create a watch > Creates a draft watch and starts a backtest on past calls. A key or the copilot may create drafts; only a person can turn a watch on, once enough sample calls are labelled. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents/{agentId}/watches 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}/watches: post: tags: - Watches summary: Create a watch description: >- Creates a draft watch and starts a backtest on past calls. A key or the copilot may create drafts; only a person can turn a watch on, once enough sample calls are labelled. operationId: createWatch 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWatch' responses: '201': description: The watch. content: application/json: schema: $ref: '#/components/schemas/WatchDetail' '400': description: The watch 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' '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' '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/watches" \ -H "Authorization: Bearer $SIGNAL_API_KEY" components: schemas: CreateWatch: type: object properties: name: type: string minLength: 1 description: A short name for the list. lane: type: string enum: - hearing - understanding - flow - speaking - integrations description: >- The lane a defect lives in: hearing, understanding, flow, speaking or integrations. scope: $ref: '#/components/schemas/WatchScope' expectation: $ref: '#/components/schemas/WatchExpectation' required: - name - lane - scope - expectation WatchDetail: allOf: - $ref: '#/components/schemas/Watch' - type: object properties: scope: $ref: '#/components/schemas/WatchScope' expectation: $ref: '#/components/schemas/WatchExpectation' createdBy: type: - string - 'null' backtest: $ref: '#/components/schemas/WatchBacktest' samples: type: array items: $ref: '#/components/schemas/WatchSampleCall' labels: type: object properties: right: type: integer wrong: type: integer labelled: type: integer precision: type: - number - 'null' required: - right - wrong - labelled - precision goLiveBlock: type: - string - 'null' description: Why Turn on is refused, or null when the bar is met. required: - scope - expectation - createdBy - backtest - samples - labels - goLiveBlock 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 WatchScope: type: object properties: text: type: string minLength: 1 description: Where it applies, in the customer's words. code: type: object properties: kind: type: string enum: - tool_called - step_visited tool: type: string step: type: string required: - kind required: - text WatchExpectation: type: object properties: text: type: string minLength: 1 description: What should happen, in the customer's words. polarity: type: string enum: - must - must_not description: 'must: the expectation should hold. must_not: it should not.' code: type: object additionalProperties: {} required: - text - polarity Watch: type: object properties: object: type: string enum: - watch 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 name: type: string lane: type: string enum: - hearing - understanding - flow - speaking - integrations description: >- The lane a defect lives in: hearing, understanding, flow, speaking or integrations. state: type: string enum: - draft - backtesting - review - live - paused - rejected description: >- draft/backtesting while authoring; review once a backtest finished; live once a person turns it on; paused or rejected leave it off. revision: type: integer origin: type: string passRate: type: - number - 'null' description: >- Share of production calls in scope where the expectation held. Null until there are calls to measure. calls: type: integer description: Production calls behind the pass rate. 0 until there are any. precision: type: - number - 'null' description: >- Of the sample calls a person labelled on the current revision, the share labelled right. Null until any are labelled. labelled: type: integer source: type: - object - 'null' properties: agentVersion: type: - integer - 'null' step: type: - string - 'null' line: type: string verbatim: type: boolean description: >- False when the line was not found word for word in the instructions. required: - agentVersion - step - line - verbatim description: >- For a generated watch (origin generated): the agent version and instruction line it was drafted from. Null otherwise. firstSample: type: - object - 'null' properties: inScope: type: integer flagged: type: integer required: - inScope - flagged description: >- On a suggested draft: how many past calls the first backtest found in scope and how many it flagged. Null until that backtest finishes. Precision is not known until the draft is kept and its sample calls are labelled. createdAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' updatedAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' required: - object - id - name - lane - state - revision - origin - passRate - calls - precision - labelled - source - firstSample - createdAt - updatedAt WatchBacktest: type: - object - 'null' properties: watchRevision: type: integer considered: type: integer inScope: type: integer flagged: type: integer createdAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' updatedAt: type: string format: date-time example: '2026-10-02T14:03:07.120Z' required: - watchRevision - considered - inScope - flagged - createdAt - updatedAt WatchSampleCall: type: object properties: callId: 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 kind: type: string enum: - flagged - cleared verdict: type: string quote: type: - string - 'null' turn: type: - integer - 'null' label: type: - string - 'null' enum: - right - wrong - null required: - callId - kind - verdict - quote - turn - label 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.