Create an objective

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const objective = await client.objectives.create({
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  agentId: 'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
  systemPromptData: { foo: 'bar' },
});

console.log(objective.configSnapshot);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
objective = client.objectives.create(
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
    system_prompt_data={
        "foo": "bar"
    },
)
print(objective.config_snapshot)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	objective, err := client.Objectives.New(context.TODO(), cadenya.ObjectiveNewParams{
		WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		AgentID:     "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		SystemPromptData: map[string]any{
			"foo": "bar",
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objective.ConfigSnapshot)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective = cadenya.objectives.create(
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  agent_id: "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  system_prompt_data: {foo: "bar"}
)

puts(objective)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "systemPromptData": {},
  "variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  "metadata": {
    "labels": {},
    "externalId": "<string>"
  },
  "firstUserMessage": "<string>",
  "secrets": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "memoryCascade": [
    {
      "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
      "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
    }
  ],
  "firstUserMessageData": {},
  "pinnedParameters": {}
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives",
  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_01HXKD2E5NQM3T9AYWCFMGWT9Y',
    'systemPromptData' => [
        
    ],
    'variationId' => 'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
    'metadata' => [
        'labels' => [
                
        ],
        'externalId' => '<string>'
    ],
    'firstUserMessage' => '<string>',
    'secrets' => [
        [
                'name' => '<string>',
                'value' => '<string>'
        ]
    ],
    'memoryCascade' => [
        [
                'memoryLayerId' => 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
                'memoryEntryId' => 'mementry_01HXKD2E5NQM3T9AYWCF5E52Z0'
        ]
    ],
    'firstUserMessageData' => [
        
    ],
    'pinnedParameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y\",\n  \"systemPromptData\": {},\n  \"variationId\": \"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP\",\n  \"metadata\": {\n    \"labels\": {},\n    \"externalId\": \"<string>\"\n  },\n  \"firstUserMessage\": \"<string>\",\n  \"secrets\": [\n    {\n      \"name\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"memoryCascade\": [\n    {\n      \"memoryLayerId\": \"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n      \"memoryEntryId\": \"mementry_01HXKD2E5NQM3T9AYWCF5E52Z0\"\n    }\n  ],\n  \"firstUserMessageData\": {},\n  \"pinnedParameters\": {}\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "configSnapshot": {
    "agent": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "description": "<string>",
        "webhookEventsUrl": "<string>",
        "systemPromptDataSchema": {},
        "outputDefinition": {},
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 123
      },
      "info": {
        "variationCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    },
    "agentVariation": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "systemPromptTemplate": "<string>",
        "progressiveDiscovery": {
          "maxTools": 123,
          "hints": [
            "<string>"
          ]
        },
        "constraints": {
          "maxToolCalls": 123,
          "maxSubObjectives": 123,
          "inactivityTimeout": "<string>"
        },
        "description": "<string>",
        "modelConfig": {
          "modelId": "claude/opus-4.6",
          "temperature": 123
        },
        "compactionConfig": {
          "triggerThreshold": 123,
          "summarization": {
            "instructions": "<string>"
          },
          "toolResultClearing": {
            "preserveRecentResults": 123
          }
        },
        "firstUserMessageTemplate": "<string>"
      },
      "info": {
        "toolCount": 123,
        "toolSetCount": 123,
        "subAgentCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        },
        "model": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "name": "<string>",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "createdAt": "2023-11-07T05:31:56Z",
          "externalId": "<string>",
          "labels": {},
          "updatedAt": "2023-11-07T05:31:56Z"
        },
        "score": 123,
        "feedbackCount": 123,
        "assignments": [
          {
            "type": "tool",
            "tool": {
              "id": "<string>",
              "name": "<string>"
            },
            "id": "avt_01HXKD2E5NQM3T9AYWCFJE6K89"
          }
        ],
        "memoryLayerAssignments": [
          {
            "id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
            "memoryLayer": {
              "id": "<string>",
              "name": "<string>"
            },
            "position": 123
          }
        ],
        "memoryLayerCount": 123
      }
    },
    "agentSchedule": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "schedule": {
          "calendars": [
            {
              "second": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "minute": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "hour": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "dayOfMonth": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "month": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "dayOfWeek": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "comment": "<string>"
            }
          ],
          "intervals": [
            {
              "every": "<string>",
              "offset": "<string>"
            }
          ],
          "timezone": "<string>"
        },
        "firstUserMessage": "<string>",
        "variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
        "systemPromptData": {},
        "firstUserMessageData": {}
      },
      "info": {
        "nextFireAt": "2023-11-07T05:31:56Z",
        "lastFireAt": "2023-11-07T05:31:56Z",
        "lastObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
        "lastSkippedAt": "2023-11-07T05:31:56Z",
        "lastSkipReason": "<string>",
        "totalFires": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    }
  },
  "systemPrompt": "<string>",
  "firstUserMessage": "<string>",
  "stateMessage": "<string>",
  "info": {
    "totalEvents": 123,
    "totalToolCalls": 123,
    "totalInputTokens": 123,
    "totalOutputTokens": 123,
    "totalContextWindows": 123,
    "totalIterations": 123,
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    },
    "effectiveMemoryCascade": [
      {
        "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
        "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
      }
    ],
    "agent": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "name": "<string>",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "createdAt": "2023-11-07T05:31:56Z",
      "externalId": "<string>",
      "labels": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "agentVariation": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "name": "<string>",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "createdAt": "2023-11-07T05:31:56Z",
      "externalId": "<string>",
      "labels": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "currentContextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
    "tenant": {
      "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
      "externalId": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
      "externalId": "customer-user-42",
      "name": "Jane Doe"
    },
    "widget": {
      "id": "<string>",
      "name": "<string>"
    }
  },
  "parentObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "systemPromptData": {},
  "memoryCascade": [
    {
      "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
      "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
    }
  ],
  "output": {},
  "firstUserMessageData": {},
  "episodicMemory": {
    "key": "<string>",
    "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"
  },
  "pinnedParameters": {}
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

