Skip to main content

​
OpenAPI Updater

This skill helps you add new API endpoints to an OpenAPI 3.0.3 specification and automatically update the associated Mintlify documentation structure.

​
When to use this skill

Use this skill when the user wants to:
  • Add new API endpoints to existing documentation
  • Update openapi.json with new paths and schemas
  • Create endpoint documentation files
  • Update navigation in docs.json
  • Add new enumerations or resources

​
Input format

The user will provide API documentation in various formats:
  • cURL examples with request/response examples
  • API specification fragments
  • Structured descriptions of endpoints
Your job is to extract the structured information needed for the OpenAPI spec.

​
Project structure assumptions

This skill assumes a Mintlify documentation project with this structure: 
project/
├── api-reference/
│   ├── openapi.json          # Main OpenAPI specification
│   ├── endpoints/            # Endpoint documentation (.md files)
│   │   ├── kya/
│   │   ├── kyt/
│   │   └── [category]/
│   └── resources/            # Enumerations and reference docs
│       └── enumerations.md
├── docs.json                  # Navigation configuration
└── skills/

​
Workflow

​
Step 1: Understand the API endpoints

First, gather this information for each new endpoint:
  • HTTP method: GET, POST, PUT, DELETE, PATCH
  • Path: e.g., /api/v1/tracker/address/blacklist
  • Summary: Short description
  • Parameters: Query parameters, headers
  • Request body: Structure for POST/PUT/PATCH
  • Responses: 200, 400, 401, etc. with examples
  • Tags: Which API group (e.g., “KYA”, “KYT”, “Address Management”)

​
Step 2: Update openapi.json

Read the existing api-reference/openapi.json and add:
  1. Add to tags if a new category is needed
  2. Add to paths the new endpoints with:
    • Method (get/post/put/delete/patch)
    • Summary and description
    • Parameters (query, header)
    • Request body (for non-GET requests)
    • Responses with examples
  3. Add to components/schemas any new schemas needed:
    • Request/response bodies
    • Nested objects
    • Enumerations
Important patterns:
  • Use $ref to reference existing schemas when possible
  • Follow existing naming conventions (PascalCase for schemas)
  • Include example fields in responses for documentation
  • Reuse common response types like BaseResponse, Error, Pagination
  • Reference shared schemas like Network, RiskType, RiskLevel

​
Step 3: Create endpoint documentation files

For each endpoint, create a .md file in api-reference/endpoints/[category]/: 
---
title: [Human-readable title]
openapi: '[METHOD] [path]'
---
Examples:
  • GET /api/v1/tracker/kya/entities → retrieve-entity.md
  • POST /api/v1/tracker/address/blacklist → add-blacklist-addresses.md
Naming convention: [verb]-[noun].md using lowercase with hyphens.

​
Step 4: Update docs.json navigation

Read docs.json and add the new endpoints to the appropriate group under the “API Reference” tab. Structure: 
{
  "group": "[Category Name]",
  "pages": [
    "api-reference/endpoints/[category]/[file-name]",
    ...
  ]
}
For nested groups (like Blacklist/Whitelist under Address Management): 
{
  "group": "Parent Category",
  "pages": [
    {
      "group": "Subcategory",
      "pages": ["path/to/file1", "path/to/file2"]
    }
  ]
}

​
Step 5: Update resources if needed

If the new endpoints introduce new enumerations or types, update api-reference/resources/enumerations.md. Add new sections following the existing format with tables showing:
  • Code/Name values
  • Descriptions in multiple languages (if applicable)

​
Field descriptions

When writing schema descriptions, be precise:
  • Timestamps: Use “A unix timestamp” (not milliseconds)
  • Optional fields: Mark with description but don’t use required: []
  • Array limits: Use maxItems with explanation
  • Defaults: Use default in parameter schemas

​
Error handling

Always include standard error responses:
  • 400: $ref: "#/components/responses/BadRequest"
  • 401: $ref: "#/components/responses/Unauthorized"
  • 429: $ref: "#/components/responses/RateLimit"
  • 500: $ref: "#/components/responses/InternalServerError"

​
Verification

After making changes:
  1. The JSON files should be valid (you can validate with python/json.tool)
  2. The structure should match existing patterns
  3. All new paths should be referenced in docs.json
  4. All schemas referenced should exist

​
Common schemas to reference

Before creating new schemas, check if these existing ones can be used:
  • BaseResponse - Standard response wrapper
  • Error - Error response structure
  • Network - Blockchain network enum
  • NetworkCore - Core networks (ethereum, eth, tron, btc, bsc)
  • RiskType - Risk category enum
  • RiskLevel - Risk level enum
  • Entity - Entity information
  • Risk - Risk assessment with riskLevel, riskType, riskSource
  • Pagination - Pagination metadata (current_page, per_page, total_pages, total_items)
  • AsyncTaskStatus - Async task status codes

​
Example workflow

When the user provides new API documentation:
  1. Parse the documentation to extract endpoints
  2. Read api-reference/openapi.json
  3. For each endpoint:
    • Add the path with method
    • Add schemas for request/response (reusing existing schemas when possible)
  4. Create endpoint .md files in appropriate category folder
  5. Update docs.json with navigation entries
  6. Update api-reference/resources/enumerations.md if new enums are added
Confirm with the user after each major step if they want to review the changes.