Deny a tool call

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 objectiveToolCall = await client.objectives.toolCalls.deny(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  'toolcall_01HXKD2E5NQM3T9AYWCFTANFGV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);

console.log(objectiveToolCall.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_tool_call = client.objectives.tool_calls.deny(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    tool_call_id="toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(objective_tool_call.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"),
	)
	objectiveToolCall, err := client.Objectives.ToolCalls.Deny(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
		cadenya.ObjectiveToolCallDenyParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveToolCall.Data)
}

require "cadenya"

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

objective_tool_call = cadenya.objectives.tool_calls.deny(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_tool_call)

cadenya objectives:tool-calls deny \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --tool-call-id toolcall_01HXKD2E5NQM3T9AYWCFTANFGV

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}:deny \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memo": "<string>"
}
'

<?php

$curl = curl_init();

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

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "callable": {
      "type": "tool",
      "tool": {
        "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"
      }
    },
    "arguments": {},
    "memo": "<string>",
    "statusChangedBy": {
      "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>"
      }
    },
    "resolvedSecrets": [
      {
        "key": "<string>"
      }
    ]
  },
  "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>"
      }
    },
    "tool": {
      "id": "<string>",
      "name": "<string>"
    },
    "toolSet": {
      "id": "<string>",
      "name": "<string>"
    }
  }
}

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

POST

workspaces

{workspaceId}

objectives

{objectiveId}

tool_calls

{toolCallId}

:deny

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 objectiveToolCall = await client.objectives.toolCalls.deny(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  'toolcall_01HXKD2E5NQM3T9AYWCFTANFGV',
  { workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);

console.log(objectiveToolCall.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_tool_call = client.objectives.tool_calls.deny(
    objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
    tool_call_id="toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
    workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(objective_tool_call.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"),
	)
	objectiveToolCall, err := client.Objectives.ToolCalls.Deny(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
		cadenya.ObjectiveToolCallDenyParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveToolCall.Data)
}

require "cadenya"

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

objective_tool_call = cadenya.objectives.tool_calls.deny(
  "obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
  "toolcall_01HXKD2E5NQM3T9AYWCFTANFGV",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(objective_tool_call)

cadenya objectives:tool-calls deny \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --tool-call-id toolcall_01HXKD2E5NQM3T9AYWCFTANFGV

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/tool_calls/{toolCallId}:deny \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memo": "<string>"
}
'

<?php

$curl = curl_init();

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

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "callable": {
      "type": "tool",
      "tool": {
        "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"
      }
    },
    "arguments": {},
    "memo": "<string>",
    "statusChangedBy": {
      "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>"
      }
    },
    "resolvedSecrets": [
      {
        "key": "<string>"
      }
    ]
  },
  "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>"
      }
    },
    "tool": {
      "id": "<string>",
      "name": "<string>"
    },
    "toolSet": {
      "id": "<string>",
      "name": "<string>"
    }
  }
}

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

A tool behind approval parks at TOOL_CALL_STATUS_WAITING_FOR_APPROVAL and the objective waits. Denying it tells the agent the action is off the table.

await client.objectives.toolCalls.deny(toolCallId, {
  workspaceId,
  objectiveId,
  memo: 'Do not invent company names. Ask the user for the real one.',
});

_, err := client.Objectives.ToolCalls.Deny(ctx, objectiveID, toolCallID,
	cadenya.ObjectiveToolCallDenyParams{
		WorkspaceID: cadenya.String(workspaceID),
		Memo:        cadenya.String("Do not invent company names. Ask the user for the real one."),
	})

cadenya.objectives.tool_calls.deny(
  tool_call_id,
  workspace_id: workspace_id,
  objective_id: objective_id,
  memo: "Do not invent company names. Ask the user for the real one."
)

curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/tool_calls/${TOOL_CALL_ID}:deny" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"memo": "Do not invent company names. Ask the user for the real one."}'

The tool never runs. The agent keeps working.

The memo is the difference between a wall and a hint

Deny with no memo and the agent knows only that it may not do that. It shrugs and tries something else:

deny {}
→ toolDenied  { toolCallId: 'toolcall_01KX1QTA...', memo: '' }
→ assistant:  "Let me check what fake data generators are available:"

Deny with a memo and the agent reads it, in the same run:

deny { memo: 'Do not invent company names. Ask the user for the real one.' }
→ toolDenied  { toolCallId: 'toolcall_01KX1QRH...', memo: 'Do not invent company names. ...' }
→ assistant:  "I apologize, but I'm unable to generate fake company names.
               I can only generate fake data for Acme's legitimate..."

Both are real runs of the same agent on the same message. The memo is the steering wheel: it lands in the agent’s context as the reason, so it can pick a different approach rather than guess at your policy. Write the memo as an instruction to the agent, not a note to your audit log. “Refund exceeds the $500 limit; escalate to a human instead” gives the agent somewhere to go. “Denied” does not.

