> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/rcs-agents/get-agent/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Get Agent

GET https://api.pinnacle.sh/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.


Reference: https://docs.pinnacle.sh/api-reference/rcs-agents/get-agent

## Authentication

- `PINNACLE-API-KEY` header (required) — API Key authentication via header

## Request

### Path parameters

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

## Response

### 200

The agent details.

- `id` (string, required) — The unique agent ID, prefixed with `agent_`.
- `type` (enum, required) — The agent type. - `TEST` — A test agent for development and testing with whitelisted numbers only.
  - Allowed values: `TEST`
- `serviceId` (string, required) — The RCS service ID assigned to this agent.
- `carrierLaunches` (CarrierLaunches, required) — Per-carrier launch status grouped by category. `carriers` covers AT&T / T-Mobile / Verizon / other carriers; `verification` covers the AEGIS and Google verification flows.
- `details` (RcsAgentDetails, required) — The configuration details of an RCS agent, as returned by the GET endpoint.

## Errors

### 400 Bad Request Error

Validation failed. The payload has missing required fields and/or invalid types.  See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information.

- `description` (string, required) — Human-readable summary of validation failures.
- `errors` (ZodErrorErrors, required) — 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

### 401 Unauthorized Error

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.

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

### 403 Forbidden Error

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.

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

### 404 Not Found Error

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.

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

### 500 Internal Server Error

An unexpected error occurred on Pinnacle's servers while processing your request.  If this error persists, please contact support with the request details.

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

## Types

### 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.

- `carriers` (CarrierLaunchesCarriers, required) — 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`.
- `verification` (CarrierLaunchesVerification, required) — 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.

### RcsAgentDetails

The configuration details of an RCS agent, as returned by the GET endpoint.

- `name` (string, optional) — Display name of the agent.
- `description` (string, optional) — Description of the agent.
- `iconUrl` (string, optional, nullable) — URL to the agent's logo image.
- `heroUrl` (string, optional, nullable) — URL to the agent's hero banner image.
- `color` (string, optional) — The agent's brand color hex code.
- `phones` (list of RcsAgentDetailsPhonesItems, optional) — Contact phone numbers for the agent.
- `emails` (list of RcsAgentDetailsEmailsItems, optional) — Contact email addresses for the agent.
- `websites` (list of RcsAgentDetailsWebsitesItems, optional) — Website links for the agent.
- `privacyUrl` (string, optional, nullable) — URL to the agent's privacy policy.
- `termsUrl` (string, optional, nullable) — URL to the agent's terms and conditions.
- `isConversational` (boolean, optional, nullable) — Whether the agent supports two-way conversations. `true` for agents that respond to user messages, `false` for send-only agents (e.g., notifications).
- `agentUseCase` (enum, optional, nullable) — 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.
  - Allowed values: `TRANSACTIONAL`, `PROMOTIONAL`, `OTP`, `MULTI_USE`

### ZodErrorErrors

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

### CarrierLaunchesCarriers

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`.

- `ATT` (enum, required) — AT&T launch status.
  - Allowed values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`
- `TMOBILE` (enum, required) — T-Mobile launch status.
  - Allowed values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`
- `VERIZON` (enum, required) — Verizon launch status.
  - Allowed values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`
- `OTHERS` (enum, required) — Other carriers launch status.
  - Allowed values: `NOT_LAUNCHED`, `PENDING`, `LAUNCHED`

### CarrierLaunchesVerification

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.

- `AEGIS` (enum, required) — AEGIS verification status.
  - Allowed values: `NOT_SENT`, `SENT`, `VERIFIED`
- `GOOGLE` (enum, required) — Google verification status.
  - Allowed values: `NOT_SENT`, `SENT`, `VERIFIED`

### RcsAgentDetailsPhonesItems

- `phone` (string, optional) — Phone number in E.164 format.
- `label` (string, optional) — Display label for the phone number.

### RcsAgentDetailsEmailsItems

- `email` (string, optional) — Email address.
- `label` (string, optional) — Display label for the email.

### RcsAgentDetailsWebsitesItems

- `url` (string, optional) — Website URL.
- `label` (string, optional) — Display label for the website.

## Examples

**Response**

```json
{
  "id": "agent_abc123def456",
  "type": "TEST",
  "serviceId": "acme-support_agent",
  "carrierLaunches": {
    "carriers": {
      "ATT": "NOT_LAUNCHED",
      "TMOBILE": "NOT_LAUNCHED",
      "VERIZON": "NOT_LAUNCHED",
      "OTHERS": "NOT_LAUNCHED"
    },
    "verification": {
      "AEGIS": "NOT_SENT",
      "GOOGLE": "NOT_SENT"
    }
  },
  "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"
  }
}
```

**SDK Code**

```python Test Agent
import requests

url = "https://api.pinnacle.sh/rcs/agent_abc123def456"

headers = {"PINNACLE-API-KEY": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Test Agent
const url = 'https://api.pinnacle.sh/rcs/agent_abc123def456';
const options = {method: 'GET', headers: {'PINNACLE-API-KEY': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Test Agent
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinnacle.sh/rcs/agent_abc123def456"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("PINNACLE-API-KEY", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Test Agent
require 'uri'
require 'net/http'

url = URI("https://api.pinnacle.sh/rcs/agent_abc123def456")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["PINNACLE-API-KEY"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Test Agent
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.pinnacle.sh/rcs/agent_abc123def456")
  .header("PINNACLE-API-KEY", "<apiKey>")
  .asString();
```

```php Test Agent
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.pinnacle.sh/rcs/agent_abc123def456', [
  'headers' => [
    'PINNACLE-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Test Agent
using RestSharp;

var client = new RestClient("https://api.pinnacle.sh/rcs/agent_abc123def456");
var request = new RestRequest(Method.GET);
request.AddHeader("PINNACLE-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Test Agent
import Foundation

let headers = ["PINNACLE-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/rcs/agent_abc123def456")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.