workspaces

{workspaceId}

objectives

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const objective = await client.objectives.create({
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  agentId: 'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
  systemPromptData: { foo: 'bar' },
});

console.log(objective.configSnapshot);

import os
from cadenya import Cadenya

client = Cadenya(
    api_key=os.environ.get("CADENYA_API_KEY"),  # This is the default and can be omitted
)
objective = client.objectives.create(
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
    system_prompt_data={
        "foo": "bar"
    },
)
print(objective.config_snapshot)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	objective, err := client.Objectives.New(context.TODO(), cadenya.ObjectiveNewParams{
		WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		AgentID:     "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		SystemPromptData: map[string]any{
			"foo": "bar",
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objective.ConfigSnapshot)
}

require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

objective = cadenya.objectives.create(
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  agent_id: "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  system_prompt_data: {foo: "bar"}
)

puts(objective)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "systemPromptData": {},
  "variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  "metadata": {
    "labels": {},
    "externalId": "<string>"
  },
  "firstUserMessage": "<string>",
  "secrets": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "memoryCascade": [
    {
      "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
      "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
    }
  ],
  "firstUserMessageData": {},
  "pinnedParameters": {}
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives",
  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_01HXKD2E5NQM3T9AYWCFMGWT9Y',
    'systemPromptData' => [
        
    ],
    'variationId' => 'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
    'metadata' => [
        'labels' => [
                
        ],
        'externalId' => '<string>'
    ],
    'firstUserMessage' => '<string>',
    'secrets' => [
        [
                'name' => '<string>',
                'value' => '<string>'
        ]
    ],
    'memoryCascade' => [
        [
                'memoryLayerId' => 'memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH',
                'memoryEntryId' => 'mementry_01HXKD2E5NQM3T9AYWCF5E52Z0'
        ]
    ],
    'firstUserMessageData' => [
        
    ],
    'pinnedParameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentId\": \"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y\",\n  \"systemPromptData\": {},\n  \"variationId\": \"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP\",\n  \"metadata\": {\n    \"labels\": {},\n    \"externalId\": \"<string>\"\n  },\n  \"firstUserMessage\": \"<string>\",\n  \"secrets\": [\n    {\n      \"name\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"memoryCascade\": [\n    {\n      \"memoryLayerId\": \"memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH\",\n      \"memoryEntryId\": \"mementry_01HXKD2E5NQM3T9AYWCF5E52Z0\"\n    }\n  ],\n  \"firstUserMessageData\": {},\n  \"pinnedParameters\": {}\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "configSnapshot": {
    "agent": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "description": "<string>",
        "webhookEventsUrl": "<string>",
        "systemPromptDataSchema": {},
        "outputDefinition": {},
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 123
      },
      "info": {
        "variationCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    },
    "agentVariation": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "systemPromptTemplate": "<string>",
        "progressiveDiscovery": {
          "maxTools": 123,
          "hints": [
            "<string>"
          ]
        },
        "constraints": {
          "maxToolCalls": 123,
          "maxSubObjectives": 123,
          "inactivityTimeout": "<string>"
        },
        "description": "<string>",
        "modelConfig": {
          "modelId": "claude/opus-4.6",
          "temperature": 123
        },
        "compactionConfig": {
          "triggerThreshold": 123,
          "summarization": {
            "instructions": "<string>"
          },
          "toolResultClearing": {
            "preserveRecentResults": 123
          }
        },
        "firstUserMessageTemplate": "<string>"
      },
      "info": {
        "toolCount": 123,
        "toolSetCount": 123,
        "subAgentCount": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        },
        "model": {
          "id": "<string>",
          "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
          "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
          "name": "<string>",
          "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
          "createdAt": "2023-11-07T05:31:56Z",
          "externalId": "<string>",
          "labels": {},
          "updatedAt": "2023-11-07T05:31:56Z"
        },
        "score": 123,
        "feedbackCount": 123,
        "assignments": [
          {
            "type": "tool",
            "tool": {
              "id": "<string>",
              "name": "<string>"
            },
            "id": "avt_01HXKD2E5NQM3T9AYWCFJE6K89"
          }
        ],
        "memoryLayerAssignments": [
          {
            "id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
            "memoryLayer": {
              "id": "<string>",
              "name": "<string>"
            },
            "position": 123
          }
        ],
        "memoryLayerCount": 123
      }
    },
    "agentSchedule": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "createdAt": "2023-11-07T05:31:56Z",
        "externalId": "<string>",
        "labels": {},
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "schedule": {
          "calendars": [
            {
              "second": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "minute": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "hour": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "dayOfMonth": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "month": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "dayOfWeek": [
                {
                  "start": 123,
                  "end": 123,
                  "step": 123
                }
              ],
              "comment": "<string>"
            }
          ],
          "intervals": [
            {
              "every": "<string>",
              "offset": "<string>"
            }
          ],
          "timezone": "<string>"
        },
        "firstUserMessage": "<string>",
        "variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
        "systemPromptData": {},
        "firstUserMessageData": {}
      },
      "info": {
        "nextFireAt": "2023-11-07T05:31:56Z",
        "lastFireAt": "2023-11-07T05:31:56Z",
        "lastObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
        "lastSkippedAt": "2023-11-07T05:31:56Z",
        "lastSkipReason": "<string>",
        "totalFires": 123,
        "createdBy": {
          "metadata": {
            "id": "<string>",
            "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
            "name": "<string>",
            "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
            "externalId": "<string>",
            "labels": {},
            "createdAt": "2023-11-07T05:31:56Z"
          },
          "spec": {
            "email": "<string>",
            "name": "<string>"
          }
        }
      }
    }
  },
  "systemPrompt": "<string>",
  "firstUserMessage": "<string>",
  "stateMessage": "<string>",
  "info": {
    "totalEvents": 123,
    "totalToolCalls": 123,
    "totalInputTokens": 123,
    "totalOutputTokens": 123,
    "totalContextWindows": 123,
    "totalIterations": 123,
    "createdBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    },
    "effectiveMemoryCascade": [
      {
        "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
        "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
      }
    ],
    "agent": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "name": "<string>",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "createdAt": "2023-11-07T05:31:56Z",
      "externalId": "<string>",
      "labels": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "agentVariation": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "name": "<string>",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "createdAt": "2023-11-07T05:31:56Z",
      "externalId": "<string>",
      "labels": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "currentContextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
    "tenant": {
      "id": "tenant_01HXKD2E5NQM3T9AYWCF133E3Q",
      "externalId": "acme-corp",
      "name": "Acme Corp"
    },
    "subject": {
      "id": "subj_01HXKD2E5NQM3T9AYWCFQAZGFV",
      "externalId": "customer-user-42",
      "name": "Jane Doe"
    },
    "widget": {
      "id": "<string>",
      "name": "<string>"
    }
  },
  "parentObjectiveId": "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "secrets": [
    {
      "name": "<string>"
    }
  ],
  "systemPromptData": {},
  "memoryCascade": [
    {
      "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
      "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
    }
  ],
  "output": {},
  "firstUserMessageData": {},
  "episodicMemory": {
    "key": "<string>",
    "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"
  },
  "pinnedParameters": {}
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

