Skip to content
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

Jump to bottom

API documentation for Surveys & Profile #761

Merged
merged 1 commit into from
Sep 1, 2023
Merged

API documentation for Surveys & Profile #761

Show file tree
Hide file tree
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
64 changes: 61 additions & 3 deletions apps/formbricks-com/app/docs/api/api-key-setup/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,69 @@ The API requests are authorized with a personal API key. This API key gives you
/>

<Note>
## Store API key safely
Anyone who has your API key has full control over your account. For security reasons, you cannot view the API
key again.
### Store API key safely
Anyone who has your API key has full control over your account.
For security reasons, you cannot view the API key again.
</Note>

### Test your API Key

Hit the below request to verify that you are authenticated with your API Key and the server is responding.

## Get My Profile {{ tag: 'GET', label: '/api/v1/me' }}

<Row>
<Col>

Get the product details and environment type of your account.

### Mandatory Headers

<Properties>
<Property name="x-Api-Key" type="string">
Your Formbricks API key.
</Property>
</Properties>

</Col>
<Col sticky>

<CodeGroup title="Request" tag="GET" label="/api/v1/me">

```bash {{ title: 'cURL' }}
curl --location \
'https://app.formbricks.com/api/v1/me' \
--header \
'x-api-key: <your-api-key>'
```

</CodeGroup>

<CodeGroup title="Response">

```json {{title:'200 Success'}}
{
"id": "cll2m30r70004mx0huqkitgqv",
"createdAt": "2023-08-08T18:04:59.922Z",
"updatedAt": "2023-08-08T18:04:59.922Z",
"type": "production",
"product": {
"id": "cll2m30r60003mx0hnemjfckr",
"name": "My Product"
},
"widgetSetupCompleted": false
}
```
```json {{ title: '401 Not Authenticated' }}
Not authenticated
```
</CodeGroup>

</Col>
</Row>

---

### Delete a personal API key

