> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tryenvoy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tryenvoy.ai/_mcp/server.

# Assign or unassign loads to the AI agent

POST https://tryenvoy.ai/api/v1/loads/assign-ai-agent
Content-Type: application/json

Assign one or more loads to the AI agent (`assigned=true`) or unassign them (`assigned=false`) by toggling the dedicated `assigned_to_ai_agent` flag — the source of truth for automated outreach, independent of the carrier rep the source TMS syncs. Both assign and unassign are open to any organization member (and any org API key) by design — every change is audited with actor attribution. Best-effort: load ids that are unknown or belong to another organization are returned in `skipped`.

**Authentication:** Supports API key and bearer token authentication.

Reference: https://docs.tryenvoy.ai/api-reference/endpoints/api/assign-loads-to-ai-agent-api-v-1-loads-assign-ai-agent-post

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://tryenvoy.ai/api/v1` (Production, default)
- `https://staging.tryenvoy.ai/api/v1` (Staging)

## Request

### Headers

- `X-Organization-ID` (string, optional, nullable)
- `Idempotency-Key` (string, optional) — A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with `Idempotent-Replayed: true` instead of running twice. The same key with a different request returns 422 `idempotency_key_reused`; while the first request is still running, 409 `idempotency_key_in_progress`. 5xx and 429 responses are not stored.

### Body (application/json)

This endpoint expects a LoadAssignAIAgentRequest.

- `load_ids` (list of string, required) — Loads to (un)assign to the AI agent (prefixed or raw UUIDs).
- `assigned` (boolean, required) — True to assign the loads to the AI agent, False to unassign them.

## Response

### 200

Successful Response

- `assigned_to_ai_agent` (boolean, required) — The requested state applied to the loads below.
- `applied` (list of string, optional) — Loads whose assigned_to_ai_agent now holds the requested state.
- `skipped` (list of LoadAssignSkipped, optional) — Loads that could not be updated (invalid / cross-org ids).

## Errors

### 401 Unauthorized Error

Not authenticated - missing or invalid token/API key

- `any`

### 403 Forbidden Error

Insufficient permissions for this operation

- `any`

### 409 Conflict Error

`idempotency_key_in_progress`: a request with this Idempotency-Key is still running; retry later

- `any`

### 422 Unprocessable Entity Error

Validation Error; or `idempotency_key_reused`: this Idempotency-Key was already used for a different request

- `detail` (list of ValidationError, optional)

### 429 Too Many Requests Error

Rate limit exceeded - see Retry-After header

- `any`

## Types

### LoadAssignSkipped

One load that the best-effort bulk (un)assign could not apply.

- `load_id` (string, required)
- `reason` (string, required) — Why the load was skipped (e.g. 'not_found' — unknown id or other org).

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (ValidationErrorCtx, optional)

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Request**

```json
{
  "load_ids": [
    "string"
  ],
  "assigned": true
}
```

**Response**

```json
{
  "assigned_to_ai_agent": true,
  "applied": [
    "load_00000000-0000-0000-0000-000000000000"
  ],
  "skipped": [
    {
      "load_id": "load_00000000-0000-0000-0000-000000000000",
      "reason": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://tryenvoy.ai/api/v1/loads/assign-ai-agent"

payload = {
    "load_ids": ["string"],
    "assigned": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://tryenvoy.ai/api/v1/loads/assign-ai-agent';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"load_ids":["string"],"assigned":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tryenvoy.ai/api/v1/loads/assign-ai-agent"

	payload := strings.NewReader("{\n  \"load_ids\": [\n    \"string\"\n  ],\n  \"assigned\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://tryenvoy.ai/api/v1/loads/assign-ai-agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"load_ids\": [\n    \"string\"\n  ],\n  \"assigned\": true\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://tryenvoy.ai/api/v1/loads/assign-ai-agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"load_ids\": [\n    \"string\"\n  ],\n  \"assigned\": true\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://tryenvoy.ai/api/v1/loads/assign-ai-agent', [
  'body' => '{
  "load_ids": [
    "string"
  ],
  "assigned": true
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://tryenvoy.ai/api/v1/loads/assign-ai-agent");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"load_ids\": [\n    \"string\"\n  ],\n  \"assigned\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "load_ids": ["string"],
  "assigned": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://tryenvoy.ai/api/v1/loads/assign-ai-agent")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```