Skip to main content
POST
/
api
/
agents
Create evaluation agent
curl --request POST \
  --url https://agent-evalserver-production.up.railway.app/api/agents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Support bot evaluation",
  "seed": 123,
  "numNodes": 100,
  "publicUrl": "https://example.com/chat",
  "label": "eval"
}
'
{
  "id": "2f7e9c9c-9a2e-4e3a-b77f-6d9d1a7e3a11",
  "name": "Support bot evaluation",
  "seed": 123,
  "numNodes": 100,
  "publicUrl": "https://example.com/chat",
  "advancedPayload": null,
  "label": "eval",
  "created_at": "2026-06-02T15:00:00Z",
  "updated_at": "2026-06-02T15:00:00Z"
}

Authorizations

​
x-api-key
string
header
required

Platform API key for authenticated account-level API access

Body

application/json

Register an external agent endpoint so Rippletide can run evaluations against it.

​
name
string
required

Human-readable name for the evaluation agent, such as Support Bot Eval.

Example:

"Support bot evaluation"

​
seed
integer
required

Deterministic seed for the evaluation setup. Use any integer; 123 is fine for manual calls.

Example:

123

​
numNodes
integer
default:100
required

Evaluation graph size hint. Use 100 for normal integrations.

Example:

100

​
publicUrl
string<uri> | null

Public HTTPS endpoint for your agent. Rippletide calls this endpoint when it runs tests.

Example:

"https://example.com/chat"

​
advancedPayload
object

Optional request payload template for non-standard agent APIs. Omit this unless your endpoint does not accept the default message payload.

Example:
{
  "payload": "{\"message\":\"[eval-question]\"}"
}
​
label
enum<string>
default:eval

Set to eval for public evaluation workflows.

Available options:
eval
Example:

"eval"

Response

Evaluation agent created

Evaluation agent registered in Rippletide. This record tells Rippletide what external agent endpoint to test and how to store evaluation results.

​
name
string
required

Human-readable name for this evaluation agent.

Example:

"Support bot evaluation"

​
seed
integer
required

Deterministic seed used by the evaluation setup. Use any integer; the CLI generates one automatically.

Example:

123

​
numNodes
integer
default:100
required

Evaluation graph size hint. Use 100 unless the Rippletide team recommends another value.

Example:

100

​
id
string<uuid>

Unique agent identifier returned by Rippletide. Use this ID in later evaluation API calls.

Example:

"2f7e9c9c-9a2e-4e3a-b77f-6d9d1a7e3a11"

​
publicUrl
string<uri> | null

Public HTTPS endpoint for the agent Rippletide should evaluate.

Example:

"https://example.com/chat"

​
advancedPayload
object

Optional request payload template used when Rippletide calls the agent endpoint. Omit this for standard chat-style APIs.

Example:
{
  "payload": "{\"message\":\"[eval-question]\"}"
}
​
label
enum<string>
default:eval

Public integrations should use eval.

Available options:
eval
Example:

"eval"

​
created_at
string<date-time>

Creation timestamp.

Example:

"2026-06-02T15:00:00Z"

​
updated_at
string<date-time>

Last update timestamp.

Example:

"2026-06-02T15:05:00Z"