Skip to content

Script v2: Update docs for sites API #628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Script v2: Update docs for sites API #628

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 117 additions & 25 deletions docs/sites-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ The Plausible Site provisioning API offers a way to create and manage sites in y
* Create a new site
* Delete an existing site
* Change a domain name
* Configure tracker script settings
* Get a site by domain
* Find or create a shared link by name (to use for the [embed dashboard functionality](embed-dashboard.md))
* List existing goals
Expand Down Expand Up @@ -154,18 +155,39 @@ Creates a site in your Plausible account.
```bash title="Try it yourself"
curl -X POST https://plausible.io/api/v1/sites \
-H "Authorization: Bearer ${TOKEN}" \
-F 'domain="test-domain.com"' \
-F 'timezone="Europe/London"'
-H "Content-Type: application/json" \
-d '{
"domain": "test-domain.com",
"timezone": "Europe/London",
"tracker_script_configuration": {
"file_downloads": true,
"form_submissions": true,
"outbound_links": true
}
}'
```

```json title="Response 200 OK"
{
"domain": "test-domain.com",
"timezone": "Europe/London"
"timezone": "Europe/London",
"custom_properties": [],
"tracker_script_configuration": {
"id": "pa-1iQepzD1J73BaHey2csUp",
"installation_type": null,
"track_404_pages": false,
"hash_based_routing": false,
"outbound_links": true,
"file_downloads": true,
"revenue_tracking": false,
"tagged_events": false,
"form_submissions": true,
"pageview_props": false
}
}
```

#### Post body parameters
#### Body parameters
<hr / >

**domain** <Required />
Expand All @@ -184,31 +206,62 @@ ID of the team under which the created site is to be put. Defaults to the ID of

<hr / >

**tracker_script_configuration** <Optional />