This is the endpoint that puts an agent to work. You name an agent, pass the data its prompt templates need, and Cadenya picks a variation, snapshots the configuration, and starts running. The call returns as soon as the objective is created, in STATE_PENDING. Work happens in the background. Read the result by polling the objective, streaming its events, or receiving webhooks.

The shortest call that works

Two fields are required: agentId and systemPromptData. Pass {} for the data when the agent’s prompt has no template slots.

const objective = await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: {},
  firstUserMessage: 'A customer cannot log in. What should I check first?',
});

console.log(objective.metadata.id); // obj_01KX18K1TQRC2CKS6880FH2GCR
console.log(objective.state);       // STATE_PENDING

objective, err := client.Objectives.New(ctx, cadenya.ObjectiveNewParams{
	WorkspaceID:      cadenya.String(workspaceID),
	AgentID:          "external_id:support",
	SystemPromptData: map[string]any{},
	FirstUserMessage: cadenya.String("A customer cannot log in. What should I check first?"),
})
if err != nil {
	log.Fatal(err)
}
log.Println(objective.Metadata.ID, objective.State)

objective = cadenya.objectives.create(
  workspace_id: workspace_id,
  agent_id: "external_id:support",
  system_prompt_data: {},
  first_user_message: "A customer cannot log in. What should I check first?"
)

