Agents

Our Agents API allows you to integrate your parcelLab agent in your customer service tools, applications or message interfaces.

Agent Integration Guide

This section describes the basics of using the Agents API to integrate your parcelLab agent into your application or chat interfaces.

Requirements

Before you start, ensure the following prerequisites are met:

• OpenAI opt-in enabled for your parcelLab account

• parcelLab API access

  • Credentials required: parcelLab account ID and API token with read and write scopes

• An agent configured for your account. The agent ID for your parcelLab agent is required for using the API and will be provided after the agent is configured for your account.

How to opt in to OpenAI for your parcelLab account

To use the Agents API, you must opt in to enable OpenAI for your account.

1. Log in to the parcelLab App.

2. Navigate to Admin > Accounts. A list of accounts you have access to will display with the name and ID for each record.

3. Select the account you want to enable the OpenAI opt-in for.

4. In the Opt ins section, select the OpenAI checkbox.

5. Click Save. The OpenAI opt-in is saved for your parcelLab account.

Using the Agents API

To authenticate your API requests, please provide your API token in the request header.

1

Start agent execution

Start by making a request to the agent execution endpoint (that is: v4/agents/{agent_id}/execute) using your agent ID. The response will include a thread ID, which is used to identify a message thread with your agent.

2

Poll the thread status

Using your agent ID and thread ID, you can call the v4/agents/{agent_id}/threads/{thread_ref} endpoint to retrieve the status of the agent execution. When the execution status is completed, display the message from the agent’s response.

3

Submit messages to an existing thread

When the end-user sends a message, you can call the v4/agents/{agent_id}/threads/{thread_ref}/messages endpoint to add it to the existing thread. Repeat the polling until the execution status is complete.

Response Time: The WISMO Agent does not stream responses. Response times may vary depending on the complexity of the query. For chat-based implementations, consider showing a "typing" indicator while polling for results.

Best Practice: Implement a polling mechanism with exponential backoff to avoid excessive API calls while waiting for responses.

Agents API Reference

These requests allow you to start message threads with your pre-configured agent and submit messages to existing threads.

Start Asynchronous Agent Execution

You can start a thread with the agent using the v4/agents/{agent_id}/execute endpoint.

Start async agent execution

post

Starts agent execution asynchronously and returns a thread reference immediately. Use the thread reference to poll for results.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

agent_idstring · uuidRequired

External ID of this agent, used on the simple agent thread API

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Payload for starting async agent execution.

querystring · min: 1Required

The user's input query

contextobjectOptional

Optional context data for the agent

Responses

201Success

application/json

400Error

application/json

403Error

application/json

404Error

application/json

post

/v4/agents/{agent_id}/execute/

HTTPcURLJavaScriptPython

POST /v4/agents/{agent_id}/execute/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "query": "text",
  "context": {}
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "threadId": "text",
  "executionStatus": "text"
}

Get Thread Status and Messages

You can retrieve the current status and messages of an agent thread using the v4/agents/{agent_id}/threads/{thread_ref} endpoint.

Get thread status and messages

get

Retrieve the current status and messages of an agent thread.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

agent_idstring · uuidRequired

External ID of this agent, used on the simple agent thread API

thread_refstringRequired

External reference ID of the thread

Responses

200Success

application/json

Public-facing thread details with limited message info.

idintegerRead-onlyRequired

accountintegerRequired

agentstring · uuidRequired

External ID of this agent, used on the simple agent thread API

userintegerRead-onlyRequired

executionStatusstring · enumOptional

• idle - Idle
• running - Running
• completed - Completed
• failed - Failed

Possible values:

createdAtstring · date-timeRead-onlyRequired

updatedAtstring · date-timeRead-onlyRequired

400Error

application/json

403Error

application/json

404Error

application/json

get

/v4/agents/{agent_id}/threads/{thread_ref}/

HTTPcURLJavaScriptPython

GET /v4/agents/{agent_id}/threads/{thread_ref}/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "account": 1,
  "agent": "123e4567-e89b-12d3-a456-426614174000",
  "user": 1,
  "executionStatus": "idle",
  "createdAt": "2026-03-09T16:54:13.954Z",
  "updatedAt": "2026-03-09T16:54:13.954Z",
  "messages": [
    {
      "type": "input_message",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "query": "text"
    }
  ]
}

Submit Message to Existing Thread

You can submit messages to existing threads using the v4/agents/{agent_id}/threads/{thread_ref}/messages endpoint.

Add message to existing thread

post

Async add a new message to an existing thread.

Authorizations

OAuth2 AuthenticationHeaderToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

agent_idstring · uuidRequired

External ID of this agent, used on the simple agent thread API

thread_refstringRequired

External reference ID of the thread

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Payload for starting async agent execution.

querystring · min: 1Required

The user's input query

contextobjectOptional

Optional context data for the agent

Responses

200Success

application/json

Response for async agent execution.

threadIdstringRequired

External reference ID of the thread

executionStatusstringRequired

Current execution status

400Error

application/json

403Error

application/json

404Error

application/json

post

/v4/agents/{agent_id}/threads/{thread_ref}/messages/

HTTPcURLJavaScriptPython

POST /v4/agents/{agent_id}/threads/{thread_ref}/messages/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "query": "text",
  "context": {}
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "threadId": "text",
  "executionStatus": "text"
}