The response reports the state before the decision

Denial resolves asynchronously, and the response body carries almost nothing:

const response = await client.objectives.toolCalls.deny(toolCallId, { workspaceId, objectiveId });

response.status;           // 'TOOL_CALL_STATUS_UNSPECIFIED'
response.executionStatus;  // 'TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED'

Read the call back for the settled state:

const settled = await client.objectives.toolCalls.retrieve(toolCallId, { workspaceId, objectiveId });

settled.status;           // 'TOOL_CALL_STATUS_DENIED'
settled.executionStatus;  // 'TOOL_CALL_EXECUTION_STATUS_PENDING'  ← it never ran
settled.data.memo;        // the memo you sent
settled.data.statusChangedBy;  // the profile that decided

executionStatus stays PENDING forever. That is the tell: a denied call is one that was never executed, not one that failed.

Deciding twice

A tool call can be decided once. A second decision, in either direction, comes back 404:

POST .../tool_calls/{id}:deny     → 200
POST .../tool_calls/{id}:deny     → 404  "tool call ... is not pending approval"
POST .../tool_calls/{id}:approve  → 404  "tool call ... is not pending approval"

That 404 does not mean the tool call is missing. It means someone already decided, or the objective moved on. The message says so; the status code does not.An approval queue with two reviewers hits this on day one. Treat a 404 on :deny as “refresh and show the outcome”, not as “this does not exist.”

Finding the calls waiting on you

const parked = await client.objectives.toolCalls.list(objectiveId, {
  workspaceId,
  status: 'TOOL_CALL_STATUS_WAITING_FOR_APPROVAL',
});

for await (const call of parked) {
  if (call.data.callable.type !== 'tool') continue;
  console.log(call.data.callable.tool.name, call.data.arguments);
  // GenerateFake { name: 'company' }
}

The toolApprovalRequested event fires on the stream the moment a call parks, so a UI does not have to poll. toolDenied fires when you decide, carrying the toolCallId and the memo.

Putting a tool behind approval

Approval is a property of the tool, and a synced tool set does not let you edit its tools:

PATCH .../tools/{id}  { spec: { requiresApproval: true } }
→ 400  "tools on a synced source (MCP or OpenAPI URL) are managed automatically
        and cannot be created, edited, or deleted directly"

Set it on the adapter instead, and every synced tool inherits it:

await client.toolSets.update(toolSetId, {
  workspaceId,
  spec: {
    adapter: {
      type: 'mcp',
      mcp: {
        url: 'https://free.cadenya.com/faker-mcp',
        toolApprovals: { type: 'always', always: true },
      },
    },
  },
});

Use an only filter in toolApprovals to gate a subset. For bare and HTTP tools, which you define by hand, set requiresApproval on the tool directly.

Approve a tool call

The other decision, and the same 404 on a second one.

List tool calls

Filter by WAITING_FOR_APPROVAL to build the queue.

Create a tool set

toolApprovals, and why synced tools reject edits.

Set tool call content

When you want the human to be the tool, not only gate it.

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. Supports "external_id:" prefix for external IDs.

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

toolCallId

string

required

The ID of the tool call to deny

Example:

"toolcall_01HXKD2E5NQM3T9AYWCFTANFGV"

Body

application/json

memo

string

A memo to associate to the tool call denial. Use a memo to steer the LLM to a different decision or usage of the tool.

Response

ObjectiveToolCall is a record of a tool call made during an objective's execution. Tool calls are mutable — their status changes as they are approved, denied, or executed.

metadata

object

required

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

Show child attributes

data

object

required

Show child attributes

status

enum<string>

required

Current status of the tool call

Available options:

TOOL_CALL_STATUS_UNSPECIFIED,

TOOL_CALL_STATUS_AUTO_APPROVED,

TOOL_CALL_STATUS_WAITING_FOR_APPROVAL,

TOOL_CALL_STATUS_APPROVED,

TOOL_CALL_STATUS_DENIED

executionStatus

enum<string>

required

read-only

Available options:

TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED,

TOOL_CALL_EXECUTION_STATUS_PENDING,

TOOL_CALL_EXECUTION_STATUS_RUNNING,

TOOL_CALL_EXECUTION_STATUS_COMPLETED,

TOOL_CALL_EXECUTION_STATUS_ERRORED,

TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT

info

object

Show child attributes

​The memo is the difference between a wall and a hint

​The response reports the state before the decision

​Deciding twice

​Finding the calls waiting on you

​Putting a tool behind approval

​Related

Approve a tool call

List tool calls

Create a tool set

Set tool call content

Authorizations

Path Parameters

Body

Response

The memo is the difference between a wall and a hint

The response reports the state before the decision

Deciding twice

Finding the calls waiting on you

Putting a tool behind approval

Related