# REST API

{% hint style="info" %}
If you're using an AI tool such as Cursor, ChatGPT Codex, or Claude Code to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/getting-started#mcp).
{% endhint %}

## Getting started

{% hint style="info" %}
**Note:** The REST API is available to the following types of programs (campaigns):

* **Referral programs:** Users on a GrowSurf paid subscription plan
* **Affiliate programs:** Users who have a valid payment method on file
  {% endhint %}

### Step 1: Get your API key

1. Go to your [GrowSurf Account](https://app.growsurf.com/settings#api-keys) page
2. Generate a new API key (if you don't already have one) or click on your existing API key to copy it to your clipboard

{% hint style="info" %}
Your API key holds many privileges, so be sure to keep it secure! Do not share your API key in publicly accessible areas such as GitHub, Bitbucket, Web Browsers, and Front End client code.
{% endhint %}

{% hint style="danger" %}
Do not use the RESTful API in browser applications. Exposing your secret API key within front end code exposes it to security risks. Anybody with a bit of programming knowledge could potentially hijack your API key and begin making requests on your behalf.
{% endhint %}

### Step 2: Set up authentication

The GrowSurf REST API uses your API key to authenticate requests. Here's how to set up authentication:

1. Set a plain text header named `Authorization` with the contents being **`Bearer <YOUR_API_ACCESS_KEY>`** where **`<YOUR_API_ACCESS_KEY>`** is your API key.

#### Example Authenticated Request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X "GET" "https://api.growsurf.com/v2/campaign/4pdlhb" -H "Authorization: Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E"
```

{% endtab %}

{% tab title="Java" %}

```java
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.growsurf.com/v2/campaign/4pdlhb")
  .get()
  .addHeader("Authorization", "Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E")
  .build();

Response response = client.newCall(request).execute();
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const request = require("request");

const options = { 
  method: 'GET',
  url: 'https://api.growsurf.com/v2/campaign/4pdlhb',
  headers: { 
    Authorization: 'Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E' 
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.growsurf.com/v2/campaign/4pdlhb"
headers = {
    'Authorization': "Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E"
    }
response = requests.request("GET", url, headers=headers)

print(response.text)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$request = new HttpRequest();
$request->setUrl('https://api.growsurf.com/v2/campaign/4pdlhb');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'Authorization' => 'Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
```

{% endtab %}

{% tab title="Go" %}

```go
package main

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

func main() {
	url := "https://api.growsurf.com/v2/campaign/4pdlhb"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer TWZ4X4NXESMX03MT66HHS6Z9Z91E")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(res)
	fmt.Println(string(body))

}
```

{% endtab %}
{% endtabs %}

## Base URL

All endpoints for the GrowSurf REST API start with the same base URL:

```
https://api.growsurf.com/v2
```

## **Next steps**

* [View Tutorials](/developer-tools/rest-api/tutorials.md)
* [View Objects](/developer-tools/rest-api/api-objects.md)
* [View API Reference](/developer-tools/rest-api/api-reference.md)

[![Run in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/growsurf/growsurf-public/collection/csnytdd/growsurf-rest-api)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.growsurf.com/developer-tools/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.