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
List teams
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
List site guests/invitations
Create site guest invitations
Delete site guests/invitations

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.

Try it yourself
curl -X GET https://plausible.io/api/v1/sites \
  -H "Authorization: Bearer ${TOKEN}"

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

team_id optional

ID of the team to scope the list of sites by. All sites including the ones accessible via guest membership are listed when no ID provided.

GET /api/v1/sites/teams

Gets a list of teams your Plausible account can access. The api_available attribute determines if the API is available for a given team.

Try it yourself
curl -X GET https://plausible.io/api/v1/sites/teams \
  -H "Authorization: Bearer ${TOKEN}"

Response 200 OK
{
    "teams": [
        {
            "id": "4d3dae3b-2a44-4aaa-baac-6bb55234a435",
            "name": "My Personal Sites",
            "api_available": false,
        },
        {
            "id": "ef828bca-8a1b-49f6-b829-dee1c9f7d628",
            "name": "Some Team",
            "api_available": true,
        },
        {
            "id": "59e4d5b3-fc1c-464d-95f2-dbe6983396be",
            "name": "Another Team",
            "api_available": true,
        }
    ],
    "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.

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.

team_id optional

ID of the team under which the created site is to be put. Defaults to the ID of "My Personal Sites".

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 its 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 details of a site. Your Plausible account must have access to it.

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",
    "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.

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.

GET /api/v1/sites/goals

Gets a list of existing goals for a given site_id (use the site domain as the ID).

Try it yourself
curl -X GET https://plausible.io/api/v1/sites/goals?site_id=test-domain.com \
  -H "Authorization: Bearer ${TOKEN}"

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

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",
    "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.

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.

GET /api/v1/sites/guests

Gets a list of guests for a given site_id (use the site domain as the ID).

Try it yourself
curl -X GET https://plausible.io/api/v1/sites/guests?site_id=test-domain.com \
         -H "Authorization: Bearer ${TOKEN}"

Response 200 OK
{
    "guests": [
        {
            "email": "alice@example.com",
            "role": "viewer",
            "status": "accepted"
        },
        {
            "email": "bob@example.com",
            "role": "editor",
            "status": "invited"
        }
    ],
    "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/guests

For a given site_id (use the site domain as the ID), finds an invitation or existing guest membership or sends a new invitation to a given email. This endpoint is idempotent, it won't fail if guest/invitation with the provided e-mail already exists.

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="alice@example.com"'

Response 200 OK
{
    "email": "alice@example.com",
    "role": "viewer",
    "status": "invited"
}

Body parameters

site_id REQUIRED

Id of your site in Plausible.

email REQUIRED

Guest's e-mail address.

role REQUIRED

Either editor or viewer.

DELETE /api/v1/sites/guests/:email

Deletes an invitation or guest membership from the given site. Does not delete associated user account, if any.

Try it yourself
curl -X DELETE https://plausible.io/api/v1/sites/guests/test@example.com \
         -H "Authorization: Bearer ${TOKEN}"

Response 200 OK
{
    "deleted": "true"
}

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:

Example list response
{
  "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:

Try it yourself
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.

Endpoints​

GET /api/v1/sites​

Query parameters​

GET /api/v1/sites/teams​

Query parameters​

POST /api/v1/sites​

Post body parameters​

PUT /api/v1/sites/:site_id​

Post body parameters​

DELETE /api/v1/sites/:site_id​

GET /api/v1/sites/:site_id​

PUT /api/v1/sites/shared-links​

Body parameters​

GET /api/v1/sites/goals​

Query parameters​

PUT /api/v1/sites/goals​

Body parameters​

DELETE /api/v1/sites/goals/:goal_id​

Body parameters​

GET /api/v1/sites/guests​

Query parameters​

PUT /api/v1/sites/guests​

Body parameters​

DELETE /api/v1/sites/guests/:email​

Pagination​

Endpoints

GET /api/v1/sites

Query parameters

GET /api/v1/sites/teams

Query parameters

POST /api/v1/sites

Post body parameters

PUT /api/v1/sites/:site_id

Post body parameters

DELETE /api/v1/sites/:site_id

GET /api/v1/sites/:site_id

PUT /api/v1/sites/shared-links

Body parameters

GET /api/v1/sites/goals

Query parameters

PUT /api/v1/sites/goals

Body parameters

DELETE /api/v1/sites/goals/:goal_id

Body parameters

GET /api/v1/sites/guests

Query parameters

PUT /api/v1/sites/guests

Body parameters

DELETE /api/v1/sites/guests/:email

Pagination