puts objective.metadata.id
puts objective.state

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
        "agentId": "external_id:support",
        "systemPromptData": {},
        "firstUserMessage": "A customer cannot log in. What should I check first?"
      }'

In bash and zsh, brace the variable before a custom method: write "${OBJECTIVE_ID}:cancel", not "$OBJECTIVE_ID:cancel". The shell reads :c as a modifier and eats it, and the request lands on a path that does not exist.

Where the two messages come from

An objective opens with a system prompt and a first user message. Both render from Liquid templates on the selected variation, and both take their data from this request.

Request field	Renders	Rule
`systemPromptData`	The variation’s `systemPromptTemplate`	Required. Validated against the agent’s `systemPromptDataSchema` when it has one.
`firstUserMessageData`	The variation’s `firstUserMessageTemplate`	Used when `firstUserMessage` is absent.
`firstUserMessage`	Nothing. Used verbatim.	Overrides the template.

Pass neither firstUserMessage nor a variation with a firstUserMessageTemplate and the request fails with InvalidArgument. The rendered results come back on the response as the read-only systemPrompt and firstUserMessage fields.

// The variation's templates carry the shape. The objective carries the facts.
await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: { company: 'Acme', tier: 'enterprise' },
  firstUserMessageData: { ticket_id: '4521', summary: 'Cannot log in.' },
});

Pick the variation, or let the agent pick

Omit variationId and the agent’s variationSelectionMode chooses: equal odds under VARIATION_SELECTION_MODE_RANDOM, feedback-weighted odds under VARIATION_SELECTION_MODE_WEIGHTED. Name a variationId and it overrides the mode, which is how you smoke-test a new variation before giving it weight.

await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  variationId: 'external_id:concise', // canonical agentvar_... works too
  systemPromptData: {},
  firstUserMessage: 'Pin this run to the Concise variation.',
});

Whichever variation wins, the response’s configSnapshot freezes the agent and variation as they were at create time. Edit the variation tomorrow and this objective’s record still shows what ran.

Per-run secrets

secrets scope to this one objective and shadow tool set and workspace secrets on a name clash. Resolution runs objective, then tool set, then workspace. That precedence suits short-lived, per-user tokens: the workspace holds the service credential, the objective carries the caller’s.

await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: {},
  firstUserMessage: 'Fetch this user\'s recent orders.',
  secrets: [{ name: 'USER_TOKEN', value: userToken }],
});

