API v1 Reference › AgentThreads

Cancels the active run for the specified agent thread.

POSThttps://api.awork.com/api/v1/agents/threads/{threadId}/cancel
POST https://api.awork.com/api/v1/agents/threads/{threadId}/cancel

Cancels the active run in the specified personal-agent or custom-agent conversation and returns the thread. A successful cancellation also pauses dispatch of the next queued message.

Authentication

AuthorizationBearer

Send your token in the Authorization: Bearer <token> header. See Authentication for API keys and OAuth.

Path parameters

threadIdstringRequired
format: uuid

The thread id.

Responses

200 OK

application/json

idstringOptional
format: uuid

The id of the entity.

createdOnstringOptional
format: date-time

The date this entity was created.

createdBystringOptional
format: uuid

The id of the user who created this entity.

updatedBystringOptional
format: uuid

The id of the user who last modified this entity.

usageobjectOptional

Recorded usage converted with the current reporting credit rates.

Show 2 properties
creditsUsedintegerOptional
format: int64

Whole-credit total rounded up once.

lastUsageOnstring or nullOptional
format: date-time

Time of the latest included usage record; this does not indicate run completion.

updatedOnstringOptional
format: date-time

The parent timestamp used to order thread queue snapshots, with subsecond precision.

typestring or nullOptional

The thread type.

titlestring or nullOptional

The thread title.

statusstring or nullOptional

The thread status.

isReadOnlybooleanOptional

Whether the requester may only read this thread.

isSharedbooleanOptional

Whether this directly shareable thread currently has active shares.

viewerAccessobjectOptional

Describes the requester's current shared-thread capabilities.

Show 10 properties
canReadbooleanOptional

Whether the requester can read the thread.

canWritebooleanOptional

Whether the effective share grants Manage access. The field name preserves the existing API contract.

isJoinedbooleanOptional

Whether the requester joined the thread.

canJoinbooleanOptional

Whether the requester can Join.

canSendbooleanOptional

Whether the requester can send.

canStopbooleanOptional

Whether the requester can stop active work.

canManageThreadbooleanOptional

Whether the requester can rename or delete the thread.

canManageSharingbooleanOptional

Whether the requester can manage sharing.

canLeavebooleanOptional

Whether the requester can leave.

sendBlockedReasonstring or nullOptional

The reason that prevents sending.

contributorsarray of object or nullOptional

The users who explicitly joined this thread.

Show 3 properties
idstringOptional
format: uuid

The contributor identifier.

userIdstringOptional
format: uuid

The user identifier.

accessLevelstring or nullOptional

The contributor access level.

activityUsersarray of object or nullOptional

Current details for users referenced by membership and sharing activities on detail responses.

Show 4 properties
idstringOptional
format: uuid

The identifier of the nested model.

firstNamestring or nullOptional

The first name of the user.

lastNamestring or nullOptional

The last name of the user.

hasImageboolean or nullOptional

Whether this user has a profile image.

queuearray of object or nullOptional

The queued thread messages in dispatch order.

Show 13 properties
idstringOptional
format: uuid

The id of the entity.

createdOnstringOptional
format: date-time

The date this entity was created.

createdBystringOptional
format: uuid

The id of the user who created this entity.

updatedOnstringOptional
format: date-time

The date this entity was last modified.

updatedBystringOptional
format: uuid

The id of the user who last modified this entity.

threadUpdatedOnstring or nullOptional
format: date-time

The parent timestamp saved with an edit; absent on queue snapshot rows.

threadIdstringOptional
format: uuid

The owning thread id.

queueOrderintegerOptional
format: int32

The position in the queue.

displayTextstring or nullOptional

The text shown in the queue.

payloadobjectOptional

Submits a follow-up message or answers a pending question in an agent conversation.

Show 11 properties
presetKeystring or nullOptional

The custom-agent preset. Its current settings override the supplied model and reasoning.

contentstring or nullOptional

The message text. Required when no attachments are supplied.

attachmentsarray of object or nullOptional
maxItems: 20

Up to 20 distinct files attached to this message. Each file can contain up to 20 MiB. Upload new files before submitting their identifiers.

Show 2 properties
temporaryFileIdstring or nullOptional
format: uuid

The identifier returned when uploading a temporary file. Do not also supply aworkFileId.

