Safety & Detection

Investigate Media with a Detect Agent

Choose one of Resemble’s managed Detect Agents, stream an investigation, and retrieve the persisted result for later review.

What You Will Build

This walkthrough covers the complete public Detect Agent lifecycle:

  1. List the six available Detect Agents.
  2. Select an agent and run it against a public media URL.
  3. Read the Server-Sent Events (SSE) stream.
  4. Retrieve the saved investigation and its run history.

Prerequisites

  • A Resemble API token with Detect Agents access
  • A publicly accessible media URL, or a local file to upload
  • curl and jq

Set your API token:

$export RESEMBLE_API_TOKEN="YOUR_API_TOKEN"

1. Choose a Detect Agent

List the Detect Agents available to your team:

$curl --silent --show-error --fail-with-body \
>  --request GET 'https://app.resemble.ai/api/v2/agents' \
>  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
>  > detect-agents.json
$
$jq -r '.items[] | [.uuid, .name, .description] | @tsv' detect-agents.json

Choose the agent that matches your investigation and save its uuid. For example:

$export AGENT_UUID="verify_document"

Agent names and capabilities are managed by Resemble and may evolve. Use the list response as the source of truth instead of hard-coding the available set.

2. Run an Investigation

Set a public media URL and the question you want the agent to investigate:

$export MEDIA_URL="https://example.com/media/clip.mp4"
$export INVESTIGATION_QUERY="Assess the authenticity and provenance of this clip."

Start the investigation and save the complete SSE stream:

$curl --no-buffer --show-error --fail-with-body \
>  --request POST \
>  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/run" \
>  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
>  -H 'Accept: text/event-stream' \
>  -F "url=${MEDIA_URL}" \
>  -F "query=${INVESTIGATION_QUERY}" \
>  | tee investigation.sse

To upload a local file instead, replace the url form field with:

$-F 'file=@/path/to/media.mp4'

You can also attach supporting evidence with repeated evidence[] fields or provide related pages through check_urls.

The public API runs Resemble-managed Detect Agents. It does not create agents or accept prompt, configuration, tier, or memory overrides.

3. Follow the Event Stream

Each line beginning with data: contains a JSON event. The most important events are:

EventWhat to do
run_startedSave the run_id; it identifies the persisted investigation.
tool_result or detectInspect the authenticity evidence produced during the investigation.
final_verdictRead the agent’s final assessment. The intelligence value can contain serialized JSON.
doneThe stream completed successfully.
errorThe stream failed after opening; the failed run is still persisted.

Extract the run ID from the saved stream:

$export RUN_ID=$(sed -n 's/^data: //p' investigation.sse \
>  | jq -r 'select(.type == "run_started") | .run_id' \
>  | head -n 1)
$
$echo "Run ID: ${RUN_ID}"

The service continues recording the investigation if the client disconnects, so you can still retrieve the saved run.

4. Retrieve the Investigation

Fetch the persisted run after the stream finishes:

$curl --silent --show-error --fail-with-body \
>  --request GET \
>  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/runs/${RUN_ID}" \
>  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
>  | jq

The response includes:

  • status and a compact result
  • The submitted inputs
  • The replayable event transcript
  • The effective config_snapshot
  • memory_before and memory_after
  • A terminal error, when one occurred

Use the stored result when your application needs to show the investigation again without replaying the live stream.

5. List Recent Runs

Retrieve up to 100 of the selected agent’s most recent investigations:

$curl --silent --show-error --fail-with-body \
>  --request GET \
>  "https://app.resemble.ai/api/v2/agents/${AGENT_UUID}/runs" \
>  -H "Authorization: Bearer ${RESEMBLE_API_TOKEN}" \
>  | jq

The list contains compact summaries in newest-first order. Retrieve an individual run when you need its transcript, snapshots, or media details.

Troubleshooting

ResponseWhat to check
401 UnauthorizedThe API token is missing or invalid.
402 Payment RequiredBilling or available credits blocked the run.
403 ForbiddenThe account does not have Detect Agents access.
404 Not FoundThe selected agent UUID is unknown, or the run does not belong to that agent.
422 Unprocessable EntityNeither a file nor a url was supplied.

Errors that occur after the stream opens arrive as error SSE events while the HTTP response remains 200 OK.

Endpoint Guides