> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://gtm-tools.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server.

# Quickstart

> Two paths to get up and running with GTM Tools: programmatic signup for agents, or a terminal walkthrough for humans.

Two paths, pick the one that matches who's reading. **For Agents** if your AI assistant is doing the signup. **For Humans** if you're poking around in a terminal.

## For Agents

For agents that sign themselves up programmatically, with no console or dashboard needed.

#### Sign up

Call `get_api_key` with the user's email. A 6-digit verification code is sent to that address.

**`cURL`**

```bash title="cURL"
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

**`CLI`**

```bash title="CLI"
gtm-tools admin auth user@example.com
```

#### Verify with the code

Re-call the same endpoint with the code from the inbox. The response returns the bearer token.

**`cURL`**

```bash title="cURL"
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "code": "123456"}'
# → { "api_key": "sk_..." }
```

**`CLI`**

```bash title="CLI"
gtm-tools admin auth user@example.com --code 123456
```

#### Wire MCP and call a tool

With the key in hand, the fastest path is the `mcp add` CLI, which patches Claude Desktop, Cursor, or Windsurf in place.

```bash
npx gtm-tools@latest mcp add --client cursor --with-api-key sk_...
# Drop --with-api-key to use OAuth on first connect.
```

Then ask the agent to call any tool, e.g. `get_linkedin_company_url` for `siena.cx`.

> **Note**
>
> New accounts get **100 free credits** (\$1 = 100 credits, paid top-ups start at \$5). Live credit costs per tool are returned by `get_credit_balance`.

## For Humans

For developers who want to try GTM Tools from a terminal.

#### Get an API key

API keys are issued after email verification. New accounts get **100 free credits**.

#### REST

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_api_key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'
```

#### CLI

```bash
npm install -g @gtm-tools/cli
gtm-tools admin auth you@yourcompany.com
```

#### MCP

Wire the MCP client first (see [Agent Onboarding](/integrations/agent-onboarding)), then ask your agent to call `get_api_key` with your email.

A 6-digit code is sent to the address you provided. Re-call `get_api_key` with `{"email": "...", "code": "123456"}` (or `gtm-tools admin auth ... --code 123456`) and the response returns your bearer token.

#### Store your API key

```bash
export GTM_TOOLS_API_KEY="sk_..."
```

#### Get your credit balance

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_credit_balance \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{
  "balance": 100,
  "tools": {
    "get_linkedin_company_url": { "cost": 2 },
    "get_linkedin_profile_url": { "cost": 5 },
    "list_linkedin_company_employees": { "cost": 30 },
    "get_email": { "cost": 5 },
    "detect_signal": { "cost": 0 }
  }
}
```

`detect_signal` is free (0 credits) but the individual signals it dispatches are 5 credits each. That's how the all-in-one runner is metered.

#### Call your first tool

Get a company's LinkedIn URL from its domain.

#### REST

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_linkedin_company_url \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "siena.cx"}'
```

#### CLI

```bash
gtm-tools socials company-url siena.cx
```

#### TypeScript

```typescript
const res = await fetch(
  "https://api.gtm-tools.sh/api/v0/get_linkedin_company_url",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.GTM_TOOLS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ domain: "siena.cx" }),
  }
);
const data = await res.json();
```

```json
{
  "url": "https://www.linkedin.com/company/siena-cx",
  "domain": "siena.cx"
}
```

That call cost **2 credits**, so your balance is now 98.

#### Search the company's employees

Use boolean title filters to narrow the result. `AND`, `OR`, and `NOT` are supported, and parentheses group expressions.

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/list_linkedin_company_employees \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "gorgias.com",
    "title_filters": "(CEO OR CTO OR Founder) NOT intern",
    "limit": 10,
    "page": 1
  }'
```

This single call costs **30 credits**. `list_linkedin_company_employees` is the most expensive LinkedIn tool because it runs a paginated, filtered crawl. See [Credit Efficiency](/credit-efficiency) for tips on minimizing spend.

#### Try other categories

Verify a professional email:

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/get_email \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Justin Mares", "domain": "kettleandfire.com"}'
```

Run every signal detector at once:

```bash
curl -X POST https://api.gtm-tools.sh/api/v0/detect_signal \
  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "gymshark.com"}'
```

`detect_signal` runs every detector (hiring, Trustpilot, social spikes, tech stack) and returns the union of fired signals. The dispatch is free; only the individual detectors that ran are charged.

#### Wire MCP into your client

The fastest way to give an AI agent ongoing access is the remote MCP endpoint.

```bash
npx gtm-tools@latest mcp add --client claude-desktop
# or: --client cursor / --client windsurf
# Append `--with-api-key $GTM_TOOLS_API_KEY` to skip the OAuth flow.
```

For other clients (Codex, Goose, OpenClaw, Hermes Agent, NanoClaw, Raycast, VS Code, Cline, …) see the [Connect](/connect) page.

## Copy for Cursor / Claude

A drop-in TypeScript helper to give an agent as a starting point:

```typescript
const KEY = process.env.GTM_TOOLS_API_KEY!;

async function call<T>(tool: string, body: unknown = {}): Promise<T> {
  const res = await fetch(`https://api.gtm-tools.sh/api/v0/${tool}`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${tool}: ${res.status} ${await res.text()}`);
  return res.json();
}

// Domain → LinkedIn URL → decision-makers → verified emails
const { url } = await call<{ url: string }>("get_linkedin_company_url", { domain: "siena.cx" });
const employees = await call<any>("list_linkedin_company_employees", {
  domain: "siena.cx",
  title_filters: "(CEO OR CTO OR Founder) NOT intern",
  limit: 5,
});
for (const e of employees.results) {
  const { email } = await call<any>("get_email", { name: e.name, domain: "siena.cx" });
  console.log(e.name, "→", email);
}
```

## Next steps

#### [Agent Onboarding](/integrations/agent-onboarding)

Wire MCP into Cursor, Windsurf, and other clients.

#### [Outbound](/outbound)

A complete prospecting workflow: domain → decision-maker → email → outreach.

#### [Signals Tools](/signals-tools)

Every signal detector explained.

#### [API Reference](/api-reference)

Every tool with interactive request and response examples.