Welcome to the developer integration guide! Whether you are managing inventory for a plant store or automating documentation updates using our AI endpoints, our public APIs provide the flexible tools you need to build powerful integrations.
This guide will walk you through the first steps of authenticating, understanding our data models, and making your first successful API request.
Authentication
All of our public API endpoints require authentication to ensure your data remains secure. We use standard HTTP Bearer authentication.
Never commit your API tokens to version control. Always use environment variables or a secure secrets manager to store your credentials.
When making a request, you must include your API key in the Authorization header of your HTTP request:
Authorization: Bearer YOUR_API_KEYMaking Your First Request
To help you get started safely, we provide a sandbox environment (http://sandbox.mintlify.com). Let's walk through fetching a list of items using the Plant Store API as an example.
- 1
Set up your request
Prepare your HTTP client to make a
GETrequest to the/plantsendpoint. You can optionally include alimitquery parameter to control how many results are returned. - 2
Add your headers
Attach your Bearer token to the request headers.
- 3
Execute the call
Run the following cURL command in your terminal to see the API in action:
curl -X GET "http://sandbox.mintlify.com/plants?limit=10" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json"
Understanding the API Flow
Here is a quick look at how your application interacts with our API when retrieving data:
sequenceDiagram
participant App as Your Application
participant API as Public API
App->>API: GET /plants?limit=10 (Bearer Token)
alt Successful Request
API-->>App: 200 OK (Returns Array of Plants)
else Invalid Request / Error
API-->>App: 400 Bad Request (Returns Error Schema)
endDeleting Data
You can remove an existing plant by making a DELETE request to the /plants/{id} endpoint.
curl -X DELETE "http://sandbox.mintlify.com/plants/123"
-H "Authorization: Bearer YOUR_API_KEY"A successful deletion will return a 204 status code. If the request is invalid, it will return a 400 status with the standard Error schema.
Core Data Models
When you interact with our endpoints, you'll frequently send and receive structured JSON data. Understanding the core schemas will help you parse responses correctly.
Here is an overview of the primary schemas used in the Plant API:
| Schema | Description | Required Fields | Properties |
|---|---|---|---|
| Plant | Represents an existing plant in the system. | name | name (string), tag (string) |
| NewPlant | Used when creating a new plant via POST /plants. | name, id | Inherits Plant, adds id (int64) |
| Error | Standardized error format returned on a 400 status. | error, message | error (int32 code), message (string) |
Handling Errors: Always check for a 400 status code. If an error occurs, the API will return the Error schema containing a specific error code and a human-readable message to help you debug.
Webhooks
If you want your application to react in real-time, you can utilize our webhook integrations. For example, you can configure a webhook endpoint (POST /plant/webhook) to receive a payload whenever a new plant is added to the store.
When you receive a webhook payload, your server should return a 200 status code to acknowledge that the data was received successfully.
Explore More APIs
Beyond the Plant Store sandbox, we offer extensive APIs for Documentation Management and AI-powered content generation (such as /documentation/{org_id}/{doc_id}/ai/edit).
Ready to dive deeper? Choose a topic below to continue your integration journey: