API Cheat Sheet - Bluejay Docs

For the base URL and authentication, see the API introduction.

Test

Simulations

Method	Path	Description
POST	`/v1/create-simulation`	Creates a simulation for an agent and returns `simulation_id`.
POST	`/v1/simulation/{simulation_id}/add-digital-humans`	Links existing Digital Humans to a simulation.
POST	`/v1/simulation/{simulation_id}/remove-digital-humans`	Unlinks Digital Humans from a simulation.
PUT	`/v1/simulation/{simulation_id}`	Updates a simulation.
GET	`/v1/simulation/{simulation_id}`	Returns one simulation by `simulation_id`.
GET	`/v1/get-all-simulations`	Returns all simulations in your organization, for all agents.
GET	`/v1/get-simulations-by-agent/{agent_id}`	Returns the simulations for one agent.
DELETE	`/v1/simulation/{simulation_id}`	Deletes a simulation by `simulation_id`.
POST	`/v1/queue-http-text-simulation-run`	Starts a text run for an HTTP agent and returns `simulation_run_id` and `simulation_result_ids`.
POST	`/v1/send-http-text-message`	Sends one agent turn into a running HTTP text simulation.

Simulation runs

Method	Path	Description
POST	`/v1/queue-simulation-run`	Queues a run of a simulation and returns the run ID.
POST	`/v1/queue-sms-simulation-run`	Queues an SMS run of a simulation.
GET	`/v1/get-simulation-runs/{simulation_id}`	Returns the runs of a simulation.
POST	`/v1/update-simulation-result`	Adds tool calls, events, tags, metadata, and trace IDs to a simulation result.
GET	`/v1/retrieve-simulation-results/{simulation_run_id}`	Returns a simulation run and one page of its results, oldest first.
GET	`/v1/retrieve-simulation-result/{test_result_id}`	Returns one simulation result and its custom metric results.
POST	`/v1/end-conversations`	Ends running conversations.

Digital Humans

Method	Path	Description
POST	`/v1/create-digital-human`	Creates one Digital Human.
POST	`/v1/create-digital-humans`	Creates many Digital Humans in one request.
POST	`/v1/generate-digital-humans`	Generates Digital Humans for an agent and links them to the simulation.
PUT	`/v1/update-digital-human/{digital_human_id}`	Updates a Digital Human.
GET	`/v1/digital-human/{digital_human_id}`	Returns one Digital Human by `digital_human_id`.
GET	`/v1/digital-humans-by-simulation/{simulation_id}`	Returns the Digital Humans linked to a simulation.
GET	`/v1/digital-humans`	Returns the Digital Humans in your organization, newest first.
DELETE	`/v1/digital-human/{digital_human_id}`	Deletes a Digital Human by `digital_human_id`.
POST	`/v1/generate-objectives`	Generates objectives from the intent of a Digital Human and saves them on the Digital Human.
POST	`/v1/generate-intent-summary`	Writes `intent_summary` on a Digital Human.

Personalities

Method	Path	Description
GET	`/v1/personalities`	Returns the personality library of your organization.
POST	`/v1/personalities`	Creates one or more personalities.
PATCH	`/v1/personalities/{personality_id}`	Updates a personality.
DELETE	`/v1/personalities/{personality_id}`	Deletes a personality and removes it from every simulation that selects it.
GET	`/v1/simulations/{simulation_id}/personalities`	Returns the personalities that a simulation runs with.
PUT	`/v1/simulations/{simulation_id}/personalities`	Replaces the personality selection of a simulation.
POST	`/v1/create-customer-persona`	Creates a customer persona with `name`, `description`, and `goal`.
PUT	`/v1/update-customer-persona/{persona_id}`	Updates a customer persona.
GET	`/v1/customer-persona/{persona_id}`	Returns one customer persona by `persona_id`.
GET	`/v1/customer-personas-by-agent/{agent_id}`	Returns the customer personas for one agent.
DELETE	`/v1/customer-persona/{persona_id}`	Deletes a customer persona and its agent links.

Communities

Method	Path	Description
POST	`/v1/create-community`	Creates a community.
PUT	`/v1/update-community/{community_id}`	Updates a community.
PUT	`/v1/add-to-community/{community_id}`	Adds Digital Humans to a community.
GET	`/v1/community/{community_id}`	Returns one community by `community_id`.
GET	`/v1/communities`	Returns the communities in your organization.
DELETE	`/v1/community/{community_id}`	Deletes a community.

Custom background noises

