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

# Send a message to a delegate task

POST https://api.runtype.com/v1/delegate-tasks/{id}/messages
Content-Type: application/json

Answer a question the task asked (status `input_required`) or add a follow-up instruction to a running task. Only the principal that started the task (the same user, and the same API key when one started it) may message it, because the task keeps acting with that principal's authority. API keys need `DELEGATE_TASKS:WRITE`.

Reference: https://docs.runtype.com/api-reference/runtype-api/delegate-tasks/send-a-message-to-a-delegate-task

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required) — The task id (`dlg_…`).

### Body (application/json)

This endpoint expects an object.

- `message` (string, required)

## Response

### 202

Accepted

- `accepted` (boolean, required)
- `task` (V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTask, required)

## Errors

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 403 Forbidden Error

Missing API key scope, or the caller is not the principal that started the task

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 404 Not Found Error

Feature disabled, or no such task in this organization

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 409 Conflict Error

The task has already settled

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

### 503 Service Unavailable Error

The operator agent is not available on this deployment

- `error` (string, required)
- `details` (list of ErrorDetailsItems, optional)

## Types

### V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTask

- `apiKeyId` (string, required, nullable)
- `clientName` (string, required, nullable)
- `clientVersion` (string, required, nullable)
- `completedAt` (string, required, nullable)
- `createdAt` (string, required)
- `error` (string, required, nullable)
- `id` (string, required)
- `instruction` (string, required)
- `lastEventSeq` (integer, required)
- `modelRoundCount` (integer, required)
- `organizationId` (string, required)
- `question` (string, required, nullable)
- `result` (V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResult, required, nullable)
- `startedAt` (string, required, nullable)
- `status` (enum, required)
  - Allowed values: `queued`, `running`, `input_required`, `completed`, `failed`, `cancelled`
- `summary` (string, required, nullable)
- `toolCallCount` (integer, required)
- `totalCost` (double, required, nullable)
- `touchedEntities` (list of V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskTouchedEntitiesItems, required)
- `updatedAt` (string, required)
- `userId` (string, required)
- `context` (any, optional)

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResult

- `links` (list of V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResultLinksItems, required)
- `modelRoundCount` (integer, required)
- `summary` (string, required)
- `toolCallCount` (integer, required)
- `touchedEntities` (list of V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResultTouchedEntitiesItems, required)
- `totalCost` (double, optional)
- `warnings` (list of string, optional)

### V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskTouchedEntitiesItems

- `action` (enum, required)
  - Allowed values: `created`, `updated`, `deleted`, `executed`, `read`
- `id` (string, required)
- `kind` (string, required)
- `name` (string, optional)

### V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResultLinksItems

- `label` (string, required)
- `url` (string, required)

### V1DelegateTasksIdMessagesPostResponsesContentApplicationJsonSchemaTaskResultTouchedEntitiesItems

- `action` (enum, required)
  - Allowed values: `created`, `updated`, `deleted`, `executed`, `read`
- `id` (string, required)
- `kind` (string, required)
- `name` (string, optional)

## Examples

**Request**

```json
{
  "message": "Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done."
}
```

**Response**

```json
{
  "accepted": true,
  "task": {
    "apiKeyId": "key_01jh1234567890abcdefghijkl",
    "clientName": "runtype-sdk-python",
    "clientVersion": "1.4.2",
    "completedAt": null,
    "createdAt": "2025-01-15T09:22:00Z",
    "error": null,
    "id": "dlg_01jh0000000000000000000000",
    "instruction": "Deploy the latest build to staging and notify the team when complete.",
    "lastEventSeq": 7,
    "modelRoundCount": 3,
    "organizationId": "org_01jh9876543210zyxwvutsrqpo",
    "question": null,
    "result": {
      "links": [
        {
          "label": "Staging Deployment Dashboard",
          "url": "https://dashboard.runtype.com/deployments/dep_01jh0000000000000000000001"
        }
      ],
      "modelRoundCount": 3,
      "summary": "Deployment to staging environment initiated successfully. Team notification sent via Slack to #deployments channel.",
      "toolCallCount": 5,
      "touchedEntities": [
        {
          "action": "created",
          "id": "dep_01jh0000000000000000000001",
          "kind": "Deployment",
          "name": "staging-deploy-v2.3.1"
        }
      ],
      "totalCost": 0.0042,
      "warnings": [
        "Staging environment was last deployed 14 days ago; consider reviewing environment variables."
      ]
    },
    "startedAt": "2025-01-15T09:22:05Z",
    "status": "running",
    "summary": "Deploying build v2.3.1 to staging environment and notifying team.",
    "toolCallCount": 5,
    "totalCost": 0.0042,
    "touchedEntities": [
      {
        "action": "created",
        "id": "dep_01jh0000000000000000000001",
        "kind": "Deployment",
        "name": "staging-deploy-v2.3.1"
      }
    ],
    "updatedAt": "2025-01-15T09:22:31Z",
    "userId": "usr_01jhaabbccddeeff00112233445"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages"

payload = { "message": "Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done." }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"message":"Yes, please proceed with deploying to the staging environment and notify the team via Slack once it\'s done."}'
};

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://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages"

	payload := strings.NewReader("{\n  \"message\": \"Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done.\"\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://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages")

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  \"message\": \"Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done.\"\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://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done.\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages', [
  'body' => '{
  "message": "Yes, please proceed with deploying to the staging environment and notify the team via Slack once it\'s done."
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"message\": \"Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done.\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["message": "Yes, please proceed with deploying to the staging environment and notify the team via Slack once it's done."] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/delegate-tasks/dlg_01jh0000000000000000000000/messages")! 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()
```