Sign in

v56

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01142337440.5 KB
ObjectiveService
Objectives

Create a new objective

Creates a new objective in the workspace

post/v1/workspaces/{workspaceId}/objectives

Path parameters

workspaceIdstring required
Example:workspace_01HXKD2E5NQM3T9AYWCF133E3Q

Request body

workspaceIdstring required
agentIdstring required
variationIdstring

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

systemPromptDataobject 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.

firstUserMessagestring

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.

firstUserMessageDataobject

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.

pinnedParametersobject

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.

Example request

{
  "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  "agentId": "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "variationId": "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  "memoryCascade": [
    {
      "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH",
      "memoryEntryId": "mementry_01HXKD2E5NQM3T9AYWCF5E52Z0"
    }
  ],
  "episodicMemory": {
    "memoryLayerId": "memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH"
  },
  "tenant": {
    "id": "acme-corp",
    "name": "Acme Corp"
  },
  "subject": {
    "id": "customer-user-42",
    "name": "Jane Doe"
  }
}

Response

OK

state'STATE_UNSPECIFIED' | 'STATE_PENDING' | 'STATE_RUNNING' | 'STATE_WAITING' | 'STATE_FAILED' | 'STATE_CANCELLED' | 'STATE_FINALIZED' | 'STATE_TIMED_OUT' enum required

The current lifecycle state of the objective.

stateMessagestring

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

systemPromptstring required

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

firstUserMessagestring 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.

parentObjectiveIdstring

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

systemPromptDataobject

Arbitrary data rendered into the variation's system_prompt_template

outputobject

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

firstUserMessageDataobject

Arbitrary data rendered into the variation's first_user_message_template

pinnedParametersobject

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