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

# Call Queues API — ACD Queue Management REST Endpoints

> Create and manage ACD call queues via REST API. Queues distribute inbound calls across extension-based agents within a LaraCopilot tenant.

Call queues (ACD queues) hold inbound callers in a waiting pool and distribute them to available agents according to a configurable `strategy`. Each queue has a `queue_number` that callers dial or that DIDs route to, a `timeout` controlling the maximum hold time in seconds, and a `status` flag controlling whether the queue is active. All endpoints require an active admin session. The list endpoint supports an optional `search` parameter that matches against `name`, `queue_number`, and `strategy`. List and show responses include the parent `tenant` and the assigned `agents` relations.

***

## GET /api/queues

Returns all call queues ordered by creation date descending, with `tenant` and `agents` relations included.

**Query parameters**

<ParamField query="search" type="string">
  Optional. Filters queues whose `name`, `queue_number`, or `strategy` contains the given string (case-insensitive).
</ParamField>

<ResponseField name="message" type="string">
  Value is `"Queues fetched successfully."`.
</ResponseField>

<ResponseField name="data" type="array">
  Array of queue objects.

  <Expandable title="queue object fields">
    <ResponseField name="data[].id" type="integer">
      Auto-incremented primary key.
    </ResponseField>

    <ResponseField name="data[].tenant_id" type="integer">
      ID of the tenant this queue belongs to.
    </ResponseField>

    <ResponseField name="data[].name" type="string">
      Human-readable name for the queue, e.g. `"Support Queue"`.
    </ResponseField>

    <ResponseField name="data[].queue_number" type="string">
      The dialable number or extension used to reach this queue, e.g. `"5000"`.
    </ResponseField>

    <ResponseField name="data[].strategy" type="string">
      Call distribution strategy, e.g. `roundrobin`, `leastrecent`, or `ringall`.
    </ResponseField>

    <ResponseField name="data[].timeout" type="integer">
      Maximum time in seconds a caller waits in the queue before overflow. Minimum: `1`.
    </ResponseField>

    <ResponseField name="data[].status" type="string">
      Lifecycle status, e.g. `active` or `inactive`.
    </ResponseField>

    <ResponseField name="data[].tenant" type="object">
      The parent tenant object.
    </ResponseField>

    <ResponseField name="data[].agents" type="array">
      Array of queue agent objects (extension-based members of this queue).
    </ResponseField>

    <ResponseField name="data[].created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="data[].updated_at" type="string">
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl https://your-instance.laracopilot.com/api/queues \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```bash Request (with search) theme={null}
  curl "https://your-instance.laracopilot.com/api/queues?search=support" \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "Queues fetched successfully.",
    "data": [
      {
        "id": 1,
        "tenant_id": 1,
        "name": "Support Queue",
        "queue_number": "5000",
        "strategy": "roundrobin",
        "timeout": 60,
        "status": "active",
        "tenant": { "id": 1, "name": "Acme Corp" },
        "agents": [],
        "created_at": "2025-03-01T09:00:00.000000Z",
        "updated_at": "2025-03-01T09:00:00.000000Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## POST /api/queues

Creates a new call queue and returns `201 Created` with the record.

<ParamField body="tenant_id" type="integer" required>
  ID of the tenant to assign this queue to. Must reference an existing tenant.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable queue name. Maximum 255 characters.
</ParamField>

<ParamField body="queue_number" type="string" required>
  Dialable number or short code for the queue, e.g. `"5001"`. Maximum 20 characters.
</ParamField>

<ParamField body="strategy" type="string" required>
  Agent selection strategy, e.g. `roundrobin`, `leastrecent`, `ringall`. Maximum 100 characters.
</ParamField>

<ParamField body="timeout" type="integer" required>
  Maximum caller wait time in seconds. Minimum value: `1`.
</ParamField>

<ParamField body="status" type="string" required>
  Lifecycle status, e.g. `active` or `inactive`. Maximum 50 characters.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"Queue created successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created queue record.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://your-instance.laracopilot.com/api/queues \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "name": "Sales Queue",
      "queue_number": "5001",
      "strategy": "leastrecent",
      "timeout": 120,
      "status": "active"
    }'
  ```

  ```json 201 Response theme={null}
  {
    "message": "Queue created successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "name": "Sales Queue",
      "queue_number": "5001",
      "strategy": "leastrecent",
      "timeout": 120,
      "status": "active",
      "created_at": "2025-04-22T10:45:00.000000Z",
      "updated_at": "2025-04-22T10:45:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## GET /api/queues/{queue}

Fetches a single call queue by its ID. Includes the parent `tenant` and `agents` relations.

**Path parameters**

<ParamField path="queue" type="integer" required>
  The numeric ID of the queue to retrieve.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"Queue loaded successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The queue record with `tenant` and `agents` included.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl https://your-instance.laracopilot.com/api/queues/2 \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "Queue loaded successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "name": "Sales Queue",
      "queue_number": "5001",
      "strategy": "leastrecent",
      "timeout": 120,
      "status": "active",
      "tenant": { "id": 1, "name": "Acme Corp" },
      "agents": [],
      "created_at": "2025-04-22T10:45:00.000000Z",
      "updated_at": "2025-04-22T10:45:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## PUT /api/queues/{queue}

Replaces all fields on an existing call queue. `PATCH /api/queues/{queue}` is also accepted and uses the same handler.

**Path parameters**

<ParamField path="queue" type="integer" required>
  The numeric ID of the queue to update.
</ParamField>

<ParamField body="tenant_id" type="integer" required>
  Must reference an existing tenant.
</ParamField>

<ParamField body="name" type="string" required>
  Maximum 255 characters.
</ParamField>

<ParamField body="queue_number" type="string" required>
  Maximum 20 characters.
</ParamField>

<ParamField body="strategy" type="string" required>
  Maximum 100 characters.
</ParamField>

<ParamField body="timeout" type="integer" required>
  Minimum value: `1`.
</ParamField>

<ParamField body="status" type="string" required>
  Maximum 50 characters.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"Queue updated successfully."`.
</ResponseField>

<ResponseField name="data" type="object">
  The updated queue record.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT https://your-instance.laracopilot.com/api/queues/2 \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -b cookies.txt \
    -d '{
      "tenant_id": 1,
      "name": "Sales Queue",
      "queue_number": "5001",
      "strategy": "ringall",
      "timeout": 90,
      "status": "active"
    }'
  ```

  ```json 200 Response theme={null}
  {
    "message": "Queue updated successfully.",
    "data": {
      "id": 2,
      "tenant_id": 1,
      "name": "Sales Queue",
      "queue_number": "5001",
      "strategy": "ringall",
      "timeout": 90,
      "status": "active",
      "created_at": "2025-04-22T10:45:00.000000Z",
      "updated_at": "2025-04-22T11:30:00.000000Z"
    }
  }
  ```
</CodeGroup>

***

## DELETE /api/queues/{queue}

Permanently deletes the specified call queue.

**Path parameters**

<ParamField path="queue" type="integer" required>
  The numeric ID of the queue to delete.
</ParamField>

<ResponseField name="message" type="string">
  Value is `"Queue deleted successfully."`.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://your-instance.laracopilot.com/api/queues/2 \
    -H "Accept: application/json" \
    -b cookies.txt
  ```

  ```json 200 Response theme={null}
  {
    "message": "Queue deleted successfully."
  }
  ```
</CodeGroup>