The Update an agent's custom instructions replaces the custom instruction associated with your user account for a specified agent. You can submit instruction text directly or use an encoded request. For large instructions, the Update an agent's custom instructions supports chunked uploads. A successful update returns the saved instruction, agent identifier, lock status, and last update time.

HTTP method and endpoint

Use the following HTTP method and endpoint path to replace or clear your custom instruction for an agent.

PUT https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions

The following table describes the endpoint path parameters.

Request headers

The following request headers must be included.

Request body

The following table describes the request body parameters, including accepted values and defaults. Include either custom_instruction or encoded_request.

The API accepts a single encoded_request without chunk parameters.

To prepare a large instruction for upload:

1. Optionally, compress the JSON payload using gzip. If you compress the payload, set encoding to gzip.

2. Base64-encode the payload.

3. Divide the encoded payload into chunks of no more than 6,000 characters.

Example request

Use the following example to see how a complete request is structured with headers and a JSON body.

PUT https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "custom_instruction": "Always answer in French."
}

The following example shows how to clear a saved custom instruction.

PUT https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "custom_instruction": ""
}

The following example shows a single encoded request. The encoded_request value represents base64-encoded JSON containing the custom_instruction field.

PUT https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "encoded_request": "<base64_encoded_payload>"
}

The following example shows the first chunk of a three-chunk upload. Subsequent chunks use indexes 1 and 2 with the same session identifier.

PUT https://{host}/ai/agentflow/api/v202605/{tenant_id}/agents/{agent_id}/custom-instructions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "encoded_request": "<base64_encoded_chunk_0>",
  "chunk_session_id": "instruction-upload-001",
  "chunk_index": 0,
  "total_chunks": 3
}

Response body

The following table describes the fields returned in the response body after a successful update.

For a non-final chunk, the API returns HTTP 202 Accepted with a status field containing chunk_received. A completed update returns HTTP 200 OK with the fields listed in the table.

Example response

The following example shows a successful HTTP 200 OK response with the saved custom instruction.

{
  "agent_id": "MRA",
  "custom_instruction": "Always answer in French.",
  "locked": false,
  "updated_at": "2026-10-14T07:58:30.087566Z"
}

The following example shows the HTTP 202 Accepted response for a non-final chunk.

{
  "status": "chunk_received"
}

Error codes and recommended actions

The following table lists the possible error responses returned by this API.