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

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

All requests require an API key:

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.

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} 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 and select the investigator that matches your verification workflow.
2. Save its uuid and run an investigation 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.

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
}

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.

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;
}

Endpoints

• GET /agents — List catalog and custom investigators
• GET /agents/{uuid} — Get one investigator, including its skills
• POST /agents/{uuid}/run — Stream an investigation
• GET /agents/{uuid}/runs — List an agent’s recent runs
• GET /agents/{uuid}/runs/{run_id} — Get a persisted run