Reference the name in an adapter header as ${USER_TOKEN} and Cadenya swaps in the value at call time. Secrets never come back on a read: the response lists their names and nothing else. To see which source won for a given key, read resolvedSecrets on a tool call.

Memory

Two independent controls, both optional. memoryCascade layers memory over the baseline the variation already carries. Array order is resolution order, and earlier elements win. Pin a single entry by passing memoryEntryId alongside its memoryLayerId. The total effective cascade, this field plus the variation’s assignments, caps at 10 entries. episodicMemory.key groups objectives that should share what the agent writes about itself. Objectives created with the same key, for the same agent, read and write one system-managed layer that sits at the most specific end of the cascade. The agent must have enableEpisodicMemory set.

await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: {},
  firstUserMessage: 'Pick up where we left off.',
  episodicMemory: { key: `customer-${customerId}` },
  memoryCascade: [{ memoryLayerId: 'external_id:enterprise-playbook' }],
});

See Memory cascade for how the layers resolve.

What comes back, and what happens next

The response is the objective: metadata.id (an obj_ prefixed ULID), the rendered systemPrompt and firstUserMessage, the configSnapshot, and a state that starts at STATE_PENDING. An objective walks through eight states:

State	Meaning
`STATE_PENDING`	Created, not yet picked up.
`STATE_RUNNING`	The agent is working: calling tools, reading memory, looping.
`STATE_WAITING`	The agent answered and awaits another turn. Continue it to send one.
`STATE_FINALIZED`	Done. `output` is populated when the agent has an output definition.
`STATE_FAILED`	Stopped on an error. Read `stateMessage` for the reason.
`STATE_CANCELLED`	Cancelled by a caller while it was running.
`STATE_TIMED_OUT`	Hit the variation’s inactivity timeout.
`STATE_UNSPECIFIED`	Never returned in practice.

The agent’s outputDefinition decides whether an objective ever finalizes. With one, Cadenya extracts a result against that schema when the agent stops working, and the objective reaches STATE_FINALIZED with output populated. Without one, the objective parks in STATE_WAITING instead: it has answered, and it is holding the context window open for your next message. It never finalizes on its own. So if you are polling for a terminal state against an agent that has no outputDefinition, you are waiting for something that never happens. Either declare the schema, or treat STATE_WAITING as done. Cancelling interrupts work in flight. The call returns the objective in whatever state it was in, then the state settles to STATE_CANCELLED a moment later, so read it back rather than trusting the response. Cancelling a STATE_WAITING objective does nothing: there is no work to stop, and it stays waiting. To watch the work as it happens, stream the events rather than polling:

const objective = await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: {},
  firstUserMessage: 'A customer cannot log in. What should I check first?',
});

const stream = await client.objectives.streamEvents(objective.metadata.id, { workspaceId });
for await (const event of stream) {
  console.log(event.data?.type);
  // assistantMessage
  // toolCalled
  // toolResult
}

A tool that needs approval parks the objective and emits a toolApprovalRequested event. Nothing moves until you approve or deny the call.

Bring your own ID

Set metadata.externalId here and you never have to store the obj_ ID. Every later call takes external_id:your-value in its place.

await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: {},
  firstUserMessage: 'Handle ticket 4521.',
  metadata: { externalId: 'ticket-4521', labels: { team: 'support' } },
});

// Later, from anywhere, with no ID bookkeeping:
const objective = await client.objectives.retrieve('external_id:ticket-4521', { workspaceId });

Labels come along for the ride: filter the objectives list by them to group runs however your system thinks about them.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json

agentId

string

required

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

systemPromptData

object

required

Arbitrary data rendered into the selected variation's system_prompt_template (liquid) to produce the objective's system prompt. If the agent has a system_prompt_data_schema, this must satisfy it.

variationId

string

Optional explicit variation selection. Overrides the agent's variation_selection_mode.

Example:

"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"

metadata

object

CreateOperationMetadata contains the user-provided fields for creating an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id) are excluded since they are set by the server.

Show child attributes

firstUserMessage

string

Optional explicit first user message for the LLM chat history. When not set, the selected variation's first_user_message_template is rendered with first_user_message_data instead. If neither this field nor a first_user_message_template is present, the request is rejected with InvalidArgument.