aworkFileIdstring or nullOptional
format: uuid

The identifier of an existing awork file the caller can read. Do not also supply temporaryFileId.

modelProviderstring or nullOptional

The provider for a model override. Supply it together with modelName.

modelNamestring or nullOptional

The model to use for this message. It must be available in the workspace.

reasoningLevelstring or nullOptional

The reasoning level for this message. Supported values depend on the selected model.

toolAccessobjectOptional

Per-message agent tool access options.

Show 4 properties
aworkbooleanOptional

Whether awork tools are enabled for this run.

webSearchbooleanOptional

Whether web search is enabled for this run.

googleGenAibooleanOptional

Whether Google GenAI tools are enabled for this run.

openAiImageGenerationbooleanOptional

Whether OpenAI image generation is enabled for this run.

connectorIdsarray of string or nullOptional

The connector selection for this message.

connectorConnectionsarray of object or nullOptional

Connection choices for custom-agent connectors. These do not change agent settings.

Show 2 properties
connectorIdstringOptional
format: uuid

The connector identifier.

connectionIdstringOptional
format: uuid

The connection identifier.

skillIdsarray of string or nullOptional

The skill selection for this message.

answerToInterruptIdstring or nullOptional

The interrupt identifier returned with the question being answered.

attachmentsarray of object or nullOptional

Attachment display metadata resolved by the server. This metadata is not part of the editable request.

Show 5 properties
idstring or nullOptional

The resource id.

namestring or nullOptional

The display name.

mimeTypestring or nullOptional

The file media type.

sandboxPathstring or nullOptional

The canonical sandbox path assigned after file promotion.

downloadUrlstring or nullOptional

The relative file download URL.

responsibleUserIdstringOptional
format: uuid

The user whose permissions apply at dispatch time.

blockedReasonstring or nullOptional

The stable reason that prevents automatic dispatch.

agentIdstring or nullOptional
format: uuid

The agent used for the initial execution.

agentNameSnapshotstring or nullOptional

The immutable initial agent name.

executionOwnerUserIdstring or nullOptional
format: uuid

The user whose permissions applied to the initial execution.

executionTriggeredByUserIdstring or nullOptional
format: uuid

The user who triggered the initial execution.

executionTypestring or nullOptional

The initial execution type.

executionSourceIdstring or nullOptional
format: uuid

The entity that caused the initial execution.

modelProviderstring or nullOptional

The model provider.

modelNamestring or nullOptional

The provider model name.

parentThreadIdstring or nullOptional
format: uuid

The parent thread id.

projectIdstring or nullOptional
format: uuid

The associated project id.

taskIdstring or nullOptional
format: uuid

The associated task id.

clientIdstring or nullOptional
format: uuid

The associated client id.

documentIdstring or nullOptional
format: uuid

The associated document id.

startedOnstring or nullOptional
format: date-time

When execution started.

completedOnstring or nullOptional
format: date-time

When execution completed.

lastActivityOnstring or nullOptional
format: date-time

The latest activity timestamp.

lastActivityBystring or nullOptional
format: uuid

The user responsible for the latest user-message activity.

failureReasonstring or nullOptional

The failure reason.

lastSequenceintegerOptional
format: int64

The latest persisted event sequence.

latestThreadUpdateSequenceintegerOptional
format: int64

The latest event sequence that creates a thread update.

hasUpdatebooleanOptional

Whether the requester has an unseen update.

isUnseenbooleanOptional

Whether the requester explicitly marked this thread unseen.

isArchivedbooleanOptional

Whether the requester archived the thread.

archivedOnstring or nullOptional
format: date-time

When the requester archived the thread.

isPinnedbooleanOptional

Whether the requester pinned the thread.

pinnedOrdernumber or nullOptional
format: double

The requester's pinned order.

listStateUpdatedOnstring or nullOptional
format: date-time

When the requester's archive or pin state last changed.

isAwaitingActionbooleanOptional

Whether the thread awaits user action.

pendingBatchConfirmationobjectOptional

Represents a pending batch confirmation for an agent thread.

Show 6 properties
confirmationIdstring or nullOptional

The confirmation id.

confirmationMessagestring or nullOptional

The confirmation message.

affectedItemCountintegerOptional
format: int32

The affected item count.

isDestructivebooleanOptional

