> ## Documentation Index > Fetch the complete documentation index at: https://www.thred.dev/llms.txt > Use this file to discover all available pages before exploring further. # Cancel a collection > Request cancellation of an open collection, then poll for its final status. No request body is needed. Repeated requests and requests for already closed collections return the current state. ## OpenAPI ````yaml api-reference/openapi.json POST /v1/collect/{id}/cancel openapi: 3.0.3 info: title: Thred API version: 1.0.0 description: >- Thred is the data API for the phone. Use Collect when you know who to ask: send a phone number and instructions, add context values in input, and define the answers you want with a JSON Schema in output. Use the same base URL for Development and Production; your API key selects the environment. servers: - url: https://api.thred.dev description: Thred API security: - bearerAuth: [] tags: - name: Authentication description: Verify the workspace and environment selected by your API key. - name: Collect description: Collect structured answers from a known phone number. - name: Usage description: Read daily operational usage. - name: Health description: Check public API availability. paths: /v1/collect/{id}/cancel: parameters: - name: id in: path required: true description: >- The collection ID returned when the request was accepted. IDs use the call_ prefix. schema: type: string pattern: ^call_[a-z0-9-]+$ example: call_123e4567-e89b-42d3-a456-426614174000 post: tags: - Collect summary: Cancel a collection description: >- Request cancellation of an open collection, then poll for its final status. No request body is needed. Repeated requests and requests for already closed collections return the current state. operationId: cancelCollection responses: '202': description: >- Cancellation recorded, or the current state of an already closed or cancel-requested collection. content: application/json: schema: $ref: '#/components/schemas/Cancellation' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/Unavailable' components: schemas: Cancellation: allOf: - $ref: '#/components/schemas/Call' - type: object properties: navigation_routes: type: array maxItems: 16 items: $ref: '#/components/schemas/NavigationRoute' description: >- Included when the call is already closed, terminal, or previously marked for cancellation. description: >- Current collection state. Retrieve the collection to confirm it reaches a terminal status. Call: type: object properties: id: type: string example: call_123e4567-e89b-42d3-a456-426614174000 description: The collection ID, using the call_ prefix. environment: $ref: '#/components/schemas/Environment' status: $ref: '#/components/schemas/CallStatus' handling: $ref: '#/components/schemas/CallHandling' to: type: string example: '+14155550123' description: Destination in E.164 format. from: type: string example: '+12025550124' description: Outbound caller number in E.164 format. created_at: type: string format: date-time description: UTC creation time. updated_at: type: string format: date-time description: UTC time of the latest update. started_at: type: string nullable: true format: date-time description: UTC job start time, or null before startup. ended_at: type: string nullable: true format: date-time description: >- UTC job end time, or null until closure. Results may still be processing afterward. human_assisted: type: boolean description: >- Whether an internal operator assisted the live call. Assisted results require approval before publication. outcome: type: string nullable: true description: >- Call closure reason, when known. Use status to determine whether results are final. data: type: object nullable: true additionalProperties: true description: >- Complete answers matching output, or null before publication / when no complete result exists. partial_data: type: object nullable: true additionalProperties: true description: >- Available answers when a complete result could not be obtained. Missing required fields may be omitted, but remaining schema constraints still apply. missing_fields: type: array items: type: string description: >- Validation messages for unavailable answers, including the field path. Empty for completed and canceled collections. error: type: object nullable: true properties: code: type: string message: type: string required: - code - message description: >- Collection failure details. This is separate from an HTTP error response. duration_seconds: type: number nullable: true description: Elapsed job duration; not provider billable talk time. usage: $ref: '#/components/schemas/CallUsage' recording_status: $ref: '#/components/schemas/RecordingStatus' recording: $ref: '#/components/schemas/Recording' cancellation_requested: type: boolean description: >- True once a cancellation request is recorded; does not by itself mean the call has ended. screener_sequence: type: array nullable: true items: $ref: '#/components/schemas/ScreenerMessage' description: >- Prepared or supplied screener messages, or null while preparation is pending. screener_sequence_source: type: string nullable: true enum: - provided - generated - null description: Whether screener messages were supplied or generated. navigation_cache_source_call_id: type: string nullable: true description: Prior call whose eligible navigation steps were loaded, or null. request: $ref: '#/components/schemas/CallRequestSnapshot' required: - id - environment - status - handling - to - from - created_at - updated_at - started_at - ended_at - human_assisted - outcome - data - partial_data - missing_fields - error - duration_seconds - usage - recording_status - recording - cancellation_requested - screener_sequence - screener_sequence_source - navigation_cache_source_call_id - request description: >- A collection and its published results. List responses return this shape. Detail responses also include navigation_routes. NavigationRoute: type: object properties: navigation_id: type: string description: Navigation episode identifier. status: type: string description: Navigation episode status. result: type: string nullable: true description: Navigation outcome, when known. reusable: type: boolean description: >- Whether successful steps are eligible for automatic reuse on a matching future call. steps: type: array items: $ref: '#/components/schemas/NavigationStep' required: - navigation_id - status - result - reusable - steps ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error Environment: type: string enum: - development - production description: >- The API key selects the workspace environment. Development and Production are isolated, but either can place real calls when enabled. CallStatus: type: string enum: - queued - dialing - in_progress - processing - awaiting_review - completed - incomplete - failed - canceled description: >- Final: completed, incomplete, failed, canceled. Continue polling for all other statuses. CallHandling: type: string enum: - ai - awaiting_operator - operator description: >- Who is handling the call: AI, waiting for an internal operator, or an internal operator. CallUsage: type: object properties: elapsed_job_seconds: type: number nullable: true description: >- Elapsed job duration, including setup and waiting. Not a billable duration. billed_seconds: type: number nullable: true enum: - null description: Always null until provider billing reconciliation is available. billing_status: type: string enum: - unreconciled required: - elapsed_job_seconds - billed_seconds - billing_status RecordingStatus: type: string enum: - disabled - pending - starting - recording - processing - ready - failed description: >- Recording progresses independently of the call result. Hosted recording is currently disabled. Recording: type: object properties: status: $ref: '#/components/schemas/RecordingStatus' duration_seconds: type: number nullable: true description: Recorded audio duration, when available. audio_started_at: type: string nullable: true format: date-time description: Start of the recording audio clock, when available. error: type: string nullable: true description: Recording failure details, if any. required: - status - duration_seconds - audio_started_at - error ScreenerMessage: type: object properties: message: type: string minLength: 1 maxLength: 500 description: Approved spoken copy; must contain non-whitespace text. type: type: string enum: - intro - detail description: The first message must be intro; all later messages must be detail. required: - message - type additionalProperties: false CallRequestSnapshot: allOf: - $ref: '#/components/schemas/CreateCallRequest' - type: object required: - input - max_duration_seconds - metadata - record description: >- The accepted request with defaults applied and text normalized. Client metadata remains available here. NavigationStep: type: object properties: menu: type: string description: Observed menu text. action: $ref: '#/components/schemas/NavigationAction' status: type: string enum: - authorized - executing - sent - failed - uncertain - canceled required: - menu - action - status ErrorDetail: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable error explanation. required: - code - message CreateCallRequest: type: object properties: to: type: string pattern: ^\+[1-9]\d{6,14}$ example: '+14155550123' description: Destination phone number in E.164 format. instructions: type: string minLength: 1 maxLength: 8000 description: >- What you want to find out. Thred manages conversation, navigation, and assistance. Must contain non-whitespace text. input: type: object additionalProperties: true default: {} description: >- Known context values for the call, such as a date, product name, or reference number. Must be a JSON object; optional and defaults to an empty object. Up to 16,000 bytes of JSON. Maximum depth: 32; maximum values: 8,192. example: date: today output: $ref: '#/components/schemas/OutputSchema' max_duration_seconds: type: integer default: 300 minimum: 30 maximum: 1800 description: >- Maximum job duration. Your workspace and environment may have a lower limit. caller_number_id: type: string minLength: 1 maxLength: 160 description: >- Enabled caller number ID belonging to the same workspace and environment. Omit to use the environment default. webhook_id: type: string minLength: 1 maxLength: 160 description: >- Enabled webhook endpoint ID from your dashboard, in the same workspace and environment. Omit to poll for results. navigation: $ref: '#/components/schemas/Navigation' screener_sequence: type: array minItems: 1 maxItems: 8 items: $ref: '#/components/schemas/ScreenerMessage' description: >- An intro followed by optional detail messages for screeners. If omitted, Thred prepares a sequence from the task and input before dialing. metadata: type: object additionalProperties: true default: {} description: >- Your tracking fields, up to 4,000 bytes of JSON. Maximum depth: 32; maximum values: 8,192. record: type: boolean default: false description: >- Recording is currently disabled. Leave false or omit; true returns 503. required: - to - instructions - output description: Send UTF-8 JSON, up to 64 KiB. Unknown fields are rejected. additionalProperties: false NavigationAction: oneOf: - type: object properties: kind: type: string enum: - press-digits digits: type: string description: Digits sent to the phone menu. required: - kind - digits additionalProperties: false - type: object properties: kind: type: string enum: - speak text: type: string description: Spoken menu response. required: - kind - text additionalProperties: false OutputSchema: type: object properties: type: type: string enum: - object description: >- Optional. The output root is always an object; omit this field when creating a collection. default: object description: type: string maxLength: 2000 description: Explain what the answer should contain. title: type: string maxLength: 2000 properties: type: object description: >- Object fields. Names must contain 1–120 characters and cannot be __proto__, prototype, or constructor. additionalProperties: $ref: '#/components/schemas/OutputSchemaNode' required: type: array description: >- Unique names declared in properties. Required answers that cannot be obtained prevent a completed result. uniqueItems: true items: type: string additionalProperties: type: boolean enum: - false description: Required and always false for every object schema. required: - properties - additionalProperties description: >- The JSON Schema defining the answers returned in data. The output root is always an object, so no top-level type is needed. Define properties and required fields, and set additionalProperties to false. additionalProperties: false example: properties: is_open: type: boolean closes_at: type: string required: - is_open - closes_at additionalProperties: false Navigation: type: object properties: contact_name: type: string minLength: 1 maxLength: 160 description: Person to ask for. department: type: string minLength: 1 maxLength: 160 description: Department to reach. extension: type: string minLength: 1 maxLength: 16 pattern: ^[0-9]+$ description: >- Extension hint, used when an appropriate extension-entry prompt is heard. language: type: string minLength: 1 maxLength: 160 pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8}){0,3}$ example: en description: Language tag, such as en or fr-CA. description: >- Optional routing hints. IVR navigation is automatic. Custom routes, actions, and navigation policy overrides are not accepted. additionalProperties: false OutputSchemaNode: type: object properties: type: description: >- One supported type, or an array containing one supported non-null type and null. An object schema must include properties and additionalProperties: false; an array schema must include items. oneOf: - type: string enum: - object - array - string - number - integer - boolean - 'null' - type: array minItems: 1 maxItems: 2 uniqueItems: true items: type: string enum: - object - array - string - number - integer - boolean - 'null' description: type: string maxLength: 2000 description: Explain what the answer should contain. title: type: string maxLength: 2000 properties: type: object description: >- Object fields. Names must contain 1–120 characters and cannot be __proto__, prototype, or constructor. additionalProperties: type: object additionalProperties: true description: >- A nested schema with the same supported fields. Every node needs type; objects need properties and additionalProperties: false; arrays need items. required: type: array description: >- Unique names declared in properties. Required answers that cannot be obtained prevent a completed result. uniqueItems: true items: type: string additionalProperties: type: boolean enum: - false description: Required and always false for every object schema. items: type: object additionalProperties: true description: The schema for each array item, using the same supported fields. enum: type: array minItems: 1 maxItems: 100 items: oneOf: - type: string nullable: true - type: number - type: boolean description: >- Primitive string, number, boolean, or null values. Each value must satisfy the declared type and bounds. minItems: type: integer minimum: 0 maximum: 10000 maxItems: type: integer minimum: 0 maximum: 10000 minLength: type: integer minimum: 0 maximum: 10000 maxLength: type: integer minimum: 0 maximum: 10000 minimum: type: number maximum: type: number required: - type description: >- Supported JSON Schema fields. Maximum 128 nodes and 8 nesting levels below the root. Keywords must match their type; minimum bounds cannot exceed maximum bounds. additionalProperties: false responses: Unauthorized: description: >- Missing, malformed, invalid, revoked, or environment-mismatched bearer API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: >- No matching collection in this key’s workspace and environment, or the endpoint does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unavailable: description: >- Calling or the backend is unavailable. Codes include calling_unavailable, environment_unavailable, not_configured, and backend_unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Thred API key description: >- Send Authorization: Bearer . Development keys begin thr_dev_; Production keys begin thr_prod_. Each key is scoped to a workspace and environment. Keep secrets on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.