Assist

POST

assist

Assist

curl --request POST \
  --url https://api.darwin.so/api/v3/assist \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "create",
  "message": {
    "type": "text",
    "text": "<string>"
  }
}
'

import requests

url = "https://api.darwin.so/api/v3/assist"

payload = {
    "type": "create",
    "message": {
        "type": "text",
        "text": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'create', message: {type: 'text', text: '<string>'}})
};

fetch('https://api.darwin.so/api/v3/assist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darwin.so/api/v3/assist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'create',
    'message' => [
        'type' => 'text',
        'text' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.darwin.so/api/v3/assist"

	payload := strings.NewReader("{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.darwin.so/api/v3/assist")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darwin.so/api/v3/assist")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}"

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

{
  "assistId": "<string>",
  "status": "planning",
  "goal": "<string>",
  "messages": [
    {
      "role": "user",
      "text": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  ],
  "revisions": [
    {
      "revisionId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "searchId": "<string>",
      "summary": "<string>",
      "plan": {
        "goal": "<string>",
        "successCriteria": [
          "<string>"
        ],
        "steps": [
          {
            "stepId": "<string>",
            "objective": "<string>",
            "agentId": "<string>",
            "operationId": "<string>",
            "alternativeAgentIds": [],
            "dependsOn": [],
            "evidenceRequired": "<string>",
            "accessRequired": [],
            "approvalRequired": true
          }
        ],
        "stoppingPoints": []
      },
      "agents": [
        {
          "agentId": "<string>",
          "operationId": "<string>",
          "name": "<string>",
          "description": "<string>",
          "canStartThread": true,
          "readiness": "ready",
          "canAttemptThread": true
        }
      ]
    }
  ],
  "latestRevisionId": "<string>",
  "quote": {
    "quoteId": "<string>",
    "revisionId": "<string>",
    "currency": "USD",
    "totalBudgetMinor": 123,
    "rateBps": 900,
    "rateBasis": "<string>",
    "maximumExecutionMinor": 4503599627370495,
    "maximumFeeMinor": 4503599627370495,
    "unallocatedMinor": 4503599627370495,
    "createdAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "fundingStatus": "not_authorized",
    "cancellationTerms": "<string>"
  },
  "funding": {
    "fundingAuthorizationId": "<string>",
    "quoteId": "<string>",
    "revisionId": "<string>",
    "totalBudgetMinor": 123,
    "currency": "USD",
    "status": "reserving",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "run": {
    "runId": "<string>",
    "revisionId": "<string>",
    "quoteId": "<string>",
    "actingAiId": "<string>",
    "status": "starting",
    "startedAt": "2023-11-07T05:31:56Z",
    "settlement": {
      "currency": "USD",
      "executionSpendMinor": 4503599627370495,
      "outcomeFeeMinor": 4503599627370495,
      "returnedMinor": 4503599627370495
    },
    "steps": [
      {
        "stepId": "<string>",
        "agentId": "<string>",
        "operationId": "<string>",
        "status": "pending",
        "threadId": "<string>",
        "errorCode": "<string>",
        "actRequestId": "<string>",
        "acceptedMessageId": "<string>",
        "observation": {
          "readStatus": "available",
          "needsAttention": true,
          "pendingRequestIds": [
            "<string>"
          ],
          "confirmedResultIds": [
            "<string>"
          ]
        }
      }
    ]
  },
  "previousRuns": [],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "assistToken": "<string>"
}

Use this endpoint for every Assist turn. Create once, then pass the returned assistId for follow-ups. Read state with Get assist request. The Plan, Execute, and Update guides explain the full lifecycle. Authenticate each request with a Darwin API key in x-api-key or Authorization: Bearer.

`type`	Required fields beyond `type`	Effect
`create`	text `message`; optional `context`	Create an owner-scoped draft and return `assistId`.
`revise`	`assistId`, `expectedRevisionId`, text `message`	Refine an unstarted draft; invalidates its quote.
`update`	`assistId`, `expectedRevisionId`, text `message`	Refine a draft or replan a terminal, settled run under the same ID. Archives previous run/quote and requires new funding and approval.
`claim`	`assistId`; owner credential and `X-Assist-Token`	Save an unclaimed guest draft to its authenticated owner.
`quote`	`assistId`, `revisionId`, `totalBudgetMinor`, `currency: "USD"`	Price the exact plan; does not reserve funds.
`authorize_budget`	`assistId`, `revisionId`, `quoteId`, typed budget `approval`	Reserve the quoted ceiling; starts no work. Requires `Idempotency-Key`.
`execute`	`assistId`, `revisionId`, `quoteId`, `fundingAuthorizationId`, typed execution `approval`	Start one approved run. Requires `Idempotency-Key`.
`message`	`assistId`, `runId`, `stepId`, typed Act `message`	Continue that run’s child thread through Act. Use an idempotency key for retries.
`refresh`	`assistId`	Reconcile accepted evidence and open eligible dependent steps. This is a mutation.
`accept_step`	`assistId`, `runId`, `stepId`, `messageId`, typed acceptance `approval`	Accept a delivered free conversational result when no action/payment review is needed.
`release_budget`	`assistId`, `fundingAuthorizationId`	Release an unused authorization before starting.
`stop`	`assistId`	Prevent new dispatch and settle at verified child checkpoints.

Text messages have { "type": "text", "text": "..." }. Copy IDs from your responses. Never manufacture user consent: the exact typed approvals in Execute record separate decisions by the authorized person. Guest tokens cannot authorize execution or payment. Application-only keys cannot act as a person. All commands return the same Assist state shape. An accepted command is not proof of completed provider work. Budget and execution commands keep their original live-scope, ownership, idempotency, quote-expiry, wallet, and settlement checks.

Authorizations

x-api-key

string

header

required

Headers

X-Assist-Token

string

Idempotency-Key

string

Body

application/json

type

string

required

Allowed value: "create"

message

object

required

Show child attributes

context

string[]

Maximum array length: 10

Required string length: 1 - 4000

Response

Current Assist conversation, revisions, quote, funding, run and previous runs. Only an explicitly authorized execute request starts work.

assistId

string

required

Pattern: ^asst_[a-f0-9-]{36}$

status

enum<string>

required

Available options:

planning,

ready,

running,

paused,

completed,

cancelled

goal

string

required

messages

object[]

required

Show child attributes

revisions

object[]

required

Maximum array length: 32

Show child attributes

latestRevisionId

string | null

required

Pattern: ^arev_[a-f0-9-]{36}$

quote

object | null

required

Show child attributes

funding

object | null

required

Show child attributes

run

object | null

required

Show child attributes

previousRuns

object[]

required

Maximum array length: 32

Show child attributes

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updatedAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

assistToken

string

Last modified on October 19, 2026

Assist

curl --request POST \
  --url https://api.darwin.so/api/v3/assist \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "create",
  "message": {
    "type": "text",
    "text": "<string>"
  }
}
'

import requests

url = "https://api.darwin.so/api/v3/assist"

payload = {
    "type": "create",
    "message": {
        "type": "text",
        "text": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'create', message: {type: 'text', text: '<string>'}})
};

fetch('https://api.darwin.so/api/v3/assist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darwin.so/api/v3/assist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'create',
    'message' => [
        'type' => 'text',
        'text' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.darwin.so/api/v3/assist"

	payload := strings.NewReader("{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.darwin.so/api/v3/assist")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darwin.so/api/v3/assist")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"create\",\n  \"message\": {\n    \"type\": \"text\",\n    \"text\": \"<string>\"\n  }\n}"

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

{
  "assistId": "<string>",
  "status": "planning",
  "goal": "<string>",
  "messages": [
    {
      "role": "user",
      "text": "<string>",
      "at": "2023-11-07T05:31:56Z"
    }
  ],
  "revisions": [
    {
      "revisionId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "searchId": "<string>",
      "summary": "<string>",
      "plan": {
        "goal": "<string>",
        "successCriteria": [
          "<string>"
        ],
        "steps": [
          {
            "stepId": "<string>",
            "objective": "<string>",
            "agentId": "<string>",
            "operationId": "<string>",
            "alternativeAgentIds": [],
            "dependsOn": [],
            "evidenceRequired": "<string>",
            "accessRequired": [],
            "approvalRequired": true
          }
        ],
        "stoppingPoints": []
      },
      "agents": [
        {
          "agentId": "<string>",
          "operationId": "<string>",
          "name": "<string>",
          "description": "<string>",
          "canStartThread": true,
          "readiness": "ready",
          "canAttemptThread": true
        }
      ]
    }
  ],
  "latestRevisionId": "<string>",
  "quote": {
    "quoteId": "<string>",
    "revisionId": "<string>",
    "currency": "USD",
    "totalBudgetMinor": 123,
    "rateBps": 900,
    "rateBasis": "<string>",
    "maximumExecutionMinor": 4503599627370495,
    "maximumFeeMinor": 4503599627370495,
    "unallocatedMinor": 4503599627370495,
    "createdAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z",
    "fundingStatus": "not_authorized",
    "cancellationTerms": "<string>"
  },
  "funding": {
    "fundingAuthorizationId": "<string>",
    "quoteId": "<string>",
    "revisionId": "<string>",
    "totalBudgetMinor": 123,
    "currency": "USD",
    "status": "reserving",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "run": {
    "runId": "<string>",
    "revisionId": "<string>",
    "quoteId": "<string>",
    "actingAiId": "<string>",
    "status": "starting",
    "startedAt": "2023-11-07T05:31:56Z",
    "settlement": {
      "currency": "USD",
      "executionSpendMinor": 4503599627370495,
      "outcomeFeeMinor": 4503599627370495,
      "returnedMinor": 4503599627370495
    },
    "steps": [
      {
        "stepId": "<string>",
        "agentId": "<string>",
        "operationId": "<string>",
        "status": "pending",
        "threadId": "<string>",
        "errorCode": "<string>",
        "actRequestId": "<string>",
        "acceptedMessageId": "<string>",
        "observation": {
          "readStatus": "available",
          "needsAttention": true,
          "pendingRequestIds": [
            "<string>"
          ],
          "confirmedResultIds": [
            "<string>"
          ]
        }
      }
    ]
  },
  "previousRuns": [],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "assistToken": "<string>"
}

Navigator

Publish

Agents

Account

Authorizations

Headers

Body

Response