# List RCS Agents

`POST /rcs/agents/list`

List all RCS agents with pagination. Results are sorted by creation date, newest first.

## Authentication

Send your API key in the `PINNACLE-API-KEY` header.

## Request body

Required.

Content type: `application/json`.

### Fields

- `pageIndex` — `integer`, optional, default: 0; minimum: 0
- `pageSize` — `integer`, optional, default: 20; minimum: 1; maximum: 100
- `agentType` — `string`, optional, values: `PRODUCTION`, `TEST`. Filter by agent type.
- `name` — `string`, optional, minimum length: 1; maximum length: 200. Case-insensitive substring search on agent name.

### Example

```json
{
  "pageIndex": 0,
  "pageSize": 20,
  "agentType": "PRODUCTION",
  "name": "Acme Support"
}
```

## Responses

### 200

Returns paginated list of agents.

Content type: `application/json`. Schema: `ListAgentsResponse`.

- `data` — `object[]`
- `data[].agentId` — `string`. Unique identifier for the agent.
- `data[].agentType` — `string`, values: `PRODUCTION`, `TEST`. Type of the agent.
- `data[].serviceId` — `string`, optional. Service ID associated with the agent.
- `data[].carrierLaunches` — `object`, optional. Raw per-carrier launch + verification state for the agent. Each
value is tri-state — `null` means "no launch requested" or "not
sent yet"; `false` means "pending" / "sent"; `true` means
"launched" / "verified". Use the GET /rcs/{agentId}
endpoint for the resolved enum representation.
- `data[].carrierLaunches.ATT` — `boolean`, optional. Launch status for AT&T. null = not requested, false = pending, true = launched.
- `data[].carrierLaunches.OTHERS` — `boolean`, optional. Launch status for other carriers. null = not requested, false = pending, true = launched.
- `data[].carrierLaunches.TMOBILE` — `boolean`, optional. Launch status for T-Mobile. null = not requested, false = pending, true = launched.
- `data[].carrierLaunches.VERIZON` — `boolean`, optional. Launch status for Verizon. null = not requested, false = pending, true = launched.
- `data[].carrierLaunches.AEGIS` — `boolean`, optional. AEGIS verification status. null = not sent, false = sent, true = verified.
- `data[].carrierLaunches.GOOGLE` — `boolean`, optional. Google verification status. null = not sent, false = sent, true = verified.
- `data[].config` — `object`, optional. Agent configuration details.
- `data[].config.name` — `string`, optional. Display name of the agent (max 40 characters).
- `data[].config.description` — `string`, optional. Description of the agent (max 100 characters).
- `data[].config.color` — `string`, optional. Hex color code for the agent.
- `data[].config.websites` — `object[]`, optional
- `data[].config.websites[].url` — `string`, optional
- `data[].config.websites[].label` — `string`, optional
- `data[].config.phones` — `object[]`, optional
- `data[].config.phones[].phone` — `string`, optional
- `data[].config.phones[].label` — `string`, optional
- `data[].config.emails` — `object[]`, optional
- `data[].config.emails[].email` — `string`, optional
- `data[].config.emails[].label` — `string`, optional
- `data[].config.iconUrl` — `string`, optional. Logo image URL.
- `data[].config.heroUrl` — `string`, optional. Hero image URL.
- `data[].config.privacyUrl` — `string`, optional. Privacy policy URL.
- `data[].config.termsUrl` — `string`, optional. Terms of service URL.
- `data[].config.isConversational` — `boolean`, optional. Whether the agent supports two-way conversation.
- `data[].config.agentUseCase` — `string`, optional, values: `TRANSACTIONAL`, `PROMOTIONAL`, `OTP`, `MULTI_USE`. Use case for the agent.
- `data[].createdAt` — `string`. ISO 8601 timestamp of when the agent was created.
- `data[].updatedAt` — `string`. ISO 8601 timestamp of when the agent was last updated.
- `hasMore` — `boolean`
- `count` — `integer`

Example:

```json
{
  "data": [
    {
      "agentId": "agent_abc123",
      "agentType": "TEST",
      "serviceId": "pinnacletest_agent",
      "carrierLaunches": {
        "ATT": null,
        "TMOBILE": true,
        "VERIZON": false,
        "OTHERS": null
      },
      "config": {
        "name": "My Test Agent",
        "description": "A test RCS agent",
        "color": "#FF6B00"
      },
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-20T14:00:00Z"
    }
  ],
  "hasMore": false,
  "count": 1
}
```

### 400

Validation failed. The payload has missing required fields and/or invalid types.

See https://zod.dev/error-formatting for more information.

Content type: `application/json`. Schema: `object`.

- `description` — `string`. Human-readable summary of validation failures.
- `errors` — `object`. Structured dictionary of issues containing two main sections:
- `errors`: Array of global validation errors not tied to specific fields
- `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array

Example:

```json
{
  "description": "✖ Invalid input: expected string, received number\n  → at example_field",
  "errors": {
    "errors": [
      "Unrecognized key: 'extraKey'"
    ],
    "properties": {
      "example_field": {
        "errors": [
          "Invalid input: expected string, received NaN"
        ]
      }
    }
  }
}
```

### 401

The request lacks valid authentication credentials or the provided credentials are invalid.

Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "Invalid API key."
}
```

### 500

An unexpected error occurred on Pinnacle's servers while processing your request.

If this error persists, please contact support with the request details.

Content type: `application/json`. Schema: `object`.

- `error` — `string`. Human-readable description of the error that occurred, corresponding to the HTTP status code.

Example:

```json
{
  "error": "An unexpected error occurred while processing your request."
}
```

## SDK examples

### TypeScript

```typescript
import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.rcs.agents.list();
```

### Python

```python
import os
from rcs import Pinnacle

client = Pinnacle(
    api_key=os.environ["PINNACLE_API_KEY"],
)

client.rcs.agents.list()
```

### Ruby

```ruby
require "rcs"

client = Pinnacle::Client.new(
  api_key: ENV.fetch("PINNACLE_API_KEY")
)

client.rcs.agents.list
```

## Machine-readable schema

[OpenAPI 3.1 JSON](https://docs.pinnacle.sh/openapi.json)