API Insights
What is API Insights?
API Insights is an advanced API governance tool that evaluates your APIs against industry best practices.
You just need to upload your OpenAPI spec (JSON or YAML) to get a score (1-100) and grade (A-F) in design, security, and performance.
Step to Setup API Insights
You can use API Insights in several ways, depending on your preference. You can access it via:
- Web Browser
- VS Code Extension
- CLI Tool
- Using the MacOS app
Setup via Web Browser (Dashboard)
You can access API Insights through apiinsights.io/.

Example: Analysing a demo API
This report analyzes the Demo API, which has 33 endpoints.

The dashboard is organized into different categories to help you quickly analyze key metrics:
- Design Insights
- Performance Insights
- Security Insights
How Do We Calculate This?
We combine your OpenAPI Spec and the data we get from a single request to your server. We run a series of checks and compare them to industry standards and best practices.
For example:
- Design Issues are identified based on predefined API design best practices.
- Performance metrics are calculated based on each request’s response times and server performance.
- Security checks identify common vulnerabilities and attack patterns, such as IDOR and missing security headers.
Setup via VS Code Extension
The API Insights VS Code Extension lets you observe your API performance directly from your development environment.
Installation
To install the API Insights VS Code Extension:
- Open VS Code and go to the Extensions view (
Ctrl+Shift+X
). - Search for Treblle API Insights.
- Click Install.

Getting Started
- You can begin the process once you have your OpenAPI spec file (usually in JSON or YAML format) in your workspace.
- Open the file in VS Code.
- The extension will automatically check the file and provide insights based on the API’s design, performance, and security.

Re-check the Score on File Changes
The extension tracks any changes made to the file. If you modify the OpenAPI spec file, it will automatically re-check and update the score.
When a file change is detected, a prompt will appear in your editor, reminding you to re-check the score.

Setup via CLI Tool
You can use the API Insights CLI tool if you prefer working in the terminal.
Installing Treblle CLI
You can install the Treblle CLI using Homebrew
on Mac or Linux:
brew tap treblle/trebllebrew install treblle
Using API Insights with CLI
Once installed, use the insights command to generate a report for your API by uploading your OpenAPI specification:
treblle-cli insights path/to/openapi-spec.json
By default, this will give you an overview of your API’s performance, design, and security scores. You can also pass additional flags for detailed analysis.
Available Options
-
Technology Profile: To see the technology profile discovered on your API, use the
--technology
flag:Terminal window treblle-cli insights path/to/openapi-spec.json --Technology -
Details: For a deep dive into specific categories, use the
--details
flag with one of the following options:Terminal window --details=performance to show performance test results.--details=security to display security test results.--details=quality for quality checks.Example:
Terminal window treblle-cli insights path/to/openapi-spec.json --details=All -
Minimum Score Limit: Using the
--minimum
flag, set a minimum score threshold for automated testing in CI/CD environments. For example, to require a minimum score of90
:Terminal window treblle-cli insights path/to/openapi-spec.json --minimum 90
Setup via Using the MacOS App

Visit the App Store and download the macOS app.
The app works like the browser version with the same insights and features in a more convenient desktop interface.
AI Readiness for your API
We’ve introduced the AI-Ready badge as part of Treblle’s commitment to smoother API integration with AI and LLMs.
We award this badge when your API meets key criteria for AI integration.

What Makes an API AI-Ready?
You receive the AI-Ready badge when your API adheres to the following specifications:
-
Endpoints Descriptions: Each endpoint has a detailed and user-friendly description.
Example: GET
/users
Description: Fetches a list of all users in the system. Useful for retrieving user information for management or reporting
-
Operation IDs: Each endpoint must have a distinct OperationID.
Example:
createUser
,deleteOrder
, orgetOrderDetails
. -
Parameters Descriptions: Every parameter should clearly describe usage, expected data type, and input format.
Example: Query Parameters for
GET /users
.page
(integer): Page number for paginated results. Default:1
.limit
(integer): Number of users per page. Default:10
.
Path Parameters for
GET /users/{id}
.id
(string): Unique identifier of the user.
-
Response Descriptions: All responses must have HTTP status codes and descriptions.
Example Responses for GET /users:
- 200 OK: Successfully retrieved the list of users.
- 400 Bad Request: Invalid query parameter(s) provided.
- 500 Internal Server Error: Unexpected server error occurred.
Example 200 Response:
Terminal window {{"users": [{ "id": "123", "name": "John Doe", "email": "john@example.com" },{ "id": "124", "name": "Jane Doe", "email": "jane@example.com" }]} -
Schemas: A schema must have a defined type and description if a schema exists.
Example:
Terminal window {"type": "object","properties": {"id": { "type": "string", "description": "Unique identifier for the user" },"name": { "type": "string", "description": "Full name of the user" },"email": { "type": "string", "description": "Email address of the user" }}}
So, when you meet these requirements, your API will automatically receive an AI-Ready badge.