# Get Agent

`GET /rcs/{agentId}`

Retrieve details of an RCS agent by its ID.

Returns the agent's configuration including display name, description, logo, hero image,
contact information, and other settings.

## Authentication

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

## Parameters

- `agentId` — path, string. The RCS agent ID (must be prefixed with `agent_`).

## Responses

### 200

The agent details.

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

- `id` — `string`. The unique agent ID, prefixed with `agent_`.
- `type` — `string`, values: `TEST`. The agent type.
- `TEST` — A test agent for development and testing with whitelisted numbers only.
- `serviceId` — `string`. The RCS service ID assigned to this agent.
- `carrierLaunches` — `CarrierLaunches`. Per-carrier launch status grouped by category. `carriers` covers
AT&T / T-Mobile / Verizon / other carriers; `verification` covers
the AEGIS and Google verification flows.
- `carrierLaunches.carriers` — `object`. Per-carrier launch status. Each carrier moves through
`NOT_LAUNCHED` → `PENDING` → `LAUNCHED` as Pinnacle submits the
agent for review and the carrier accepts it. The agent is only
deliverable on a carrier once that carrier reports `LAUNCHED`.
- `carrierLaunches.carriers.ATT` — `string`, values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`. AT&T launch status.
- `carrierLaunches.carriers.TMOBILE` — `string`, values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`. T-Mobile launch status.
- `carrierLaunches.carriers.VERIZON` — `string`, values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`. Verizon launch status.
- `carrierLaunches.carriers.OTHERS` — `string`, values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`. Other carriers launch status.
- `carrierLaunches.verification` — `object`. External verifier status. AEGIS (the U.S. carrier vetting
authority used by AT&T, T-Mobile, and Verizon) and Google each
send a verification email to the brand's contact address. Each
verifier moves through `NOT_SENT` → `SENT` → `VERIFIED` once
the brand replies and the verifier confirms ownership.
- `carrierLaunches.verification.AEGIS` — `string`, values: `NOT_SENT`, `SENT`, `VERIFIED`. AEGIS verification status.
- `carrierLaunches.verification.GOOGLE` — `string`, values: `NOT_SENT`, `SENT`, `VERIFIED`. Google verification status.
- `details` — `RcsAgentDetails`. The configuration details of an RCS agent, as returned by the GET endpoint.
- `details.name` — `string`, optional. Display name of the agent.
- `details.description` — `string`, optional. Description of the agent.
- `details.iconUrl` — `string`, optional, format: uri. URL to the agent's logo image.
- `details.heroUrl` — `string`, optional, format: uri. URL to the agent's hero banner image.
- `details.color` — `string`, optional. The agent's brand color hex code.
- `details.phones` — `object[]`, optional. Contact phone numbers for the agent.
- `details.phones[].phone` — `string`, optional. Phone number in E.164 format.
- `details.phones[].label` — `string`, optional. Display label for the phone number.
- `details.emails` — `object[]`, optional. Contact email addresses for the agent.
- `details.emails[].email` — `string`, optional. Email address.
- `details.emails[].label` — `string`, optional. Display label for the email.
- `details.websites` — `object[]`, optional. Website links for the agent.
- `details.websites[].url` — `string`, optional. Website URL.
- `details.websites[].label` — `string`, optional. Display label for the website.
- `details.privacyUrl` — `string`, optional, format: uri. URL to the agent's privacy policy.
- `details.termsUrl` — `string`, optional, format: uri. URL to the agent's terms and conditions.
- `details.isConversational` — `boolean`, optional. Whether the agent supports two-way conversations. `true` for agents that respond
to user messages, `false` for send-only agents (e.g., notifications).
- `details.agentUseCase` — `string`, optional, values: `TRANSACTIONAL`, `PROMOTIONAL`, `OTP`, `MULTI_USE`. The primary use case for the RCS agent.
- `TRANSACTIONAL` — Order confirmations, shipping updates, appointment reminders.
- `PROMOTIONAL` — Marketing messages, offers, discounts.
- `OTP` — One-time passwords and verification codes.
- `MULTI_USE` — A combination of transactional, promotional, and/or OTP messaging.

Example:

```json
{
  "id": "agent_abc123def456",
  "type": "TEST",
  "serviceId": "acme-support_agent",
  "carrierLaunches": {
    "ATT": "NOT_LAUNCHED",
    "TMOBILE": "LAUNCHED",
    "VERIZON": "PENDING",
    "OTHERS": "NOT_LAUNCHED"
  },
  "details": {
    "name": "Acme Support",
    "description": "Get help with your Acme orders and account",
    "iconUrl": "https://example.com/logo.png",
    "heroUrl": "https://example.com/hero.png",
    "color": "#FF6B00",
    "phones": [
      {
        "phone": "+14155550123",
        "label": "Support"
      }
    ],
    "emails": [
      {
        "email": "support@example.com",
        "label": "Support"
      }
    ],
    "websites": [
      {
        "url": "https://example.com",
        "label": "Website"
      }
    ],
    "privacyUrl": "https://example.com/privacy",
    "termsUrl": "https://example.com/terms",
    "isConversational": true,
    "agentUseCase": "MULTI_USE"
  }
}
```

### 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."
}
```

### 403

Your subscription does not include access to this feature.

This occurs when attempting to use functionality that requires a higher subscription tier.
Please upgrade your subscription to access this feature.

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": "Your subscription does not include access to this feature."
}
```

### 404

The requested resource could not be found.

This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.

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": "The requested resource could not be found."
}
```

### 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.getAgent("agent_abc123def456");
```

### Python

```python
import os
from rcs import Pinnacle

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

client.rcs.get_agent(
    agent_id="agent_abc123def456",
)
```

### Ruby

```ruby
require "rcs"

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

client.rcs.get_agent(agent_id: "agent_abc123def456")
```

## Machine-readable schema

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