Skip to main content

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:

  • 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)
  • 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​

POST /api/v1/sites​

Creates a site in your Plausible account.

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"'
Response 200 OK
{
    "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.

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"'
Response 200 OK
{
    "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.

Try it yourself
curl -X DELETE https://plausible.io/api/v1/sites/test-domain.com \
  -H "Authorization: Bearer ${TOKEN}"
Response 200 OK
{
    "deleted": "true"
}

GET /api/v1/sites/:site_id​

Gets a site from your Plausible account. The API key must belong to the owner of the site.

Try it yourself
curl -X GET https://plausible.io/api/v1/sites/test-domain.com \
  -H "Authorization: Bearer ${TOKEN}"
Response 200 OK
{
    "domain": "test-domain.com",
    "timezone": "Europe/London"
}

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.

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"'
Response 200 OK
{
    "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.

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.

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"'
Response 200 OK
{
    "domain": "test-domain.com",
    "id": "1",
    "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

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.

Try it yourself
curl -X DELETE https://plausible.io/api/v1/sites/goals/1 \
  -H "Authorization: Bearer ${TOKEN}" \
  -F 'site_id="test-domain.com"'
Response 200 OK
{
    "deleted": "true"
}

Body parameters​

site_id REQUIRED

Id of your site in Plausible.