AWawork-io
agentThreads

Creates a conversation with the awork Agent or a custom agent.

Changed on

Creates a conversation with the awork Agent or a custom agent and optionally submits the first message. Supply content or attachments to submit the first message and start processing. awork Agent threads can be created without a message. Custom Agent threads require text or an attachment. The response contains the thread and accepted first-message identifiers, not the agent's reply. See GET /agents/threads/{threadId}/messages to retrieve replies. Each request creates a new thread. Retrying after a lost response can create another thread.

<Check title="Required Permissions" icon="key">Any authenticated user.</Check>

post/agents/threads

Request

  • Base URL
    https://api.awork.com/api/v1
  • URL
    https://api.awork.com/api/v1/agents/threads
  • Auth
    HTTP bearer

Request body

presetKeystring nullable

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

contentstring nullable

The message text. Required when no attachments are supplied.

modelProviderstring nullable

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

modelNamestring nullable

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

reasoningLevelstring nullable

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

connectorIdsstring[] nullable

The connector selection for this message.

skillIdsstring[] nullable

The skill selection for this message.

type'personal-agent' | 'custom-agent' required

Select personal-agent for the awork Agent, or custom-agent for a configured workspace agent.

agentIdstring uuid

The configured agent to run. Required for custom-agent threads; omit for ordinary personal-agent threads.

titlestring nullable

The thread title.

projectIdstring uuid nullable

The project context id.

taskIdstring uuid nullable

The task context id.

clientIdstring uuid nullable

The client context id.

documentIdstring uuid nullable

The document context id.

Response

OK

idstring uuid

The thread id.

threadRunIdstring uuid nullable

The current run id.

acceptedMessageIdstring uuid nullable

The accepted first-message id, or null when the thread was created without a message.

typestring nullable

The thread type.

titlestring nullable

The thread title.

status'ready' | 'accepted' | 'queued' | 'failed'

The creation result: ready without a first message, accepted with a first message, queued when the first message waits for a run, or failed to start.

createdOnstring date-time nullable

The creation timestamp.

createdBystring uuid

The id of the user who created the thread.

updatedOnstring date-time nullable

The last update timestamp.

updatedBystring uuid

The id of the user who last updated the thread.

agentIdstring uuid nullable

The custom agent assigned to the thread.

projectIdstring uuid nullable

The associated project id.

taskIdstring uuid nullable

The associated task id.

clientIdstring uuid nullable

The associated client id.

documentIdstring uuid nullable

The associated document id.

Changes