Whether the action is destructive.

confirmationDetailsobjectOptional

Detailed confirmation information for the UI with both English and German translations.

Show 13 properties
headerMessageEnstring or nullOptional

The English confirmation heading.

headerMessageDestring or nullOptional

The German confirmation heading.

descriptionEnstring or nullOptional

The English text below the heading that explains the action, or null when the heading is enough.

descriptionDestring or nullOptional

The German text below the heading that explains the action, or null when the heading is enough.

confirmationQuestionEnstring or nullOptional

The English confirmation question.

confirmationQuestionDestring or nullOptional

The German confirmation question.

confirmButtonTextEnstring or nullOptional

The English confirm button label.

confirmButtonTextDestring or nullOptional

The German confirm button label.

cancelButtonTextEnstring or nullOptional

The English cancel button label.

cancelButtonTextDestring or nullOptional

The German cancel button label.

isDestructivebooleanOptional

Whether the action is destructive.

totalItemCountintegerOptional
format: int32

The total item count.

actionsarray of object or nullOptional

The actions that require confirmation.

Show 7 properties
actionDescriptionEnstring or nullOptional

The English action description.

actionDescriptionDestring or nullOptional

The German action description.

itemNamesarray of string or nullOptional

The displayed affected item names.

itemsToggleLabelEnstring or nullOptional

The English label of a toggle that shows the item names. When set, the item names start hidden.

itemsToggleLabelDestring or nullOptional

The German label of a toggle that shows the item names. When set, the item names start hidden.

itemCountintegerOptional
format: int32

The item count.

hasMoreItemsbooleanOptional

Whether more affected items exist.

pendingToolCallsarray of object or nullOptional

The tool calls awaiting confirmation.

Show 7 properties
idstring or nullOptional

The provider tool call identifier.

toolNamestring or nullOptional

The runtime tool that was called.

connectorIdstring or nullOptional
format: uuid

The connector that supplied the tool, if applicable.

connectionIdstring or nullOptional
format: uuid

The connector connection used by the tool, if applicable.

argumentsobject or nullOptional

The structured arguments supplied to the tool.

Show schema

object or null

Additional properties

any

responsestring or nullOptional

The serialized tool result.

chartBlockstring or nullOptional

The serialized native chart block produced by code mode, when present.

pendingUserQuestionobjectOptional

Represents a pending user question for an agent thread.

Show 2 properties
toolCallIdstring or nullOptional

The tool call id.

userQuestionobjectOptional

Describes a user action that must complete before an agent run can resume.

Show 10 properties
questionstring or nullOptional

The user-facing question.

optionsarray of string or nullOptional

The bounded selectable answers.

allowCustomTextbooleanOptional

Whether a custom text answer is accepted.

interactionTypestring or nullOptional

The structured interaction type.

skillIdstring or nullOptional
format: uuid

The skill whose secure access form is requested.

skillAgentIdstring or nullOptional
format: uuid

The agent granting access to the skill, when needed.

connectorIdstring or nullOptional
format: uuid

The connector that requires user action.

connectionIdstring or nullOptional
format: uuid

The connection that requires reauthorization.

connectorNamestring or nullOptional

The safe connector display name.

connectionActionstring or nullOptional

The enable or reconnect action.

usedConnectorsarray of object or nullOptional

Connectors used successfully in this thread on detail responses.

Show 3 properties
idstringOptional
format: uuid

The connector identifier.

namestring or nullOptional

The connector name captured at its latest successful use.

logoPathstring or nullOptional

The predefined connector logo path, when available.

contextWindowUsageRationumber or nullOptional
format: double

The context-window usage ratio on detail responses.

ratingstring or nullOptional

The personal-thread rating on detail responses.

404 Not Found

application/json

codestringRequired
minLength: 1

The error code.

descriptionstringRequired
minLength: 1

The description of the error.

linkstringRequired
minLength: 1

The link to the API documentation page.

detailsarray of string or nullOptional

A list of details describing the error.

validationErrorsarray of object or nullOptional

If a validation error occurred, this contains the validation errors for each property.

Show 2 properties
propertystring or nullOptional

The name of the property that failed validation.

messagestring or nullOptional

The reason why this property failed validation.

traceIdstring or nullOptional

The request trace id for tracking the request.

Search documentation