Continue 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 objectiveEvent = await client.objectives.continue('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  message: 'message',
});

console.log(objectiveEvent.data);

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_event = client.objectives.continue_(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    message="message",
)
print(objective_event.data)

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"),
	)
	objectiveEvent, err := client.Objectives.Continue(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveContinueParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Message:     "message",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveEvent.Data)
}

require "cadenya"

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

objective_event = cadenya.objectives.continue(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  message: "message"
)

puts(objective_event)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}:continue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "enqueue": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}:continue",
  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([
    'message' => '<string>',
    'enqueue' => true
  ]),
  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/{objectiveId}:continue")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"<string>\",\n  \"enqueue\": true\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "type": "userMessage",
    "userMessage": {
      "content": "<string>"
    }
  },
  "contextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
  "info": {
    "objective": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "createdAt": "2023-11-07T05:31:56Z",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "labels": {},
      "externalId": "<string>"
    },
    "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>"
      }
    }
  },
  "duration": "<string>",
  "startedAt": "2023-11-07T05:31:56Z"
}

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

POST

workspaces

{workspaceId}

objectives

{objectiveId}

:continue

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 objectiveEvent = await client.objectives.continue('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
  workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
  message: 'message',
});

console.log(objectiveEvent.data);

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_event = client.objectives.continue_(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    message="message",
)
print(objective_event.data)

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"),
	)
	objectiveEvent, err := client.Objectives.Continue(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveContinueParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Message:     "message",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveEvent.Data)
}

require "cadenya"

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

objective_event = cadenya.objectives.continue(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  message: "message"
)

puts(objective_event)

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}:continue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "enqueue": true
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}:continue",
  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([
    'message' => '<string>',
    'enqueue' => true
  ]),
  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/{objectiveId}:continue")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"<string>\",\n  \"enqueue\": true\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "type": "userMessage",
    "userMessage": {
      "content": "<string>"
    }
  },
  "contextWindowId": "objwin_01HXKD2E5NQM3T9AYWCFN7BSTR",
  "info": {
    "objective": {
      "id": "<string>",
      "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
      "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
      "createdAt": "2023-11-07T05:31:56Z",
      "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
      "labels": {},
      "externalId": "<string>"
    },
    "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>"
      }
    }
  },
  "duration": "<string>",
  "startedAt": "2023-11-07T05:31:56Z"
}

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

An objective that answers you does not end. It parks in STATE_WAITING with its context window open, holding everything it learned. Continue it and the agent picks up mid-thought, with every tool result and memory read from the previous turns still in front of it. That is the difference between a conversation and a series of unrelated requests.

const event = await client.objectives.continue(objectiveId, {
  workspaceId,
  message: 'Now draft the refund email.',
});

console.log(event.data?.type); // userMessage

event, err := client.Objectives.Continue(ctx, objectiveID,
	cadenya.ObjectiveContinueParams{
		WorkspaceID: cadenya.String(workspaceID),
		Message:     "Now draft the refund email.",
	})

event = cadenya.objectives.continue(
  objective_id,
  workspace_id: workspace_id,
  message: "Now draft the refund email."
)

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}:continue" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Now draft the refund email." }'

The call returns the userMessage event it appended, not the agent’s reply. The objective drops back to STATE_PENDING and starts working. Read the answer by streaming events or waiting for STATE_WAITING again.

In bash and zsh, brace the variable: "${OBJECTIVE_ID}:continue". Unbraced, the shell eats the :c as a modifier and the request lands on a path that does not exist.

Only a waiting objective accepts a turn

This is the whole contract, and it is strict:

Objective state	`:continue`
`STATE_WAITING`	Accepted. The turn appends and the agent resumes.
`STATE_PENDING` or `STATE_RUNNING`	`400`. The agent is mid-turn.
`STATE_FINALIZED`, `STATE_CANCELLED`, `STATE_FAILED`, `STATE_TIMED_OUT`	`400`. Terminal. Start a new objective.