Method	Path	Description
GET	`/v1/custom-background-noises`	Returns the custom background noises in your organization, oldest first.
POST	`/v1/custom-background-noises/upload-url`	Returns `upload_url` and `storage_path`.
POST	`/v1/custom-background-noises`	Adds an uploaded file to the background noise library.
PATCH	`/v1/custom-background-noises/{noise_id}`	Renames a custom background noise.
DELETE	`/v1/custom-background-noises/{noise_id}`	Removes a custom background noise from the library.

Scenario Builder

Method	Path	Description
POST	`/v1/scenario`	Creates a scenario.
GET	`/v1/scenario`	Returns `workflows` and `total_count`.
GET	`/v1/scenario/{workflow_id}`	Returns one scenario with its full `definition`.
PUT	`/v1/scenario/{workflow_id}`	Updates a scenario.
DELETE	`/v1/scenario/{workflow_id}`	Deletes a scenario.

Schedules

Method	Path	Description
POST	`/v1/create-schedule`	Creates a schedule for a simulation.
GET	`/v1/schedules`	Returns the schedules for the agents you can see.
GET	`/v1/schedule/{schedule_id}`	Returns one schedule by `schedule_id`.
PUT	`/v1/update-schedule/{schedule_id}`	Updates a schedule and returns the updated schedule.
DELETE	`/v1/delete-schedule/{schedule_id}`	Deletes a schedule.

Red Teaming

Method	Path	Description
POST	`/v1/red-team-simulations`	Starts a red team test against an agent.
GET	`/v1/red-team-simulations`	Returns the red team tests for the agents you can see.
GET	`/v1/red-team-simulations/{test_id}`	Returns one red team test by `test_id`.
POST	`/v1/red-team-simulations/{test_id}/stop`	Stops a red team test.
GET	`/v1/red-team-simulations/entitlements`	Returns `custom_matrix`.

Metrics

Method	Path	Description
POST	`/v1/create-metric`	Creates one custom metric.
POST	`/v1/create-metrics`	Creates many custom metrics in one request.
PUT	`/v1/update-metric/{metric_id}`	Updates one custom metric.
PUT	`/v1/update-metrics`	Applies the same `updates` to each metric in `metric_ids`.
GET	`/v1/metric/{metric_id}`	Returns one custom metric.
GET	`/v1/metrics`	Returns custom metrics.
GET	`/v1/custom-metrics-by-agent/{agent_id}`	Deprecated. This endpoint is deprecated.
DELETE	`/v1/metric/{metric_id}`	Deletes one custom metric.
POST	`/v1/delete-metrics`	Deletes many custom metrics.

Monitor

Logs

Method	Path	Description
POST	`/v1/evaluate`	Sends one production conversation for evaluation.
POST	`/v1/re-evaluate/{conversation_id}`	Creates a new evaluation for a conversation.
GET	`/v1/observability/conversations`	Returns production conversations, newest first.
GET	`/v1/observability/conversations/{conversation_id}`	Returns one production conversation with its transcript and metric results.
GET	`/v1/retrieve-call-log/{call_id}`	Returns one call log and its evaluations.
GET	`/v1/retrieve-call-logs/{agent_id}`	Deprecated. This endpoint is deprecated.
DELETE	`/v1/call-log/{call_id}`	Deletes a call log.
POST	`/v1/translate-transcript`	Translates a transcript.

Uptime monitors

Method	Path	Description
GET	`/v1/uptime/monitors`	Returns the uptime monitors in your organization.
GET	`/v1/uptime/monitors/{monitor_id}`	Returns one uptime monitor and its recent checks.
POST	`/v1/uptime/monitors`	Creates an uptime monitor and the simulation and schedule that run it.
PUT	`/v1/uptime/monitors/{monitor_id}`	Updates an uptime monitor.
DELETE	`/v1/uptime/monitors/{monitor_id}`	Deletes an uptime monitor and stops its scheduled checks.
GET	`/v1/uptime/monitors/{monitor_id}/series`	Returns outcome counts, uptime percentage, and p50, p90, p95, and p99 latency per time bucket.
POST	`/v1/uptime/monitors/{monitor_id}/incidents/resolve`	Resolves every unresolved DOWN check of a monitor.
POST	`/v1/uptime/monitors/{monitor_id}/checks/{check_id}/resolve`	Resolves one DOWN check.
POST	`/v1/uptime/monitors/{monitor_id}/checks/{check_id}/unresolve`	Opens a resolved DOWN check again.
GET	`/v1/uptime/monitors/{monitor_id}/checks/{check_id}/transcript`	Returns the transcript of one check.

