> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replicas

> List and create avatar replicas for AI interviewers

## Overview

Replicas are the avatar/voice personas used by [AI Interviewers](/api-reference/interviews).
Use these endpoints to list the replicas available to a team or to register a new one. A
replica's `id` is what you pass as `aiConfiguration.replicaId` when creating an AI
interview.

<Callout type="info">
  Only safe replica fields are returned. Provider credentials and sync internals are never
  exposed by the API.
</Callout>

## List Replicas

List the replicas available to the team.

**Endpoint:** `GET /qsi/gather/replicas`

<ParamField query="teamId" type="string">
  Override the team context for this request.
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.prod.qualifi.hr/qsi/gather/replicas \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/replicas', {
      headers: { 'x-api-key': apiKey }
    });
    const { data } = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/replicas',
        headers={'x-api-key': api_key}
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "replicas": [
        {
          "id": "replica-uuid",
          "name": "Professional Avatar",
          "photoUrl": "https://example.com/avatar.png",
          "replicaId": "replica-ext-id",
          "organizationId": "org-uuid",
          "teamId": "team-uuid",
          "createdById": "user-uuid",
          "createdAt": "2026-01-15T00:00:00Z",
          "updatedAt": "2026-01-15T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "req-uuid",
      "timestamp": "2026-01-15T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Create Replica

Register a new replica for the team.

**Endpoint:** `POST /qsi/gather/replicas`

<ParamField name="name" type="string" required>
  Display name for the replica.
</ParamField>

<ParamField name="photoUrl" type="string" required>
  URL of the avatar photo.
</ParamField>

<ParamField name="teamId" type="string">
  Override the team context for this request.
</ParamField>

<ParamField name="userId" type="string">
  User to record as the creator. Resolved from the API credential if not provided.
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.prod.qualifi.hr/qsi/gather/replicas \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Professional Avatar",
        "photoUrl": "https://example.com/avatar.png"
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/replicas', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Professional Avatar',
        photoUrl: 'https://example.com/avatar.png'
      })
    });
    const { data } = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        'https://api.prod.qualifi.hr/qsi/gather/replicas',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'name': 'Professional Avatar',
            'photoUrl': 'https://example.com/avatar.png'
        }
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "replica": {
        "id": "replica-uuid",
        "name": "Professional Avatar",
        "photoUrl": "https://example.com/avatar.png",
        "replicaId": "replica-ext-id",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2026-01-15T00:00:00Z",
        "updatedAt": "2026-01-15T00:00:00Z"
      }
    },
    "meta": {
      "requestId": "req-uuid",
      "timestamp": "2026-01-15T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Configure AI interviewers that use a replica
  </Card>

  <Card title="Score Card Templates" icon="clipboard-check" href="/api-reference/score-card-templates">
    Define scoring rubrics for interviews
  </Card>
</CardGroup>