A message is required. An empty body is a 400. So a chat UI where the user types while the agent is still answering has to wait. There is no fire-and-forget: you poll or stream until the objective is waiting, then send.

async function sendTurn(objectiveId: string, message: string) {
  // The agent may still be working on the previous turn.
  for (;;) {
    const objective = await client.objectives.retrieve(objectiveId, { workspaceId });

    if (objective.state === 'STATE_WAITING') break;
    if (objective.state !== 'STATE_PENDING' && objective.state !== 'STATE_RUNNING') {
      throw new Error(`objective is ${objective.state}; start a new one`);
    }
    await new Promise((r) => setTimeout(r, 500));
  }

  return client.objectives.continue(objectiveId, { workspaceId, message });
}

Streaming is the better shape for a real UI: watch for the assistant’s last message, enable your input box, and send when the user submits. Polling like the preceding code is the version that fits in a page.

The request carries an enqueue flag, described as buffering the message until the agent loop is free. It has no effect today. A STATE_RUNNING objective rejects the call with or without it.

What carries across a turn

Everything. That is the point. The context window persists, so previous tool results, memory reads, and assistant reasoning stay available. Compaction handles the window filling up: old turns get summarized or their tool bodies stripped, and the objective keeps going rather than failing. What you cannot change mid-conversation: the variation, the system prompt, the assigned tools, or the memory cascade. All of that was snapshotted into configSnapshot when the objective was created. A turn is a message, not a reconfiguration. Publish a new variation and existing conversations keep running the old one, which is usually what you want.

Driving a conversation

The full loop, with the first turn and every turn after it looking almost the same:

// Turn one creates the objective.
const objective = await client.objectives.create({
  workspaceId,
  agentId: 'external_id:support',
  systemPromptData: { company: 'Acme' },
  firstUserMessage: 'A customer cannot log in.',
  metadata: { externalId: `chat-${sessionId}` },
});

// Every turn after continues it. The external ID means you never store obj_ IDs.
await sendTurn(`external_id:chat-${sessionId}`, 'They already tried a password reset.');
await sendTurn(`external_id:chat-${sessionId}`, 'Now draft the refund email.');

Set metadata.externalId on the objective and your session ID becomes the handle. A web server handling turn seventeen needs nothing in its database beyond the session. To end a conversation, cancel it. A waiting objective holds its context window until something closes it, and an idle objective is eventually finalized as STATE_TIMED_OUT by the variation’s inactivityTimeout, or by the system-wide 24-hour sweep.

Create an objective

The first turn, and where the conversation’s configuration is fixed.

Stream objective events

Watch the reply arrive instead of polling for it.

Compaction

What happens to a long conversation when the window fills.

Use your own IDs

Address a conversation by your session ID, forever.

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"

objectiveId

string

required

The ID of the objective. If you have assigned an external ID to the objective, you can prefix the ID with "external_id:". For example, "external_id:1234567890". Otherwise, the ID assigned by Cadenya should be used.

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Body

application/json

message

string

required

The message to continue an objective that has completed (or you are enqueing)

enqueue

boolean

When set to true, the message will be enqueued for when the agent loop is available to process it.

Response

metadata

object

required

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

Show child attributes

data

object

required

Show child attributes

contextWindowId

string

Example:

"objwin_01HXKD2E5NQM3T9AYWCFN7BSTR"

info

object

Show child attributes

duration

string

read-only

Elapsed time of the work this event records, when it is known at write time (e.g. assistant message generation, tool execution for result/error events). Unset means the event is instantaneous or the duration is not measurable. Serialized as a canonical duration string (e.g. "4.1s"). Always set together with started_at.

Pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$

startedAt

string<date-time>

read-only

When the work this event records began. Set together with duration, so the work interval is [started_at, started_at + duration]. The event's created_at remains the time the event was persisted.

​Only a waiting objective accepts a turn

​What carries across a turn

​Driving a conversation

​Related

Create an objective

Stream objective events

Compaction

Use your own IDs

Authorizations

Path Parameters

Body

Response

Only a waiting objective accepts a turn

What carries across a turn

Driving a conversation

Related