Wrap an HTTP API

Use the HTTP adapter when an API has no OpenAPI specification, or when you want to expose only a few hand-designed operations. The tool set stores a shared base URL and headers. Each tool defines its method, path, arguments, and optional request body. This guide wraps JSONPlaceholder’s public todo endpoint as a read-only GetTodo tool. You configure it in the dashboard, then verify the live request from code.

What you need

A Cadenya workspace.
A published agent, or permission to create one with Create and publish an agent.
CADENYA_API_KEY and CADENYA_WORKSPACE_ID for the code examples.

Create the HTTP tool set

Set the shared connection

Select Tool Sets, click Create Tool Set, and select HTTP. Enter this Base URL:

https://jsonplaceholder.typicode.com

HTTP connection step with JSONPlaceholder entered as the base URL — A shared base URL for every tool in the set

Use Add header when every endpoint needs the same value. Store credentials as secrets and reference them as ${SECRET_NAME}:

Authorization: Bearer ${TODO_API_TOKEN}

Tool-level headers can add or override values for one endpoint.

Name and create the set

Click Continue and enter:

Field	Value
Name	`Public Todos`
Description	`Read public todo records from JSONPlaceholder.`
External ID	`public-todos`

Review the configuration, then click Create Tool Set.The new Tools tab is empty. HTTP tool sets do not discover operations. You define each tool explicitly.

Add the read-only tool

On the Tools tab, click Add Tool.

Describe the model-facing call

Enter:

Field	Value
Name	`get_todo`
Description	`Get a public todo record by its numeric ID.`
Requires Approval	Not required

Under Parameters, click Convert a JSON payload to a schema and paste:

{
  "todoId": 1
}

Click Convert, inspect the inferred schema, then click Accept. The resulting JSON Schema requires one integer named todoId. The metadata Name identifies the Cadenya resource. Tool Name is the function name sent to the model. Keeping those names separate lets you use a conventional resource name while giving the model a concise operation name.

Configure the request

Under HTTP configuration, enter:

Field	Value
Request Method	GET
Path	`/todos/{{ arguments.todoId }}`
Query	Leave empty
Tool Name	`GetTodo`

HTTP tool configuration with GET, a Liquid path using arguments.todoId, and GetTodo as the tool name — A GET path rendered from the model's validated argument

The parameter schema controls what the model may send. Liquid renders those validated values into the request:

Base URL: https://jsonplaceholder.typicode.com
Path:     /todos/{{ arguments.todoId }}
Argument: { "todoId": 7 }
Request:  GET https://jsonplaceholder.typicode.com/todos/7

Keep the arguments. prefix. {{ arguments.todoId }} reads the tool argument; {{ todoId }} does not.

Click Create tool.

Verify the saved tool

The Tools tab now reports one available tool. Select get_todo and confirm:

The LLM tool name is GetTodo.
The adapter badge is HTTP.
The parameter schema requires integer todoId.
Approval is not required.

Public Todos tool set showing get_todo as an available HTTP tool with GetTodo as its LLM name — The available GetTodo tool and its parameter schema

HTTP tools do not have sync events because their definitions live in Cadenya. Edit the tool whenever its request or model-facing schema changes.

Assign the tool set to an agent

Open an agent variation, add Public Todos under Assignments, and use a system prompt such as:

Use GetTodo with the numeric ID from the user.
Return a compact JSON object containing id, title, and completed from the result.

Publish the agent after saving the assignment.

Dispatch a todo lookup

Set CADENYA_AGENT_ID to the published agent’s ID, then choose an example:

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'] });
const workspaceId = process.env['CADENYA_WORKSPACE_ID']!;
const agentId = process.env['CADENYA_AGENT_ID']!;

const objective = await client.objectives.create({
  workspaceId,
  agentId,
  systemPromptData: {},
  firstUserMessage: 'Get todo 7.',
});

console.log(objective.metadata.id);

curl "https://api.cadenya.com/v1/workspaces/${CADENYA_WORKSPACE_ID}/objectives" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
        \"agentId\": \"${CADENYA_AGENT_ID}\",
        \"systemPromptData\": {},
        \"firstUserMessage\": \"Get todo 7.\"
      }"

