You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: advanced/rest-api/overview.mdx
+13-19Lines changed: 13 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,31 +2,28 @@
2
2
title: Overview
3
3
---
4
4
5
-
## Trigger Updates
6
-
7
-
Leverage the REST API to programmatically trigger an update when desired.
8
-
The primary use-case will be to trigger updates. We will be adding more and more
9
-
functionality to the API overtime. Let us know what else you want to see in
10
-
[our community](https://mintlify.com/community)!
11
-
12
5
## Authentication
13
6
14
-
You can generate an API key through
15
-
[the dashboard](https://dashboard.mintlify.com/settings/integrations). The API key is
16
-
associated with the entire org and can be used across multiple deployments.
7
+
Generate an API key through [the dashboard](https://dashboard.mintlify.com/settings/integrations). This key works across all deployments within your organization.
17
8
18
9
<Frame>
19
10
<imgsrc="/images/external-api-key.png" />
20
11
</Frame>
21
12
13
+
## Trigger Updates
14
+
15
+
Use our REST API to programmatically trigger documentation updates. Additional API functionality will be added based on user feedback. Share your suggestions in [our community](https://mintlify.com/community).
16
+
22
17
## Discovery API
23
18
24
-
The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
25
-
Responses include citations so you can point your users to the right places they need to get help.
19
+
The Discovery API enables AI-powered chat experiences within your documentation. Key features:
20
+
- Embedded chat interface for any application
21
+
- Responses include citations to source documentation
22
+
- Automatically stays synchronized with your content
26
23
27
-
##Getting Started
24
+
### Setup
28
25
29
-
To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
26
+
1. Generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
30
27
31
28
<Frame>
32
29
<img
@@ -36,10 +33,7 @@ To get started, you'll need to generate a Discovery API key in the [dashboard](h
36
33
</Frame>
37
34
38
35
<Note>
39
-
The Discovery API token is a public token that can be referenced in your
40
-
frontend code whereas the API key is a server-side token that should be kept
41
-
secret.
36
+
The Discovery API token is public and safe for frontend code. Keep the API key secure on your server side.
42
37
</Note>
43
38
44
-
Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use
45
-
the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).
39
+
2. See our [example implementation](https://github.com/mintlify/discovery-api-example) or view the [live demo](https://chat.mintlify.com).
Add the widget by adding these script tags into your site's `<head>...<head/>` tag.
16
+
### HTML Installation
17
+
Add these scripts to your site's `<head>` tag:
21
18
22
19
```html
23
20
<script>
@@ -40,7 +37,8 @@ Add the widget by adding these script tags into your site's `<head>...<head/>` t
40
37
</script>
41
38
```
42
39
43
-
To use the widget in React and Next.js apps, use the React component from the `@mintlify/widget-react`[package](https://www.npmjs.com/package/@mintlify/widget-react). Here is a basic example of how to use the component in your React application:
40
+
### React Installation
41
+
For React and Next.js apps, use our React component:
44
42
45
43
```jsx
46
44
<MintlifyWidget
@@ -50,73 +48,22 @@ To use the widget in React and Next.js apps, use the React component from the `@
50
48
/>
51
49
```
52
50
53
-
## Usage
54
-
55
-
In the first script tag or the React component props, you can customize the appearance and other settings of the widget. `mintlifyWidgetSettings` accepts the following props:
description: 'Generate docs pages for your API endpoints using MDX'
3
+
description: 'Configure API endpoints documentation using MDX'
4
4
---
5
5
6
-
Mintlify allows you to define your API endpoints using a combination of `mint.json` configuration, MDX metadata fields, and the `<ParamFields />` component. From the defined endpoints, we generate an API playground, request examples, and response examples.
6
+
Learn how to set up API documentation with MDX and generate an interactive API playground.
7
7
8
8
<Steps>
9
-
<Steptitle="Configure your API">
10
-
In your `mint.json` file, define your base URL and auth method:
9
+
<Steptitle="Configure API settings">
10
+
Add your API configuration to `mint.json`:
11
11
12
12
```json
13
13
{
14
14
"api": {
15
-
"baseUrl": "https://mintlify.com/api",// string array for multiple base URLs
15
+
"baseUrl": "https://mintlify.com/api",
16
16
"auth": {
17
-
"method": "bearer"// options: bearer, basic, key.
17
+
"method": "bearer"
18
18
}
19
19
}
20
20
}
21
21
```
22
22
23
-
If you would not like to show an API playground, you don't need to include auth types. Hide the playground with the following field:
23
+
To hide the API playground, use:
24
24
25
25
```json
26
26
{
@@ -31,13 +31,10 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
31
31
}
32
32
}
33
33
```
34
-
35
-
Find a full list of API configurations [here](/settings/global#api-configurations).
36
34
</Step>
37
35
38
-
<Steptitle="Create your endpoint pages">
39
-
40
-
Each API endpoint page should have a corresponding MDX file. At the top of each file, define:
36
+
<Steptitle="Create endpoint pages">
37
+
Create an MDX file for each endpoint with the following metadata:
41
38
42
39
```md
43
40
---
@@ -46,20 +43,17 @@ Mintlify allows you to define your API endpoints using a combination of `mint.js
46
43
---
47
44
```
48
45
49
-
You can specify path parameters by adding the parameter name to the path, wrapped with `{}`:
50
-
46
+
For paths with parameters, use `{parameterName}`:
51
47
```bash
52
48
https://api.example.com/v1/endpoint/{userId}
53
49
```
54
50
55
51
<Note>
56
-
57
-
If you have `baseUrl` configured in [mint.json](/settings/global), you can use relative paths like `/v1/endpoint`.
58
-
52
+
With `baseUrl` configured, you can use relative paths like `/v1/endpoint`
59
53
</Note>
60
54
</Step>
61
55
62
-
<Steptitle="Add your endpoints to your docs">
63
-
Add your endpoint pages to the sidebar by adding the paths to the `navigation` field in your `mint.json`. Learn more about structuring your docs [here](/settings/navigation).
56
+
<Steptitle="Add to navigation">
57
+
Add your endpoint pages to the `navigation` field in `mint.json` to display them in your sidebar.
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments