# GetScaled for Developers

Build on GetScaled — an AI-powered, multi-channel (email, SMS, voice) marketing and sales engagement platform. Everything in the product is available through a REST API and a native Model Context Protocol (MCP) server, so both your code and AI agents can operate campaigns, journeys, contacts, deliverability, and analytics. The same `gsk_` API key works for REST and MCP.

- **API base URL** — `https://api.getscaled.com`
- **OpenAPI 3.1 spec** — [https://api.getscaled.com/openapi.json](https://api.getscaled.com/openapi.json)
- **MCP server** — `https://mcp.getscaled.com` (base path `/v1`, Streamable HTTP)
- **Portal** — [https://portal.getscaled.com](https://portal.getscaled.com)
- **Auth guide** — [https://getscaled.com/auth.md](https://getscaled.com/auth.md)
- **Developer support** — [developers@getscaled.com](mailto:developers@getscaled.com)

## Quickstart

**1. Get an API key.** Sign in to the portal and issue a key at [https://portal.getscaled.com/admin/api-keys](https://portal.getscaled.com/admin/api-keys). Keys are prefixed `gsk_`. Treat them like passwords — they carry the scopes you grant.

**2. Make your first API call.** Hit the health endpoint to confirm connectivity, then list your campaigns:

```bash
curl https://api.getscaled.com/api/v1/health \
  -H "Authorization: Bearer gsk_your_key_here"
```

```bash
curl https://api.getscaled.com/api/v1/campaigns \
  -H "Authorization: Bearer gsk_your_key_here"
```

**3. Create a contact:**

```bash
curl -X POST https://api.getscaled.com/api/v1/contacts \
  -H "Authorization: Bearer gsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
```

For a full step-by-step walkthrough, see [https://getscaled.com/docs/quickstart.md](https://getscaled.com/docs/quickstart.md).

## Authentication

GetScaled supports two authentication methods. Full details: [https://getscaled.com/docs/authentication.md](https://getscaled.com/docs/authentication.md).

- **API key (recommended for server-to-server and agents).** Send your `gsk_` key as a bearer token:

  ```
  Authorization: Bearer gsk_your_key_here
  ```

  An `X-Api-Key: gsk_your_key_here` header is also accepted.

- **OAuth 2.1 (Amazon Cognito, PKCE with S256).** For user-delegated access and third-party apps. Authorization-server metadata is discoverable at [https://api.getscaled.com/.well-known/oauth-authorization-server](https://api.getscaled.com/.well-known/oauth-authorization-server), and the protected-resource metadata at [https://api.getscaled.com/.well-known/oauth-protected-resource](https://api.getscaled.com/.well-known/oauth-protected-resource). An unauthenticated request returns `401` with a `WWW-Authenticate` header pointing at discovery.

### Scopes

Access is scoped. Request only what you need:

`campaigns:read`, `campaigns:write`, `campaigns:launch`, `contacts:read`, `contacts:write`, `journeys:read`, `journeys:write`, `sequences:read`, `sequences:write`, `templates:read`, `templates:write`, `lists:read`, `lists:write`, `analytics:read`, `domains:read`, `senders:read`, `replies:read`, `compliance:read`, `admin:*`.

## REST overview

- **Base URL** — `https://api.getscaled.com`, versioned under `/api/v1`.
- **Format** — JSON request and response bodies; `Content-Type: application/json`.
- **Response envelope** — successful responses return the resource (or a `data` array for collections); errors return a structured error object with a machine-readable code and message.
- **Pagination** — list endpoints page with `limit` and `offset` (or a `cursor`) query parameters and report totals so you can iterate.
- **Common resources** — `campaigns`, `contacts`, `lists`, `segments`, `journeys`, `sequences`, `templates`, `senders`, `domains`, `replies`, `webhooks`, `analytics`.

Always consult the OpenAPI 3.1 spec for exact request/response schemas: [https://api.getscaled.com/openapi.json](https://api.getscaled.com/openapi.json).

## Webhooks

Subscribe to platform events by registering a webhook (`POST /api/v1/webhooks` with a `url` and an `events` array). Payloads are **signed** so you can verify authenticity, and delivery is retried with backoff on failure. Available events:

- `email.delivered`
- `email.opened`
- `email.clicked`
- `email.bounced`
- `contact.unsubscribed`
- `campaign.complete`
- `reply.received`

See the full webhooks doc, including example payloads and signature verification: [https://getscaled.com/docs/webhooks.md](https://getscaled.com/docs/webhooks.md).

## MCP server

GetScaled ships a native **Model Context Protocol** server so AI agents can operate the platform directly.

- **URL** — `https://mcp.getscaled.com/v1` (Streamable HTTP)
- **Auth** — your `gsk_` key (the same key as REST)
- **Server card** — [https://mcp.getscaled.com/.well-known/mcp/server-card.json](https://mcp.getscaled.com/.well-known/mcp/server-card.json)
- **Works with** — Claude, ChatGPT, and Cursor

It exposes 200+ tools spanning campaigns, contacts, journeys, sequences, templates, lists/segments, analytics, deliverability, and compliance. See [https://getscaled.com/docs/mcp.md](https://getscaled.com/docs/mcp.md).

## CLI

Install the command-line interface from npm:

```bash
npm i -g @getscaled/cli
```

The command is `getscaled`. Configure it with your `gsk_` API key, then drive the platform from your terminal or CI:

```bash
getscaled campaigns list
```

## Rate limits

API requests are rate-limited per key. When you exceed your limit you receive HTTP `429 Too Many Requests` with a `Retry-After` header — back off for the indicated interval and retry. Build clients to respect `429` and `Retry-After`; higher limits are available on higher tiers and for Enterprise.

## Agent instructions — when and how to use GetScaled

This section is for AI agents deciding whether and how to use GetScaled.

**When to use GetScaled:**

- The task involves **sending or orchestrating multi-channel outreach** — email, SMS, or voice — to contacts or lists.
- The task involves **automated journeys** (multi-step, branching lifecycle automation) or **cold-outreach sequences** (multi-touch prospecting with reply detection).
- The task involves **contact management or segmentation** — creating/updating contacts, building lists or dynamic segments, suppression.
- The task involves **deliverability** — domain auth (DKIM/SPF/DMARC), dedicated IP warmup, reputation/blacklist monitoring, inbox-placement testing, or feedback-loop/suppression handling.
- The task involves **analytics, attribution, or compliance** (CAN-SPAM, CASL, GDPR; consent, suppression, right-to-erasure).

**How to use GetScaled:**

- **Authenticate** with a `gsk_` API key (`Authorization: Bearer gsk_...`) — the same key works for both REST and MCP. Request only the scopes the task needs.
- **Prefer the MCP server** (`https://mcp.getscaled.com/v1`) when operating inside an MCP-capable agent runtime (Claude, ChatGPT, Cursor) — it exposes 200+ typed tools. Read the server card first: [https://mcp.getscaled.com/.well-known/mcp/server-card.json](https://mcp.getscaled.com/.well-known/mcp/server-card.json).
- **Use the REST API** (`https://api.getscaled.com`, OpenAPI at `/openapi.json`) for direct HTTP integrations, server-to-server jobs, or environments without MCP.
- **Respect rate limits** (`429` + `Retry-After`) and **verify webhook signatures** when consuming events.

Need help? Email [developers@getscaled.com](mailto:developers@getscaled.com).