Skip to content

Commit 49a63a1

Browse files
aerosolzoldar
aerosol
and
zoldar
authored
Document Sites API guests resource (#591)
* Document Sites API `guests` resource * !fixup * !fixup * Update index * Add docs on `GET /api/v1/sites/teams` and document `team_id` parameter * Prefer status: accepted/invited over bools --------- Co-authored-by: Adrian Gruntkowski <adrian.gruntkowski@gmail.com>
1 parent dd9a730 commit 49a63a1

File tree

1 file changed

+187
-1
lines changed

1 file changed

+187
-1
lines changed

‎docs/sites-api.md‎

Lines changed: 187 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {Required, Optional} from '../src/js/api-helpers.tsx';
77
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](https://plausible.io/white-label-web-analytics). The Site API allows these operations:
88

99
* List existing sites
10+
* List teams
1011
* Create a new site
1112
* Delete an existing site
1213
* Change a domain name
@@ -15,6 +16,9 @@ The Plausible Site provisioning API offers a way to create and manage sites in y
1516
* List existing goals
1617
* Find or create a goal by type and value (learn more about [goals and custom events](goal-conversions.md))
1718
* Delete an existing goal
19+
* List site guests/invitations
20+
* Create site guest invitations
21+
* Delete site guests/invitations
1822

1923
Each request must be authenticated with an API key using the Bearer Token method. Please [contact us](https://plausible.io/contact) to discuss your needs and to get an API key with permissions for the endpoints listed in this document.
2024

@@ -72,7 +76,69 @@ Pagination cursor. See [Pagination](#pagination).
7276

7377
Pagination limit. Defaults to 100. See [Pagination](#pagination).
7478

79+
**team_id** <Optional />
80+
81+
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.
82+
83+
<hr / >
84+
85+
### GET /api/v1/sites/teams
86+
87+
Gets a list of teams your Plausible account can access. The `api_available` attribute determines if the API is available for a given team.
88+
89+
```bash title="Try it yourself"
90+
curl -X GET https://plausible.io/api/v1/sites/teams \
91+
-H "Authorization: Bearer ${TOKEN}"
92+
```
93+
94+
```json title="Response 200 OK"
95+
{
96+
"teams": [
97+
{
98+
"id": "4d3dae3b-2a44-4aaa-baac-6bb55234a435",
99+
"name": "My Personal Sites",
100+
"api_available": false,
101+
},
102+
{
103+
"id": "ef828bca-8a1b-49f6-b829-dee1c9f7d628",
104+
"name": "Some Team",
105+
"api_available": true,
106+
},
107+
{
108+
"id": "59e4d5b3-fc1c-464d-95f2-dbe6983396be",
109+
"name": "Another Team",
110+
"api_available": true,
111+
}
112+
],
113+
"meta": {
114+
"after": null,
115+
"before": null,
116+
"limit": 100
117+
}
118+
}
119+
```
120+
121+
#### Query parameters
122+
<hr / >
123+
124+
**after** <Optional />
125+
126+
Pagination cursor. See [Pagination](#pagination).
127+
75128
<hr / >
129+
130+
**before** <Optional />
131+
132+
Pagination cursor. See [Pagination](#pagination).
133+
134+
<hr / >
135+
136+
**limit** <Optional />
137+
138+
Pagination limit. Defaults to 100. See [Pagination](#pagination).
139+
140+
<hr / >
141+
76142
### POST /api/v1/sites
77143

78144
Creates a site in your Plausible account.
@@ -104,6 +170,12 @@ Domain of the site to be created in Plausible. Must be a globally unique, the re
104170
Timezone name according to the [IANA](https://www.iana.org/time-zones) database. Defaults to `Etc/UTC` when left blank.
105171
<hr / >
106172

173+
**team_id** <Optional />
174+
175+
ID of the team under which the created site is to be put. Defaults to the ID of "My Personal Sites".
176+
177+
<hr / >
178+
107179
### PUT /api/v1/sites/:site_id
108180

109181
Update an existing site in your Plausible account. Note: currently only `domain` change is allowed.
@@ -131,7 +203,7 @@ Domain of the site to be created in Plausible. Must be a globally unique, the re
131203

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

134-
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.
206+
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.
135207
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.
136208

137209
```bash title="Try it yourself"
@@ -338,6 +410,120 @@ Id of your site in Plausible.
338410

339411
<hr / >
340412

413+
### GET /api/v1/sites/guests
414+
415+
Gets a list of guests for a given `site_id` (use the site domain as the ID).
416+
417+
```bash title="Try it yourself"
418+
curl -X GET https://plausible.io/api/v1/sites/guests?site_id=test-domain.com \
419+
-H "Authorization: Bearer ${TOKEN}"
420+
```
421+
422+
```json title="Response 200 OK"
423+
{
424+
"guests": [
425+
{
426+
"email": "alice@example.com",
427+
"role": "viewer",
428+
"status": "accepted"
429+
},
430+
{
431+
"email": "bob@example.com",
432+
"role": "editor",
433+
"status": "invited"
434+
}
435+
],
436+
"meta": {
437+
"after": null,
438+
"before": null,
439+
"limit": 100
440+
}
441+
}
442+
```
443+
444+
445+
#### Query parameters
446+
<hr / >
447+
448+
**site_id** <Required />
449+
450+
Id of your site in Plausible.
451+
452+
<hr / >
453+
454+
**after** <Optional />
455+
456+
Pagination cursor. See [Pagination](#pagination).
457+
458+
<hr / >
459+
460+
**before** <Optional />
461+
462+
Pagination cursor. See [Pagination](#pagination).
463+
464+
<hr / >
465+
466+
**limit** <Optional />
467+
468+
Pagination limit. Defaults to 100. See [Pagination](#pagination).
469+
470+
<hr / >
471+
472+
### PUT /api/v1/sites/guests
473+
474+
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.
475+
476+
477+
```bash title="Try it yourself"
478+
curl -X PUT https://plausible.io/api/v1/sites/guests \
479+
-H "Authorization: Bearer ${TOKEN}" \
480+
-F 'site_id="test-domain.com"' \
481+
-F 'role="viewer"' \
482+
-F 'email="alice@example.com"'
483+
```
484+
485+
```json title="Response 200 OK"
486+
{
487+
"email": "alice@example.com",
488+
"role": "viewer",
489+
"status": "invited"
490+
}
491+
```
492+
493+
#### Body parameters
494+
<hr / >
495+
496+
**site_id** <Required />
497+
498+
Id of your site in Plausible.
499+
500+
<hr / >
501+
502+
**email** <Required />
503+
504+
Guest's e-mail address.
505+
506+
**role** <Required />
507+
508+
Either `editor` or `viewer`.
509+
510+
<hr / >
511+
512+
### DELETE /api/v1/sites/guests/:email
513+
514+
Deletes an invitation or guest membership from the given site. Does not delete associated user account, if any.
515+
516+
```bash title="Try it yourself"
517+
curl -X DELETE https://plausible.io/api/v1/sites/guests/test@example.com \
518+
-H "Authorization: Bearer ${TOKEN}"
519+
```
520+
521+
```json title="Response 200 OK"
522+
{
523+
"deleted": "true"
524+
}
525+
```
526+
341527
## Pagination
342528
343529
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`:

0 commit comments

Comments
 (0)