Issues

Method	Path	Description
GET	`/v1/observability/issues`	An issue is a problem that Bluejay finds across your calls.
GET	`/v1/observability/issues/{issue_id}`	Returns one issue.
PUT	`/v1/observability/issues/{issue_id}`	Updates an issue.

Alerts

Method	Path	Description
POST	`/v1/create-alert`	Creates an alert.
PUT	`/v1/update-alert/{alert_id}`	Updates an alert.
GET	`/v1/alerts`	Returns the alerts in your organization.
GET	`/v1/alerts/{alert_id}/results`	Returns the times an alert fired, newest first.
DELETE	`/v1/alert/{alert_id}`	Deletes an alert and its agent links.

Dashboards

Method	Path	Description
GET	`/v1/dashboards`	Returns dashboards, newest first.
POST	`/v1/dashboards`	Creates an empty dashboard.
GET	`/v1/dashboards/{dashboard_id}`	Returns a dashboard and its widgets, in layout order.
PUT	`/v1/dashboards/{dashboard_id}`	Updates the name or description of a dashboard.
PUT	`/v1/dashboards/{dashboard_id}/layout`	Sets the position and size of widgets on a dashboard.
POST	`/v1/dashboards/{dashboard_id}/duplicate`	Creates a copy named `<name> (Copy)` with a copy of each widget in the same layout.
DELETE	`/v1/dashboards/{dashboard_id}`	Deletes a dashboard, its widgets, and their metrics.
GET	`/v1/widgets`	Returns widgets with their metrics, newest first.
POST	`/v1/widgets`	Creates a widget on a dashboard.
GET	`/v1/widgets/{widget_id}`	Returns one widget and its metrics.
PUT	`/v1/widgets/{widget_id}`	Replaces the full configuration and metrics of a widget.
POST	`/v1/widgets/{widget_id}/duplicate`	Creates a copy named `Copy of <name>` on the dashboard in `dashboard_id`.
DELETE	`/v1/widgets/{widget_id}`	Deletes a widget and its metrics.

Traces

Method	Path	Description
GET	`/v1/traces`	Returns recent traces for the conversations you can see.
POST	`/v1/traces/{trace_id}`	Returns one trace and its spans.
POST	`/v1/spans/{trace_id}/{span_id}`	Returns one span of a trace.

Webhooks

Method	Path	Description
`WEBHOOK`	`Your URL`	To receive events at your own server, register a webhook URL in the dashboard and subscribe it to the events you want.

Improve

Self-Improve

Method	Path	Description
POST	`/v1/self-improve/runs`	Starts a loop that changes the agent prompt, pushes it to the provider, and runs the simulation to score it.
GET	`/v1/self-improve/runs`	Returns the Self-Improve runs for the agents you can see.
GET	`/v1/self-improve/runs/{run_id}`	Returns one Self-Improve run by `run_id`.
POST	`/v1/self-improve/runs/{run_id}/stop`	Requests a stop and returns `STOP_REQUESTED`.

Metrics Lab

Method	Path	Description
GET	`/v1/metrics-lab/labs`	Returns labs, newest first, with counts.
POST	`/v1/metrics-lab/lab`	Creates a lab with a set of conversations and custom metrics.
GET	`/v1/metrics-lab/lab/{lab_id}`	Returns the full lab.
PUT	`/v1/metrics-lab/lab/{lab_id}`	Updates the name or description of a lab.
PUT	`/v1/metrics-lab/lab/{lab_id}/settings`	Merges the settings you send into the current lab settings.
DELETE	`/v1/metrics-lab/lab/{lab_id}`	Deletes a lab.
POST	`/v1/metrics-lab/lab/{lab_id}/metrics`	Adds custom metrics to a lab.
POST	`/v1/metrics-lab/lab/{lab_id}/conversations`	Adds conversations to a lab.
DELETE	`/v1/metrics-lab/lab/{lab_id}/conversations`	Removes conversations from a lab.
POST	`/v1/metrics-lab/evaluate-conversation`	Queues an evaluation of one conversation with the metrics you send.
PUT	`/v1/metrics-lab/lab/{lab_id}/human-evaluation`	Creates or updates the human label for one metric on one conversation.
POST	`/v1/metrics-lab/lab/{lab_id}/metric-revisions`	Creates a revision of a custom metric in a lab.

Configure

Agents

