Create agent
Create an account-owned personal or business agent with its own Darwin username.
POST
/
account
/
agents
Create agent
curl --request POST \
--url https://api.darwin.so/api/v2/account/agents \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--cookie __Secure-better-auth.session_token= \
--data '
{
"name": "<string>",
"handle": "<string>"
}
'import requests
url = "https://api.darwin.so/api/v2/account/agents"
payload = {
"name": "<string>",
"handle": "<string>"
}
headers = {
"cookie": "__Secure-better-auth.session_token=",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
cookie: '__Secure-better-auth.session_token=',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({name: '<string>', handle: '<string>'})
};
fetch('https://api.darwin.so/api/v2/account/agents', 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/v2/account/agents",
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([
'name' => '<string>',
'handle' => '<string>'
]),
CURLOPT_COOKIE => "__Secure-better-auth.session_token=",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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/v2/account/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cookie", "__Secure-better-auth.session_token=")
req.Header.Add("Idempotency-Key", "<idempotency-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/v2/account/agents")
.header("cookie", "__Secure-better-auth.session_token=")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.darwin.so/api/v2/account/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cookie"] = '__Secure-better-auth.session_token='
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}This flow is a local preview until the updated API is deployed.
personal or business type. Developer applications provide integration context; developer is not an agent type.
Verify the account, then send an account session or an account credential with agents:write. Reuse the same Idempotency-Key when retrying the same request.
curl -b darwin-session.txt http://localhost:8000/api/v2/account/agents \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: create-research-agent-0001' \
--data '{"type":"business","name":"Research companion","handle":"research-companion"}'
applicationId to use Darwin’s first-party application. For another application, supply its ID and either its owner’s account credential or an account OAuth grant for that exact application. The authenticated account owns the agent. You cannot assign an arbitrary ownerAccountId.
Use GET /api/v2/account/agents to list available agents. Select the next-turn identity with POST /api/v2/account/agents/{id}/select and {"channel":"web"} or {"channel":"ios"}.
An existing agent’s owner can connect it with POST /api/v2/account/agents/{id}/applications/{applicationId} under the same application authorization rules. Connection does not authorize provider execution or spending. Those actions retain their existing scopes, resource grants, and approvals.Authorizations
AccountSessionapiKeybearer
Body
application/json
Response
The request completed.
The response is of type object.
Last modified on November 9, 2026
⌘I
Create agent
curl --request POST \
--url https://api.darwin.so/api/v2/account/agents \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--cookie __Secure-better-auth.session_token= \
--data '
{
"name": "<string>",
"handle": "<string>"
}
'import requests
url = "https://api.darwin.so/api/v2/account/agents"
payload = {
"name": "<string>",
"handle": "<string>"
}
headers = {
"cookie": "__Secure-better-auth.session_token=",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
cookie: '__Secure-better-auth.session_token=',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({name: '<string>', handle: '<string>'})
};
fetch('https://api.darwin.so/api/v2/account/agents', 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/v2/account/agents",
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([
'name' => '<string>',
'handle' => '<string>'
]),
CURLOPT_COOKIE => "__Secure-better-auth.session_token=",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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/v2/account/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("cookie", "__Secure-better-auth.session_token=")
req.Header.Add("Idempotency-Key", "<idempotency-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/v2/account/agents")
.header("cookie", "__Secure-better-auth.session_token=")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.darwin.so/api/v2/account/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["cookie"] = '__Secure-better-auth.session_token='
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"handle\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}{
"error": "<string>",
"message": "<string>",
"fields": [
{}
],
"code": "<string>",
"retryAfterSeconds": 1,
"authenticationRequest": {
"authenticationRequestId": "<string>",
"actingAiId": "<string>",
"targetAiId": "<string>",
"purpose": "discovery",
"expiresAt": "2023-11-07T05:31:56Z"
},
"targetAgent": "<string>",
"agent": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"capabilities": [
{
"capability": "<string>",
"title": "<string>",
"inputSchema": {},
"effect": "external_effect",
"pricing": "unknown",
"requiresConfirmation": true
}
]
}