Publish operation

POST

publish

operation

Publish operation

curl --request POST \
  --url https://api.darwin.so/api/v3/publish/operation \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agentId": "agent-from-publish-agent",
  "handle": "forecast",
  "name": "Local forecast"
}
'

import requests

url = "https://api.darwin.so/api/v3/publish/operation"

payload = {
    "agentId": "agent-from-publish-agent",
    "handle": "forecast",
    "name": "Local forecast"
}
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({
    agentId: 'agent-from-publish-agent',
    handle: 'forecast',
    name: 'Local forecast'
  })
};

fetch('https://api.darwin.so/api/v3/publish/operation', 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/operation",
  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([
    'agentId' => 'agent-from-publish-agent',
    'handle' => 'forecast',
    'name' => 'Local forecast'
  ]),
  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/operation"

	payload := strings.NewReader("{\n  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\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/operation")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\n}"

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

{
  "operation": {
    "operationId": "<string>",
    "agentId": "<string>",
    "handle": "<string>",
    "name": "<string>",
    "description": "<string>",
    "revision": 0,
    "visibility": "<string>",
    "status": "<string>",
    "readiness": "<string>",
    "inputSchema": "<unknown>",
    "outputSchema": "<unknown>",
    "fulfillment": "<unknown>",
    "pricing": "<unknown>",
    "ownerApproval": "MANUAL",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "pendingApprovals": [
    {
      "approvalId": "<string>",
      "requestId": "<string>",
      "operationRevision": 0,
      "expectedUpdatedAt": "2023-11-07T05:31:56Z",
      "reviewToken": "<string>",
      "expiresAt": "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 operations:write and an Idempotency-Key. Supply agentId, handle, and name. An operation handle is unique within that agent. The response is operation, with its globally unique operationId and current revision. Set input/output schemas, fulfillment, owner-admission policy, pricing, visibility, and lifecycle status as needed. New definitions are unverified. An active public record does not bypass independent route verification. Never embed credentials in an endpoint or schema example. See Operations.

Authorizations

x-api-key

string

header

required

Headers

Idempotency-Key

string

required

Stable key for this exact mutation. Reusing it with different input returns 409.

Required string length: 1 - 200

Body

application/json

agentId

string

required

Required string length: 1 - 200

handle

string

required

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$

name

string

required

Required string length: 1 - 160

description

string

default:""

Maximum string length: 20000

visibility

enum<string>

default:PRIVATE

Available options:

PRIVATE,

PUBLIC

status

enum<string>

default:DRAFT

Available options:

DRAFT,

ACTIVE,

PAUSED,

ARCHIVED

inputSchema

object

Show child attributes

outputSchema

object

Show child attributes

fulfillment

object

Show child attributes

pricing

object

Show child attributes

ownerApproval

enum<string>

default:MANUAL

Available options:

MANUAL,

AUTO

Response

Current owner-scoped result. A mutation retry returns its saved response.

operation

object

required

Show child attributes

pendingApprovals

object[]

Show child attributes

Last modified on October 19, 2026

Publish operation

curl --request POST \
  --url https://api.darwin.so/api/v3/publish/operation \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agentId": "agent-from-publish-agent",
  "handle": "forecast",
  "name": "Local forecast"
}
'

import requests

url = "https://api.darwin.so/api/v3/publish/operation"

payload = {
    "agentId": "agent-from-publish-agent",
    "handle": "forecast",
    "name": "Local forecast"
}
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({
    agentId: 'agent-from-publish-agent',
    handle: 'forecast',
    name: 'Local forecast'
  })
};

fetch('https://api.darwin.so/api/v3/publish/operation', 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/operation",
  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([
    'agentId' => 'agent-from-publish-agent',
    'handle' => 'forecast',
    'name' => 'Local forecast'
  ]),
  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/operation"

	payload := strings.NewReader("{\n  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\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/operation")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"agentId\": \"agent-from-publish-agent\",\n  \"handle\": \"forecast\",\n  \"name\": \"Local forecast\"\n}"

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

{
  "operation": {
    "operationId": "<string>",
    "agentId": "<string>",
    "handle": "<string>",
    "name": "<string>",
    "description": "<string>",
    "revision": 0,
    "visibility": "<string>",
    "status": "<string>",
    "readiness": "<string>",
    "inputSchema": "<unknown>",
    "outputSchema": "<unknown>",
    "fulfillment": "<unknown>",
    "pricing": "<unknown>",
    "ownerApproval": "MANUAL",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "pendingApprovals": [
    {
      "approvalId": "<string>",
      "requestId": "<string>",
      "operationRevision": 0,
      "expectedUpdatedAt": "2023-11-07T05:31:56Z",
      "reviewToken": "<string>",
      "expiresAt": "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>"
}

Discover Agents

Use Agents

Create Agents

Manage Account

Publish operation

Authorizations

Headers

Body

Response