Safety & DetectionDetect Agents

Run Investigation

POST https://app.resemble.ai/api/v2/agents/{uuid}/run

Run a Detect Agent against uploaded media or a public URL. The response is a live Server-Sent Events (SSE) stream.

Path Parameters

ParameterTypeDescription
uuidstringStable agent identifier returned in the uuid field by GET /agents.

Use a uuid returned by List Detect Agents.

Form Fields

Send the request as multipart/form-data.

FieldTypeRequiredDescription
filefileConditionalMedia to analyze. Required when url is omitted.
urlstringConditionalPublic media URL to analyze. Required when file is omitted.
querystringNoQuestion or investigation objective.
evidence[]file[]NoSupporting evidence files. Repeat the field for multiple files.
check_urlsstringNoAdditional URLs for the agent to check during the investigation.

When both file and url are provided, the uploaded file is sent for analysis. Prefer sending only one primary media source.

The run request selects a managed Detect Agent by its identifier. It does not accept agent configuration, tier, prompt, or memory overrides.

Analyze a file

$curl --no-buffer --request POST \
>  'https://app.resemble.ai/api/v2/agents/verify_document/run' \
>  -H 'Authorization: Bearer YOUR_API_KEY' \
>  -H 'Accept: text/event-stream' \
>  -F 'file=@/path/to/clip.mp4' \
>  -F 'query=Is this clip authentic, and where did it first appear?' \
>  -F 'evidence[]=@/path/to/source-screenshot.png' \
>  -F 'check_urls=https://example.com/original-post'

Analyze a public URL

$curl --no-buffer --request POST \
>  'https://app.resemble.ai/api/v2/agents/verify_document/run' \
>  -H 'Authorization: Bearer YOUR_API_KEY' \
>  -H 'Accept: text/event-stream' \
>  -F 'url=https://example.com/media/clip.mp4' \
>  -F 'query=Assess the authenticity and provenance of this clip.'

Stream Response

Each event is emitted as an SSE data frame containing JSON. The first frame identifies the persisted run:

data: {"type":"run_started","run_id":"6b208dee-f515-48d7-a895-cd595c46aa6d"}
data: {"type":"token","text":"I will inspect the submitted media and corroborate the available evidence."}
data: {"type":"message_end"}
data: {"type":"tool_call","id":"call_1","tool":"run_detect","args":{}}
data: {"type":"tool_result","id":"call_1","tool":"run_detect","output":"Detection completed.","detect":{"uuid":"DETECT_UUID","label":"fake","score":0.97,"media_type":"video"}}
data: {"type":"final_verdict","intelligence":"{\"recommended_action\":\"reject\",\"confidence\":0.98}","forced":false}
data: {"type":"done"}

Common event types include:

TypeMeaning
run_startedThe run record was created. Save run_id for later retrieval.
resolvedA submitted URL was resolved to analyzable media.
documentA document was parsed and its page, image, and text counts are available.
detectResemble Detect returned authenticity evidence and a label/score.
gateReports whether the investigative agent proceeded. Paid runs are configured for full investigation.
website_reportWebsite/domain authenticity findings are available.
thought / token / agent_messageIncremental agent output. Event availability depends on the selected agent.
message_endMarks the end of the current agent message.
tool_call / tool_resultA research or detection tool was invoked and returned evidence.
final_verdictFinal assessment. Its intelligence field is a string and may contain serialized JSON when the agent uses a schema.
doneThe stream completed successfully.
errorThe stream failed after opening. The run is persisted with status: "error".

Memory updates and token/cost accounting events are consumed and stored server-side. They are not sent in the public stream. Learned memory is persisted back to the agent for future investigations.

Persistence

The API creates the run before streaming and stores:

  • Submitted inputs and uploaded primary media
  • The exact effective configuration used for the run
  • Memory before and after the investigation
  • The event transcript
  • A compact result summary and any terminal error

The service continues recording the upstream investigation if the client disconnects, so run history remains available.

If this is the team’s first run with the selected Detect Agent, the service initializes the agent’s backing state automatically. This does not require a public create-agent request.

Errors Before Streaming

Errors found before the SSE stream opens are returned as JSON.

StatusMeaning
401 UnauthorizedMissing or invalid API key.
402 Payment RequiredThe run is blocked by billing or available credits.
403 ForbiddenThe account does not have Detect Agents access.
404 Not FoundThe agent identifier is unknown.
422 Unprocessable EntityNeither file nor url was provided.
1{
2  "success": false,
3  "message": "Provide a file or a url to analyze."
4}

After the stream opens, failures are reported as error SSE frames and the HTTP status remains 200 OK. Individual tools can also report failures inside a tool_result while the overall investigation continues to final_verdict and done.