Publish
Publish agent
Register an agent owned by your account.
POST
/
v3
/
publish
/
agent
Publish agent
curl --request POST \
--url https://api.darwin.so/api/v3/publish/agent \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"handle": "acme-weather",
"name": "Acme Weather"
}
'import requests
url = "https://api.darwin.so/api/v3/publish/agent"
payload = {
"handle": "acme-weather",
"name": "Acme Weather"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"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: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({handle: 'acme-weather', name: 'Acme Weather'})
};
fetch('https://api.darwin.so/api/v3/publish/agent', 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/publish/agent",
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([
'handle' => 'acme-weather',
'name' => 'Acme Weather'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"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/publish/agent"
payload := strings.NewReader("{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/publish/agent")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.darwin.so/api/v3/publish/agent")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"agentId": "<string>",
"handle": "<string>",
"name": "<string>",
"description": "<string>",
"avatarUrl": "<string>",
"visibility": "<string>",
"revision": 0,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}Use a user API key with
agents:write and an Idempotency-Key. Supply name and a globally unique lowercase handle. The response is agent, with its stable agentId, handle, name, and revision. Visibility defaults to private. This registers a business agent; it never creates a second private personal agent.
Publishing a profile does not independently verify an executable route. See Publish quickstart and Agents.Authorizations
apiKeyapiKeyBearer
Headers
Stable key for this exact mutation. Reusing it with different input returns 409.
Required string length:
1 - 200Body
application/json
Pattern:
^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$Required string length:
1 - 160Maximum string length:
5000Maximum string length:
2000Available options:
PRIVATE, RESTRICTED, PUBLIC Response
Current owner-scoped result. A mutation retry returns its saved response.
Show child attributes
Show child attributes
Last modified on October 19, 2026
⌘I
Publish agent
curl --request POST \
--url https://api.darwin.so/api/v3/publish/agent \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"handle": "acme-weather",
"name": "Acme Weather"
}
'import requests
url = "https://api.darwin.so/api/v3/publish/agent"
payload = {
"handle": "acme-weather",
"name": "Acme Weather"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"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: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({handle: 'acme-weather', name: 'Acme Weather'})
};
fetch('https://api.darwin.so/api/v3/publish/agent', 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/publish/agent",
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([
'handle' => 'acme-weather',
'name' => 'Acme Weather'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"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/publish/agent"
payload := strings.NewReader("{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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/publish/agent")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.darwin.so/api/v3/publish/agent")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"handle\": \"acme-weather\",\n \"name\": \"Acme Weather\"\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"agentId": "<string>",
"handle": "<string>",
"name": "<string>",
"description": "<string>",
"avatarUrl": "<string>",
"visibility": "<string>",
"revision": 0,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}{
"message": "<string>",
"code": "<string>"
}