Method	Path	Description
POST	`/v1/add-agent`	Adds an agent.
POST	`/v1/update-agent`	Updates an agent by `agent_id`.
PUT	`/v1/update-agent-by-external-id`	Updates an agent by `external_agent_id`, the ID of the agent at your voice provider.
PUT	`/v1/folders/move-agent`	Moves an agent into a folder.
GET	`/v1/agents/{agent_id}`	Returns one agent by `agent_id`.
GET	`/v1/agent-by-external-id/{external_id}`	Returns one agent by `external_agent_id`.
GET	`/v1/agents/{agent_id}/workflow/summary`	Returns the workflow of one agent as `nodes` and `edges`.
POST	`/v1/agents/{agent_id}/workflow/sync`	Pulls the latest workflow of one agent from its provider.
GET	`/v1/get-agents-by-folder/{folder_id}`	Returns the ID and name of each agent in a folder.
GET	`/v1/all-agents`	Returns all agents in your organization.
DELETE	`/v1/agent/{agent_id}`	Deletes an agent by `agent_id`.

Agent versions

Method	Path	Description
POST	`/v1/agents/{agent_id}/versions`	Creates the next agent version of an agent.
POST	`/v1/agents/{agent_id}/versions/promote`	Moves the `production` label to the latest version, or to the version in `version`.
GET	`/v1/agents/{agent_id}/versions`	Returns the agent versions of an agent.
GET	`/v1/agents/{agent_id}/versions/{version}`	Returns one agent version by number.
GET	`/v1/agents/{agent_id}/versions/{prompt_id}`	Returns one agent version by UUID.
GET	`/v1/agents/{agent_id}/prompts`	Deprecated. This endpoint is deprecated.
DELETE	`/v1/agents/{agent_id}/versions/{version}`	Deletes one agent version.
DELETE	`/v1/agents/{agent_id}/versions`	Deletes the version that has the `label` you send.
DELETE	`/v1/agents/{agent_id}/versions/{prompt_id}`	Deletes one agent version by UUID.
GET	`/v1/agents/{agent_id}/versions/{version}/labels`	Returns the labels on one agent version.
POST	`/v1/agents/{agent_id}/versions/{version}/labels`	Adds labels to one agent version.
DELETE	`/v1/agents/{agent_id}/versions/{version}/labels`	Removes labels from one agent version.

Knowledge Bases

Method	Path	Description
POST	`/v1/knowledge-base`	Creates an empty Knowledge Base.
GET	`/v1/knowledge-base`	Returns the Knowledge Bases in your organization, each with `document_count`.
GET	`/v1/knowledge-base/{knowledge_base_id}`	Returns a Knowledge Base and its documents.
PUT	`/v1/knowledge-base/{knowledge_base_id}`	Updates a Knowledge Base.
DELETE	`/v1/knowledge-base/{knowledge_base_id}`	Deletes a Knowledge Base and returns 204.
POST	`/v1/knowledge-base/{knowledge_base_id}/agents/{agent_id}`	Links an agent to a Knowledge Base.
DELETE	`/v1/knowledge-base/{knowledge_base_id}/agents/{agent_id}`	Unlinks an agent from a Knowledge Base and returns 204.

Organization

Method	Path	Description
POST	`/v1/agents/{agent_id}/labels`	Creates a label for an agent.
GET	`/v1/agents/{agent_id}/labels`	Returns the labels of an agent.
GET	`/v1/agents/{agent_id}/labels/{label_id}`	Returns one label.
PUT	`/v1/agents/{agent_id}/labels/{label_id}`	Renames a label.
DELETE	`/v1/agents/{agent_id}/labels/{label_id}`	Deletes a label.
POST	`/v1/create-folder`	Creates a folder for agents.
PUT	`/v1/update-folder/{folder_id}`	Renames a folder.
GET	`/v1/folder/{folder_id}`	Returns one folder.
GET	`/v1/all-folders`	Returns all folders in your organization.
DELETE	`/v1/folder/{folder_id}`	Deletes a folder.
GET	`/v1/phone-numbers`	Returns the phone numbers in your organization.

Integrations

Method	Path	Description
POST	`/v1/integrations/amelia/sync`	Imports each Amelia AI agent that the Amelia integration account can see.
GET	`/v1/integrations/amelia/agents`	Returns the AI agent names in one Amelia domain.
GET	`/v1/integrations/amelia/flows`	Returns the flow names in one Amelia domain.

Last modified on October 21, 2026

⌘I