> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Investigator

Investigator runs media-authenticity investigations. Resemble provides seven ready-to-run catalog investigators, each designed for a specific verification workflow, and a team can also have custom investigators with their own instructions and skills. Every investigation combines Resemble Detect evidence with an evidence-based assessment.

Choose an investigator, submit uploaded media or a public URL, and consume the investigation as a Server-Sent Events (SSE) stream. Completed and failed investigations are persisted so you can retrieve their results later.

## Base URL

```text
https://app.resemble.ai/api/v2
```

All requests require an API key:

```http
Authorization: Bearer YOUR_API_KEY
```

Your account must have Investigator access. An authenticated account without access receives `403 Forbidden`.

## Available Investigators

Seven catalog investigators are available out of the box.

| Investigator                     | `preset_id`                  | Workflow                                                                 | Managed tier    |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------------------ | --------------- |
| Investigate Social Media Content | `investigate_social_content` | Decide whether suspicious social content should remain available         | `investigation` |
| Review an Insurance Claim        | `review_insurance_claim`     | Determine whether submitted claim evidence is credible                   | `investigation` |
| Verify Breaking News Media       | `verify_breaking_news`       | Authenticate and source-trace footage before publishing                  | `investigation` |
| Verify a Document or Receipt     | `verify_document`            | Determine whether a submitted record is genuine                          | `forensic`      |
| Verify Submitted Evidence        | `verify_evidence`            | Produce an explainable forensic finding                                  | `forensic`      |
| Verify an ID                     | `verify_id`                  | Verify an identity document and the person presenting it                 | `forensic`      |
| Web Investigation                | `website_check`              | Decide whether a site and its content can be trusted before acting on it | `investigation` |

Catalog investigators are managed by Resemble, and `GET /agents` always returns all seven. When a team runs one for the first time, its backing state is initialized automatically.

## Custom Investigators

A custom investigator is configured for your team in the Resemble app, with its own instructions, tier, output format, and skills. `GET /agents` lists your team's active custom investigators after the catalog ones. A custom investigator has a UUID `uuid` and a `null` `preset_id`.

With an API key you can inspect, run, and read the history of your own team's custom investigators. Another team's investigators and archived ones return `404 Not Found`.

### Skills

Skills are playbooks a custom investigator can open when a task matches. The agent sees each enabled skill's name and description, and reads the body only when the skill applies. For example, an ID-verification investigator can carry one skill per country's documents.

[`GET /agents/{uuid}`](/detect/investigator/get) returns a custom investigator's skills. Runs include its enabled skills automatically. Skills are created and edited in the app; the API returns them read-only and a run request cannot add or override them.

## Public API Scope

The public API is read-and-run. Investigators, their configuration, and their skills are managed in the Resemble app.

You can:

* List the catalog investigators and your team's custom investigators
* Get one investigator, including a custom investigator's skills
* Run an investigation with an investigator
* List an investigator's runs
* Retrieve a specific investigation run

The supported public contract does not include creating, updating, archiving, or deleting investigators or their skills. Configuration, tier, and memory are read-only, and the shape of `config` is not part of the supported contract.

## Typical Workflow

1. [List Investigators](/detect/investigator/list) and select the investigator that matches your verification workflow.
2. Save its `uuid` and [run an investigation](/detect/investigator/run) against a file or public URL.
3. Consume the SSE stream for live evidence and the final assessment.
4. Use the returned `run_id` to retrieve the persisted run, or list the investigator's recent runs.

## Investigator Shape

`GET /agents` returns read-only metadata for every investigator. Catalog names, capabilities, and ordering are controlled by Resemble and may evolve over time, so use the API response as the source of truth.

```ts
interface Investigator {
  id: string; // Stable identifier; the same as uuid
  uuid: string; // The preset_id for a catalog investigator, a UUID for a custom one
  name: string;
  description: string | null;
  preset_id: string | null; // null for a custom investigator
  tier: "triage" | "investigation" | "forensic";
  memory_preview: string;
  capabilities: {
    media: boolean;
    reverse_search: boolean;
    identity: boolean;
    grounding: boolean;
    structured: boolean;
    tools: boolean;
    knowledge: boolean;
  };
  tagline: string | null;
  display: Record<string, unknown> | null; // Catalog metadata; null for a custom investigator
  activated: boolean;
  created_at: string | null;
  updated_at: string | null;
}

// GET /agents/{uuid} adds:
interface InvestigatorDetail extends Investigator {
  memory: string;
  config: Record<string, unknown>; // Read-only; shape not part of the contract
  skills?: Array<{
    name: string;
    description: string;
    body: string;
    enabled: boolean;
    position: number;
  }>; // Custom investigators only
}
```

> **Note**
>
> For a catalog investigator, `id`, `uuid`, and `preset_id` contain the same identifier, such as `verify_id`. For a custom investigator, `id` and `uuid` contain a UUID and `preset_id` is `null`. The `tier`, capabilities, memory, and skills are informational and cannot be changed through the public API.

## Investigation Run Shape

Run-list responses return compact summaries. A run-detail response also includes the replay transcript and audit snapshots recorded during the investigation.

```ts
interface InvestigationRun {
  uuid: string;
  status: "running" | "completed" | "error";
  result: {
    verdict?: { forced?: boolean; excerpt?: string };
    recommended_action?: string | null;
    confidence?: number | null;
    label?: string | null;
    score?: number | null;
    agent_ran?: boolean | null;
  };
  inputs: {
    query?: string;
    url?: string;
    filename?: string;
    check_urls?: string;
  };
  has_media: boolean;
  created_at: string | null;
  updated_at: string | null;
  transcript?: Array<Record<string, unknown>>;
  config_snapshot?: Record<string, unknown>;
  memory_before?: string;
  memory_after?: string;
  error?: string | null;
  media_url?: string | null;
}
```

> **Note**
>
> Token and cost accounting is retained internally for billing but is never returned in run summaries, run-detail transcripts, or the live SSE stream.

## Endpoints

* [`GET /agents`](/detect/investigator/list) — List catalog and custom investigators
* [`GET /agents/{uuid}`](/detect/investigator/get) — Get one investigator, including its skills
* [`POST /agents/{uuid}/run`](/detect/investigator/run) — Stream an investigation
* [`GET /agents/{uuid}/runs`](/detect/investigator/list-runs) — List an agent's recent runs
* [`GET /agents/{uuid}/runs/{run_id}`](/detect/investigator/get-run) — Get a persisted run