Configuration object for the tracker script for this site. When not provided, the default configuration is set. When provided or provided partially (all options are optional), allows you to customize tracking features (any option that is not specified is set to the default value). See [Tracker script configuration](#tracker-script-configuration).

<hr />

### PUT /api/v1/sites/:site_id

Update an existing site in your Plausible account. Note: currently only `domain` change is allowed.
Update an existing site in your Plausible account. You can change the domain name and/or update tracker script configuration.

```bash title="Try it yourself"
curl -X PUT https://plausible.io/api/v1/sites/test-domain.com \
-H "Authorization: Bearer ${TOKEN}" \
-F 'domain="new-test-domain.com"'
-H "Content-Type: application/json" \
-d '{
"domain": "new-test-domain.com",
"tracker_script_configuration": {
"form_submissions": true
}
}'
```

```json title="Response 200 OK"
{
"domain": "new-test-domain.com",
"timezone": "Europe/London"
"timezone": "Europe/London",
"custom_properties": [],
"tracker_script_configuration": {
"id": "pa-1iQepzD1J73BaHey2csUp",
"installation_type": null,
"track_404_pages": false,
"hash_based_routing": false,
"outbound_links": false,
"file_downloads": false,
"revenue_tracking": false,
"tagged_events": false,
"form_submissions": true,
"pageview_props": false
}
}
```

#### Post body parameters
#### Body parameters
<hr / >

**domain** <Required />
**domain** <Optional />

Domain of the site to be created in Plausible. Must be a globally unique, the request will fail if the domain is already taken.
<hr / >

**tracker_script_configuration** <Optional />

Configuration object for the tracker script for this site. When not provided, the current configuration is kept. When provided or provided partially, allows you to update settings for tracking features (any option that is not specified is kept at the current value). See [Tracker script configuration](#tracker-script-configuration).

<hr />

### DELETE /api/v1/sites/:site_id

Deletes a site from your Plausible account along with all its data and configuration. The API key must belong to the owner of the site.
Expand All @@ -227,7 +280,7 @@ curl -X DELETE https://plausible.io/api/v1/sites/test-domain.com \

### GET /api/v1/sites/:site_id

Gets details of a site. Your Plausible account must have access to it.
Gets details of a site. Your Plausible account must have access to it. The response includes the tracker script configuration for the site and its ID, which you can use to request the tracker script for this site. See [Tracker script URL](#tracker-script-url).

```bash title="Try it yourself"
curl -X GET https://plausible.io/api/v1/sites/test-domain.com \
Expand All @@ -238,7 +291,19 @@ curl -X GET https://plausible.io/api/v1/sites/test-domain.com \
{
"domain": "test-domain.com",
"timezone": "Europe/London",
"custom_properties": ["logged_in"]
"custom_properties": ["logged_in"],
"tracker_script_configuration": {
"id": "pa-1iQepzD1J73BaHey2csUp",
"installation_type": null,
"track_404_pages": false,
"hash_based_routing": false,
"outbound_links": false,
"file_downloads": false,
"revenue_tracking": false,
"tagged_events": false,
"form_submissions": false,
"pageview_props": false
}
}
```

Expand All @@ -250,9 +315,11 @@ Finds or creates a shared link for a given `site_id` (use the site domain as the
```bash title="Try it yourself"
curl -X PUT https://plausible.io/api/v1/sites/shared-links \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"' \
-F 'name="Wordpress"'
```
-H "Content-Type: application/json" \
-d '{
"site_id": "test-domain.com",
"name": "Wordpress"
}'

```json title="Response 200 OK"
{
Expand Down Expand Up @@ -346,10 +413,12 @@ Finds or creates a goal for a given `site_id` (use the site domain as the ID). T
```bash title="Try it yourself"
curl -X PUT https://plausible.io/api/v1/sites/goals \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"' \
-F 'goal_type="event"' \
-F 'event_name="Signup"'
```
-H "Content-Type: application/json" \
-d '{
"site_id": "test-domain.com",
"goal_type": "event",
"event_name": "Signup"
}'

```json title="Response 200 OK"
{
Expand Down Expand Up @@ -400,8 +469,10 @@ Deletes a goal from your Plausible account. The API key must belong to the owner
```bash title="Try it yourself"
curl -X DELETE https://plausible.io/api/v1/sites/goals/1 \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"'
```
-H "Content-Type: application/json" \
-d '{
"site_id": "test-domain.com"
}'

```json title="Response 200 OK"
{
Expand Down Expand Up @@ -484,11 +555,14 @@ For a given `site_id` (use the site domain as the ID), finds an invitation or ex

```bash title="Try it yourself"
curl -X PUT https://plausible.io/api/v1/sites/guests \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"' \
-F 'role="viewer"' \
-F 'email="[email protected]"'
```
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"site_id": "test-domain.com",
"role": "viewer",
"email": "[email protected]"
}'
```

```json title="Response 200 OK"
{
Expand Down Expand Up @@ -555,3 +629,21 @@ curl -X GET https://plausible.io/api/v1/sites?after=AFTER_VALUE_FROM_LAST_RESPON
```

The `limit` parameter must remain the same when paginating, either by leaving it at a default value or passing the same value each time explicitly. The `null` value in `before` or `after` means there are no more previous or next pages to navigate to, respectively.

## Tracker script configuration

This parameter is used to configure the tracker script for a site. It is a JSON object with the following parameters, all of which are optional.

- **installation_type**: Type of installation (`"wordpress"`, `"manual"`, `"gtm"`, `null`). Defaults to `null`.
- **track_404_pages**: Whether to track 404 page visits. Defaults to `false`.
- **hash_based_routing**: Whether to track hash-based routing changes. Defaults to `false`.
- **outbound_links**: Whether to track outbound link clicks. Defaults to `false`.
- **file_downloads**: Whether to track file downloads. Defaults to `false`.
- **revenue_tracking**: Whether to enable revenue tracking. Defaults to `false`.
- **tagged_events**: Whether to enable tagged events. Defaults to `false`.
- **form_submissions**: Whether to track form submissions. Defaults to `false`.
- **pageview_props**: Whether to enable pageview properties. Defaults to `false`.

### Tracker script URL

The resolved configuration is returned in GET/PUT/POST site endpoints response along with an ID. This ID can be used to request the tracker script for this site from the URL `https://plausible.io/js/{id}.js`.