secrets

object[]

Secrets that can be used in the headers for tool calls using the secret interpolation format.

Show child attributes

memoryCascade

object[]

Memory layers/entries layered over the baseline cascade inherited from the selected variation — element-level rules over inherited styles, in CSS terms.

Array order is resolution order: EARLIER elements are more specific and are consulted first. Entries pinned via memory_entry_id behave as single-entry layers at their position.

System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on the episodic key.

Size cap: the TOTAL effective cascade (this field + the variation's memory layer assignments) must not exceed 10 entries. A request that would produce a larger cascade is rejected with InvalidArgument.

Show child attributes

firstUserMessageData

object

Arbitrary data rendered into the selected variation's first_user_message_template (liquid) to produce the first user message. Separate from system_prompt_data, which renders the system prompt template.

episodicMemory

object

If the agent variation that is selected has episodic memory enabled, then this key is used to create/update a memory layer specific to the episodic memory. The layer may have a TTL configured by the variation.

Show child attributes

tenant

object

Optional tenant assertion — the customer's org/company identifier for the end user this objective serves. Upserts the tenant record in the workspace and associates the objective with it.

Show child attributes

subject

object

Optional subject assertion — the person within the tenant this objective serves. Requires tenant; a subject asserted without a tenant is rejected with InvalidArgument.

Show child attributes

pinnedParameters

object

Parameters forced onto this objective's tool calls. A pinned parameter is an overlay on a tool's JSON schema: the parameter is removed from what the LLM sees, and its value is always overwritten server-side with the pinned value — the model cannot choose a different value for it.

Show child attributes

Response

Objective is the data for an objective. It contains the snapshotted fields for the selected agent and variation. Secrets are returned only with their names, and the output definition is copied from the agent's configuration.

metadata

object

required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

Show child attributes

configSnapshot

object

required

The snapshot of the agent and the variation selected (either explicitly or by sampling) will be set here. Cadenya stores the point-in-time snapshot of the configuration used to start an objective and maintains it throughout the entire lifecycle so that changes to agents and variations in the middle of a cycle don't impact the objective itself

Show child attributes

state

enum<string>

required

read-only

The current lifecycle state of the objective.

Available options:

STATE_UNSPECIFIED,

STATE_PENDING,

STATE_RUNNING,

STATE_WAITING,

STATE_FAILED,

STATE_CANCELLED,

STATE_FINALIZED,

STATE_TIMED_OUT

systemPrompt

string

required

read-only

system_prompt is read-only, derived from the selected variation's prompt

firstUserMessage

string

required

The first user message in the LLM chat history, either provided explicitly at creation or rendered from the variation's first_user_message_template.

stateMessage

string

read-only

Optional human-readable detail about the current state (e.g. a failure reason).

info

object

Read-only aggregated info about this objective's execution

Show child attributes

parentObjectiveId

string

read-only

A parent objective means the objective was spawned off using a separate agent to complete an objective

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

secrets

object[]

Secrets that can be used in the headers for tool calls using the secret interpolation format.

Show child attributes

systemPromptData

object

read-only

Arbitrary data rendered into the variation's system_prompt_template

memoryCascade

object[]

Memory layers/entries layered over the baseline cascade inherited from the selected variation — element-level rules over inherited styles, in CSS terms.

Array order is resolution order: EARLIER elements are more specific and are consulted first. Entries pinned via memory_entry_id behave as single-entry layers at their position.

System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on the episodic key.

Show child attributes

output

object

read-only

The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred. This will only be set if the state of the objective is set to STATE_FINALIZED

firstUserMessageData

object

read-only

Arbitrary data rendered into the variation's first_user_message_template

episodicMemory

object

Show child attributes

pinnedParameters

object

read-only

Parameters forced onto this objective's tool calls, as provided at creation. See CreateObjectiveRequest.pinned_parameters for semantics.

Show child attributes

​The shortest call that works

​Where the two messages come from

​Pick the variation, or let the agent pick

​Per-run secrets

​Memory

​What comes back, and what happens next

​Bring your own ID

Authorizations

Path Parameters

Body

Response

The shortest call that works

Where the two messages come from

Pick the variation, or let the agent pick

Per-run secrets

Memory

What comes back, and what happens next

Bring your own ID