1. Go to settings on [app.formbricks.com](https://app.formbricks.com/).
Expand Down
10 changes: 5 additions & 5 deletions apps/formbricks-com/app/docs/api/overview/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
export const meta = {
title: "API Overview",
description:
"Explore Formbricks' APIs: Public Client API for client-side tasks, and User API for account management with secure API Key authentication.",
"Explore Formbricks' APIs: Public Client API for client-side tasks, and Management API for account management with secure API Key authentication.",
};

#### API

# API Overview

Formbricks offers two types of APIs: the **Public Client API** and the **User API**. Each API serves a different purpose, has different authentication requirements, and provides access to different data and settings.
Formbricks offers two types of APIs: the **Public Client API** and the **Management API**. Each API serves a different purpose, has different authentication requirements, and provides access to different data and settings.

## Public Client API

The Public Client API is designed for the JavaScript SDK and does not require authentication. It's primarily used for creating persons, sessions, and responses within the Formbricks platform. This API is ideal for client-side interactions, as it doesn't expose sensitive information.

## User API
## Management API

The User API provides access to all data and settings that are visible in the Formbricks App. This API requires a personal API Key for authentication, which can be generated in the Settings section of the Formbricks App. With the User API, you can manage your Formbricks account programmatically, accessing and modifying data and settings as needed.
The Management API provides access to all data and settings that are visible in the Formbricks App. This API requires a personal API Key for authentication, which can be generated in the Settings section of the Formbricks App. With the Management API, you can manage your Formbricks account programmatically, accessing and modifying data and settings as needed.

**Auth:** Personal API Key

API requests made to the User API are authorized using a personal API key. This key grants the same rights and access as if you were logged in at formbricks.com. It's essential to keep your API key secure and not share it with others.
API requests made to the Management API are authorized using a personal API key. This key grants the same rights and access as if you were logged in at formbricks.com. It's essential to keep your API key secure and not share it with others.

To generate, store, or delete an API key, follow the instructions provided on the following page [API Key](/docs/api/api-key-setup).

Expand Down
2 changes: 1 addition & 1 deletion apps/formbricks-com/app/docs/api/responses/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export const meta = {
"Explore the Formbricks Public Client API for client-side tasks and integration into your website.",
};

#### Client API
#### Management API

# Responses API

Expand Down
180 changes: 180 additions & 0 deletions apps/formbricks-com/app/docs/api/surveys/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,180 @@
import { Fence } from "@/components/shared/Fence";

export const meta = {
title: "Surveys API",
description:
"Explore the Formbricks Public Client API for client-side tasks and integration into your website.",
};

#### Management API

# Surveys API

The Survey API currently has one endpoint that allows you to get all the surveys you have in your Formbricks environment. You will need the [API Key](/docs/api/api-key-setup) to access the same!

---

## List all surveys {{ tag: 'GET', label: '/api/v1/surveys' }}

<Row>
<Col>

Retrieve all the surveys you have for the environment.

### Mandatory Headers

<Properties>
<Property name="x-Api-Key" type="string">
Your Formbricks API key.
</Property>
</Properties>

</Col>
<Col sticky>

<CodeGroup title="Request" tag="GET" label="/api/v1/surveys">

```bash {{ title: 'cURL' }}
curl --location \
'https://app.formbricks.com/api/v1/surveys' \
--header \
'x-api-key: <your-api-key>'
```

</CodeGroup>

<CodeGroup title="Response">

```json {{title:'200 Success'}}
{
"data": [
{
"id": "cllnfy2780fromy0hy7uoxvtn",
"createdAt": "2023-08-23T07:56:20.516Z",
"updatedAt": "2023-08-23T07:56:26.947Z",
"name": "Product Market Fit (Superhuman)",
"type": "link",
"environmentId": "cll2m30r70004mx0huqkitgqv",
"status": "inProgress",
"attributeFilters": [],
"displayOption": "displayOnce",
"autoClose": null,
"triggers": [],
"redirectUrl": null,
"recontactDays": null,
"questions": [
{
"id": "gml6mgy71efgtq8np3s9je5p",
"type": "cta",
"headline": "You are one of our power users! Do you have 5 minutes?",
"required": false,
"buttonLabel": "Happy to help!",
"logic": [
{
"condition": "skipped",
"destination": "end"
}
],
"html": "<p class=\"fb-editor-paragraph\" dir=\"ltr\"><span>We would love to understand your user experience better. Sharing your insight helps a lot!</span></p>",
"buttonExternal": false,
"dismissButtonLabel": "No, thanks."
},
{
"id": "kp62fbqe8cfzmvy8qwpr81b2",
"type": "multipleChoiceSingle",
"headline": "How disappointed would you be if you could no longer use My Product?",
"subheader": "Please select one of the following options:",
"required": true,
"choices": [
{
"id": "bdgy1hnwd7uwmfxk1ljqp1n5",
"label": "Not at all disappointed"
},
{
"id": "poabnvgtwenp8rb2v70gj4hj",
"label": "Somewhat disappointed"
},
{
"id": "opfiqyqz8wrqn0i0f7t24d3n",
"label": "Very disappointed"
}
],
"shuffleOption": "none"
},
{
"id": "klvpwd4x08x8quesihvw5l92",
"type": "multipleChoiceSingle",
"headline": "What is your role?",
"subheader": "Please select one of the following options:",
"required": true,
"choices": [
{
"id": "c8nerw6l9gpsxcmqkn10f9hy",
"label": "Founder"
},
{
"id": "ebjqezei6a2axtuq86cleetn",
"label": "Executive"
},
{
"id": "ctiijjblyhlp22snypfamqt1",
"label": "Product Manager"
},
{
"id": "ibalyr0mhemfkkr82vypmg40",
"label": "Product Owner"
},
{
"id": "fipk606aegslbd0e7yhc0xjx",
"label": "Software Engineer"
}
],
"shuffleOption": "none"
},
{
"id": "ryo75306flyg72iaeditbv51",
"type": "openText",
"headline": "What type of people do you think would most benefit from My Product?",
"required": true
},
{
"id": "lkjaxb73ulydzeumhd51sx9g",
"type": "openText",
"headline": "What is the main benefit your receive from My Product?",
"required": true
},
{
"id": "ec7agikkr58j8uonhioinkyk",
"type": "openText",
"headline": "How can we improve My Product for you?",
"subheader": "Please be as specific as possible.",
"required": true
}
],
"thankYouCard": {
"enabled": true,
"headline": "Thank you!",
"subheader": "We appreciate your feedback."
},
"delay": 0,
"autoComplete": null,
"closeOnDate": null
}
]
}
```
```json {{ title: '401 Not Authenticated' }}
{
"code": "not_authenticated",
"message": "Not authenticated",
"details": {
"x-Api-Key": "Header not provided or API Key invalid"
}
}
```
</CodeGroup>

</Col>
</Row>

---
1 change: 1 addition & 0 deletions apps/formbricks-com/components/docs/Navigation.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,7 @@ export const navigation: Array<NavGroup> = [
{ title: "Overview", href: "/docs/api/overview" },
{ title: "API Key Setup", href: "/docs/api/api-key-setup" },
{ title: "Responses", href: "/docs/api/responses" },
{ title: "Surveys", href: "/docs/api/surveys" },
{ title: "Webhook", href: "/docs/api/webhooks" },
],
},
Expand Down
Loading