The vetted run produced:

userMessage → assistantMessage → toolCalled → toolResult → assistantMessage

The tool call contained { "todoId": 7 }. JSONPlaceholder returned todo 7, and the agent replied:

{
  "id": 7,
  "title": "illo expedita consequatur quia in",
  "completed": false
}

Create the same resources from the SDK

Provisioning code creates the empty HTTP tool set and then adds each operation:

const toolSet = await client.toolSets.create({
  workspaceId,
  metadata: { name: 'Public Todos', externalId: 'public-todos' },
  spec: {
    description: 'Read public todo records from JSONPlaceholder.',
    adapter: {
      type: 'http',
      http: { baseUrl: 'https://jsonplaceholder.typicode.com' },
    },
  },
});

const tool = await client.toolSets.tools.create(toolSet.metadata.id, {
  workspaceId,
  metadata: { name: 'get_todo', externalId: 'get-todo' },
  spec: {
    description: 'Get a public todo record by its numeric ID.',
    requiresApproval: false,
    parameters: {
      type: 'object',
      properties: {
        todoId: { type: 'integer' },
      },
      required: ['todoId'],
    },
    llmToolName: 'GetTodo',
    config: {
      type: 'http',
      http: {
        requestMethod: 'GET',
        path: '/todos/{{ arguments.todoId }}',
      },
    },
  },
});

Configure other request shapes

Every templated field reads from the same arguments object.

Query parameters

Keep the path stable and render the query separately:

Path:  /search
Query: q={{ arguments.query }}&limit={{ arguments.limit }}

Include both query and limit in the tool’s parameter schema.

JSON request bodies

For POST, PUT, or PATCH, set Request Body Content Type and Request Body Template:

Request Body Content Type: application/json
Request Body Template:
{ "todoId": {{ arguments.todoId }}, "completed": {{ arguments.completed }} }

The path, query, headers, and body all support Liquid. Make the parameter schema match the values the template renders.

Approval for writes

Select Required for tools that change data, send messages, move money, or trigger another sensitive action. The objective pauses before Cadenya sends the request. Your application can then approve or deny the tool call.

Trace requests

Cadenya adds correlation headers to every HTTP call:

Header	Identifies
`x-cadenya-tool-call-id`	The tool call
`x-cadenya-objective-id`	The objective
`x-cadenya-agent-id`	The agent
`x-cadenya-agent-variation-id`	The selected variation

Log these values on the receiving service to connect its request record to the Cadenya timeline.

You now have a hand-defined HTTP tool whose UI schema, Liquid path, live GET request, tool result, and agent response have all been verified.

Next steps

Require approval

Pause sensitive HTTP writes before Cadenya sends them.

Store credentials

Put provider tokens behind secret references.

Run tools in your code

Keep execution inside a private worker instead of exposing an endpoint.

Tool sets from the SDK

Manage tools, assignments, updates, and archival from code.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Wrap an HTTP API

What you need

Create the HTTP tool set

Add the read-only tool

Describe the model-facing call

Configure the request

Verify the saved tool

Assign the tool set to an agent

Dispatch a todo lookup

Create the same resources from the SDK

Configure other request shapes

Query parameters

JSON request bodies

Approval for writes

Trace requests

Next steps

Require approval

Store credentials

Run tools in your code

Tool sets from the SDK

​What you need

​Create the HTTP tool set

​Add the read-only tool

​Describe the model-facing call

​Configure the request

​Verify the saved tool

​Assign the tool set to an agent

​Dispatch a todo lookup

​Create the same resources from the SDK

​Configure other request shapes

​Query parameters

​JSON request bodies

​Approval for writes

​Trace requests

​Next steps

Require approval

Store credentials

Run tools in your code

Tool sets from the SDK

What you need

Create the HTTP tool set

Add the read-only tool

Describe the model-facing call

Configure the request

Verify the saved tool

Assign the tool set to an agent

Dispatch a todo lookup

Create the same resources from the SDK

Configure other request shapes

Query parameters

JSON request bodies

Approval for writes

Trace requests

Next steps