Site provisioning API reference
The Plausible Site provisioning API offers a way to create and manage sites in your Plausible account programmatically. This is useful if you run many websites or if you're offering a web analytics dashboard powered by Plausible to your customers. The Site API allows these operations:
- List existing sites
- Create a new site
- Delete an existing site
- Change a domain name
- Get a site by domain
- Find or create a shared link by name (to use for the embed dashboard functionality)
- List existing goals
- Find or create a goal by type and value (learn more about goals and custom events)
- Delete an existing goal
Each request must be authenticated with an API key using the Bearer Token method. Please contact us to discuss your needs and to get an API key with permissions for the endpoints listed in this document.
Endpoints
GET /api/v1/sites
Gets a list of existing sites your Plausible account can access.
curl -X GET https://plausible.io/api/v1/sites \
-H "Authorization: Bearer ${TOKEN}"
{
"sites": [
{
"domain": "test-domain1.com",
"timezone": "Europe/London",
},
{
"domain": "test-domain2.com",
"timezone": "Europe/London",
},
{
"domain": "test-domain3.com",
"timezone": "Europe/London",
}
],
"meta": {
"after": null,
"before": null,
"limit": 100
}
}
Query parameters
after optional
Pagination cursor. See Pagination.
before optional
Pagination cursor. See Pagination.
limit optional
Pagination limit. Defaults to 100. See Pagination.
POST /api/v1/sites
Creates a site in your Plausible account.
curl -X POST https://plausible.io/api/v1/sites \
-H "Authorization: Bearer ${TOKEN}" \
-F 'domain="test-domain.com"' \
-F 'timezone="Europe/London"'
{
"domain": "test-domain.com",
"timezone": "Europe/London"
}
Post body parameters
domain REQUIRED
Domain of the site to be created in Plausible. Must be a globally unique, the request will fail if the domain is already taken.
timezone optional
Timezone name according to the IANA database. Defaults to Etc/UTC when left blank.
PUT /api/v1/sites/:site_id
Update an existing site in your Plausible account. Note: currently only domain change is allowed.
curl -X PUT https://plausible.io/api/v1/sites/test-domain.com \
-H "Authorization: Bearer ${TOKEN}" \
-F 'domain="new-test-domain.com"'
{
"domain": "new-test-domain.com",
"timezone": "Europe/London"
}
Post body parameters
domain REQUIRED
Domain of the site to be created in Plausible. Must be a globally unique, the request will fail if the domain is already taken.
DELETE /api/v1/sites/:site_id
Deletes a site from your Plausible account along with all it's data and configuration. The API key must belong to the owner of the site. Permanently deleting all your data may take up to 48 hours and you won't be able to immediately register the same site again until the process is complete.
curl -X DELETE https://plausible.io/api/v1/sites/test-domain.com \
-H "Authorization: Bearer ${TOKEN}"
{
"deleted": "true"
}
GET /api/v1/sites/:site_id
Gets details of a site. Your Plausible account must have access to it.
curl -X GET https://plausible.io/api/v1/sites/test-domain.com \
-H "Authorization: Bearer ${TOKEN}"
{
"domain": "test-domain.com",
"timezone": "Europe/London",
"custom_properties": ["logged_in"]
}
PUT /api/v1/sites/shared-links
Finds or creates a shared link for a given site_id (use the site domain as the ID). This endpoint is idempotent, it won't fail if a shared link with the provided name already exists.
curl -X PUT https://plausible.io/api/v1/sites/shared-links \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"' \
-F 'name="Wordpress"'
{
"name": "Wordpress",
"url": "https://plausible.io/share/site.com?auth=<random>"
}
Body parameters
site_id REQUIRED
Id of your site in Plausible.
name REQUIRED
Name of the shared link.
GET /api/v1/sites/goals
Gets a list of existing goals for a given site_id (use the site domain as the ID).
curl -X GET https://plausible.io/api/v1/sites/goals?site_id=test-domain.com \
-H "Authorization: Bearer ${TOKEN}"
{
"goals": [
{
"id": "1",
"goal_type": "event",
"display_name": "Signup",
"event_name": "Signup",
"page_path": null
},
{
"id": "2",
"goal_type": "page",
"display_name": "Visit /register",
"event_name": null,
"page_path": "/register"
}
],
"meta": {
"after": null,
"before": null,
"limit": 100
}
}
Query parameters
site_id REQUIRED
Id of your site in Plausible.
after optional
Pagination cursor. See Pagination.
before optional
Pagination cursor. See Pagination.
limit optional
Pagination limit. Defaults to 100. See Pagination.
PUT /api/v1/sites/goals
Finds or creates a goal for a given site_id (use the site domain as the ID). This endpoint is idempotent, it won't fail if a goal with the provided name already exists.
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"'
{
"domain": "test-domain.com",
"id": "1",
"display_name": "Signup",
"goal_type": "event",
"event_name": "Signup",
"page_path": null
}
Body parameters
site_id REQUIRED
Id of your site in Plausible.
goal_type REQUIRED
Type of your goal, accepts only one of the following values: event or page
event_name REQUIRED only if goal_type is set to event
Actual value of the event name of your goal
page_path REQUIRED only if goal_type is set to page
Actual value of the page path of your goal, also accepts wildcards for type page
display_name
The value under which the goal is available in the dashboard, as well as in the Stats API. If not provided, for custom events the display_name becomes event_name and Visit {page_path} in case of pageview goals.
DELETE /api/v1/sites/goals/:goal_id
Deletes a goal from your Plausible account. The API key must belong to the owner of the site. The site must owned by the current user.
curl -X DELETE https://plausible.io/api/v1/sites/goals/1 \
-H "Authorization: Bearer ${TOKEN}" \
-F 'site_id="test-domain.com"'
{
"deleted": "true"
}
Body parameters
site_id REQUIRED
Id of your site in Plausible.
Pagination
All list endpoints implement cursor based pagination. They accept following URL query parameters: before, after and limit. The response payload always contains pagination metadata under meta:
{
"sites": [...],
"meta": {
"after": "Z2xc...",
"before": null,
"limit": 100
}
}
After the initial request, previous and next pages can be retrieved by repeating the same request with either before or after query parameter passed over from the last response:
curl -X GET https://plausible.io/api/v1/sites?after=AFTER_VALUE_FROM_LAST_RESPONSE \
-H "Authorization: Bearer ${TOKEN}"
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.