Skip to main content
POST
Run test cases from a JSON spec file

Authorizations

X-CEKURA-API-KEY
string
header
required

API Key Authentication. It should be included in the header of each request.

Query Parameters

dry_run
boolean

Validate and price the spec without running or charging anything.

Body

Accepts a spec as a JSON body or an uploaded file.

CI posts JSON directly; the dashboard uploads the same file the customer has in their repo. Both land in spec.

spec
any

The test-suite spec. Use this when posting JSON directly.

file
string<uri>

A .json spec file. Use this instead of 'spec' for uploads.

agent_id
integer

Agent to test. Overrides 'agent_id' in the spec, letting one spec file run against several environments.

name
string

Label for this run. Defaults to the spec's suite name.

Maximum string length: 255
channel
enum<string>

How to reach the agent: 'voice' for a phone call (the default), 'text' for chat, 'elevenlabs' for an ElevenLabs WebRTC session, or 'livekit_v2' or 'pipecat_v2' for their respective WebRTC sessions.

  • voice - voice
  • text - text
  • elevenlabs - elevenlabs
  • livekit_v2 - livekit_v2
  • pipecat_v2 - pipecat_v2
Available options:
voice,
text,
elevenlabs,
livekit_v2,
pipecat_v2
frequency
integer

Run every test case this many times, on top of each case's own 'frequency' in the spec. Default 1.

Required range: x >= 1
agent_number
string

Voice and text only. The agent's phone number for this run, in E.164 format, overriding the agent's configured contact number.

outbound_phone_number
string

Voice and text only. For an inbound voice agent, the number Cekura dials, in E.164 format; defaults to 'agent_number', then the agent's contact number. Rejected for outbound voice agents: set 'phone_number' per test case in the spec instead. For SMS and WhatsApp agents, the contact number for the conversation.

mode
enum<string>

Voice, inbound agents only. 'same_number' (default) places every call from the same Cekura number; 'different_numbers' spreads them across the pool and cannot be combined with 'phone_number' in the spec.

  • same_number - same_number
  • different_numbers - different_numbers
Available options:
same_number,
different_numbers
concurrency_limit
integer

Cap on the number of runs executed in parallel. Overrides the spec's 'defaults.concurrency_limit'.

Required range: x >= 1
mock_tool_names
string[] | null

Names of mock tools to activate for this run. Omit (or send null) to mock every tool configured on the agent; send an empty list to mock none.

livekit_data
object

Optional LiveKit overrides. These apply only to this run and are not part of the portable test-suite spec.

pipecat_data
object

Optional Pipecat Cloud overrides. These apply only to this run and are not part of the portable test-suite spec.

Response

id
integer

ID of the result

agent
integer

ID of the agent

status
enum<string>

Status of the result

Available options:
pending,
running,
completed,
failed
run_as_text
boolean

Whether the scenario ran as text or not

Example:

false

runs
object[]
Examples:
created_at
string<date-time>
Example:

"2025-02-25T21:00:01.990052Z"