> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitrace.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Add new API endpoints to OpenAPI specifications and update Mintlify documentation structure. Use this skill whenever the user wants to add new APIs to their documentation, update OpenAPI specs, create new endpoint documentation files, or add API navigation entries. This includes tasks like "add these new endpoints to the API docs", "update the OpenAPI spec with new endpoints", "add API documentation for these endpoints", or "create docs for new API endpoints".

# SKILL

# 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]/`:

```markdown theme={null}
---
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:**

```json theme={null}
{
  "group": "[Category Name]",
  "pages": [
    "api-reference/endpoints/[category]/[file-name]",
    ...
  ]
}
```

For nested groups (like Blacklist/Whitelist under Address Management):

```json theme={null}
{
  "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.