### Example Output Directory Structure

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-review-openapi-batched.md

This example shows the typical directory structure and file names generated after running the batched OpenAPI review for the 'session' API.

```bash
reviewed-docs/2025-10-07-Claude-4-5-Sonnet-Cursor/session/
├── session-documentation-review.md
├── session-openapi.json
└── session-api-code-files.json
```

--------------------------------

### Clone Repository

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/openapi-gen-intro.md

Clone the openapi-gen-tester repository to get started. Navigate into the cloned directory to run commands.

```bash
git clone https://github.com/vtex/openapi-gen-tester.git
cd openapi-gen-tester
```

--------------------------------

### VTEX OpenAPI Schema Structure Example

Source: https://context7.com/vtex/openapi-schemas/llms.txt

An example of a VTEX OpenAPI schema file demonstrating the standard structure, including info, servers, security, paths, and components.

```APIDOC
## OpenAPI Schema File Structure

Each VTEX OpenAPI schema file follows a standard structure. Use this as a template when contributing new schemas.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "My VTEX API",
    "description": "Overview text with index of all endpoints...",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://{accountName}.{environment}.com.br",
      "description": "VTEX server URL.",
      "variables": {
        "accountName": { "default": "apiexamples", "description": "..." },
        "environment": { "default": "vtexcommercestable", "enum": ["vtexcommercestable"] }
      }
    }
  ],
  "security": [ 
    { "appKey": [], "appToken": [] },
    { "VtexIdclientAutCookie": [] }
  ],
  "paths": {
    "/api/myapi/pvt/resource/{resourceId}": {
      "get": {
        "tags": ["Resource"],
        "summary": "Get resource",
        "description": "Retrieves a resource by ID.\n\n## Permissions\n\n...",
        "operationId": "GetResource",
        "parameters": [
          { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Content-Type" },
          { "$ref": "#/components/parameters/Accept" }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey" },
      "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken" },
      "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie" }
    },
    "parameters": {
      "Content-Type": { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } },
      "Accept": { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "default": "application/json" } }
    },
    "schemas": {
      "Resource": { "type": "object", "properties": { "id": { "type": "string" } } }
    }
  }
}
```
```

--------------------------------

### Adding a New API Schema - Step-by-Step Guide

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Follow these steps to add a new API schema, including local validation and configuration updates.

```bash
# 1. Create the schema file following the naming convention
cp "templates/VTEX - Template openAPI.jsonc" "VTEX - My New API.json"

# 2. Edit the file: set info.title, info.description, servers, paths, components

# 3. Validate locally with Spectral (requires Node.js + @stoplight/spectral-cli)
npx @stoplight/spectral-cli lint "VTEX - My New API.json" --ruleset .spectral.yml

# 4. Add to config.json (maps the new API to its source repo)
# {
#   "repo": { "organization": "vtex", "codebase_name": "my-new-api-repo" },
#   "documentation": "VTEX - My New API.json"
# }

# 5. Open a PR — GitHub Actions will auto-lint the schema and post results,
#    and convert it to a Postman Collection in PostmanCollections/

# 6. Add the API display name → URL slug mapping to the Developer Portal's
#    api-slug-mapping.ts for consistent routing:
# fileSlugMap.set("My New API", "my-new-api")
```

--------------------------------

### OpenAPI Description Field Example

Source: https://github.com/vtex/openapi-schemas/blob/master/templates/Template - API Reference Overview.md

Example of how to include markdown descriptions within the `description` field of an OpenAPI JSON file. Remember to escape markdown characters.

```json
"openapi": "3.0.0",
    "info": {
        "title": "Antifraud Provider",
        "description": "{{Add your description here}}",
        "contact": {},
        "version": "1.0"
    }
```

--------------------------------

### Run Prism Validation

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-run-prism-validation.md

The basic command to start Prism validation for an OpenAPI file. This command finds the OpenAPI file, starts a mock server, tests endpoints, generates a report, and cleans up.

```bash
/run-prism-validation VTEX - License Manager API.json
```

--------------------------------

### Example Configuration Structure

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/analyzing-pr-changes-openapi.md

The `config.json` file maps repository names to their corresponding OpenAPI schema files. This configuration is crucial for the analysis tool to locate the correct schema.

```json
{
  "codebases": [
    {
      "name": "session",
      "documentation": "VTEX - Session Manager API.json"
    }
  ],
  "output": {
    "pr-changes-output": "pr-changes-suggestions/{yyyy-mm-dd}-{model_name}-Cursor/{repository}/"
  }
}
```

--------------------------------

### Scenario 1: Testing a New API

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-run-prism-validation.md

Command to validate a newly generated OpenAPI specification. Expects a moderate success rate and common issues like missing examples.

```bash
/run-prism-validation VTEX - New API.json
```

--------------------------------

### Common API Parameters Table

Source: https://github.com/vtex/openapi-schemas/blob/master/templates/Template - API Reference Overview.md

Example table outlining common parameters used in API references, including account name, environment, and authentication headers.

```markdown
| Parameter name |
| - | - | - |
| `{{accountName}}` | Name of the VTEX account. Used as part of the URL. | Server variable. |
| `{{environment}` | Environment to use. Used as part of the URL. The default value is `vtexcommercestable`. | Server variable. |
| `X-VTEX-API-AppKey` | Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys). | Authentication header. Must be used together with `X-VTEX-API-AppToken`. Not necessary when using `VtexIdclientAutCookie`. |
| `X-VTEX-API-AppToken` | Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys). | Authentication header. Must be used together with `X-VTEX-API-AppKey`. Not necessary when using `VtexIdclientAutCookie`. |
| `VtexIdclientAutCookie` | [User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours. | Authentication header. Not necessary when using `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken`. |
```

--------------------------------

### Create a Product in VTEX Catalog API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Example of creating a new product using the Catalog API. Requires authentication headers and a JSON payload with product details. The response includes the newly created product's ID.

```bash
# Create a product
curl -X POST "https://apiexamples.vtexcommercestable.com.br/api/catalog/pvt/product" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{ 
    "Name": "Lightweight Jacket",
    "CategoryId": 12,
    "BrandId": 2000001,
    "RefId": "JACKET-001",
    "IsVisible": true,
    "Description": "A breathable lightweight jacket for all seasons.",
    "IsActive": true,
    "TaxCode": "",
    "MetaTagDescription": "Lightweight jacket for everyday use",
    "ShowWithoutStock": true
  }'

# Response: 200 OK
# { "Id": 1, "Name": "Lightweight Jacket", "CategoryId": 12, ... }
```

--------------------------------

### Multi-Repository API Configuration Example

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/generating-openapi.md

This JSON configuration shows how to define multiple repositories for a single API. The command will clone and analyze all listed repositories, merging their endpoints into a single OpenAPI schema.

```json
{
  "repo": [
    {
      "organization": "vtex",
      "codebase_name": "newtail-retail-media-api"
    },
    {
      "organization": "vtex",
      "codebase_name": "newtail-retail-media-adserver-api"
    }
  ],
  "documentation": "VTEX - Ads API.json"
}
```

--------------------------------

### Configure Context7 MCP Server

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/spectral-linting.md

This JSON configuration file automatically sets up the Context7 MCP server within Cursor. Ensure the repository is cloned and opened in Cursor for automatic setup.

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "env": {}
    }
  }
}
```

--------------------------------

### Create a SKU for a Product in VTEX Catalog API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Example of creating a Stock Keeping Unit (SKU) for an existing product using the Catalog API. Requires authentication and a JSON payload with SKU-specific details like dimensions and weight.

```bash
# Create a SKU for the product
curl -X POST "https://apiexamples.vtexcommercestable.com.br/api/catalog/pvt/stockkeepingunit" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{ 
    "ProductId": 1,
    "Name": "Lightweight Jacket - Medium Blue",
    "RefId": "JACKET-001-M-BLU",
    "IsActive": true,
    "Height": 10,
    "Length": 30,
    "Width": 20,
    "WeightKg": 0.5
  }'
```

--------------------------------

### Example Output File Structure

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/analyzing-pr-changes-openapi.md

Files generated by the analysis command are saved in a structured directory. This includes the detailed analysis report and the updated OpenAPI schema if modifications were needed.

```bash
pr-changes-suggestions/2025-10-07-Claude-4-Sonnet-Cursor/session/
├── session-pr-135-analysis.md
└── session-openapi.json
```

--------------------------------

### Get Autocomplete Suggestions

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve search term suggestions based on a partial query. Specify the query and locale.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/autocomplete_suggestions?query=runn&locale=en-US&count=10" \
  -H "Accept: application/json"
```

--------------------------------

### Get API keys from account

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves a list of all API keys associated with the account.

```APIDOC
## GET /api/vlm/appkeys

### Description
Retrieves a list of API keys associated with the account.

### Method
GET

### Endpoint
/api/vlm/appkeys
```

--------------------------------

### Get Specific Promotion by ID

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve details of a single promotion using its unique ID. Requires AppKey and AppToken.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/rnb/pvt/calculatorconfiguration/{idCalculatorConfiguration}" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Get stores

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves a list of stores associated with the VTEX account.

```APIDOC
## GET /api/vlm/account/stores

### Description
Retrieves a list of stores associated with the account.

### Method
GET

### Endpoint
/api/vlm/account/stores
```

--------------------------------

### Get Specific Order

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves details for a specific order using its ID. Requires authentication with AppKey and AppToken.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/oms/pvt/orders/1172452900788-01" \
  -H "Accept: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Start New Payments Gateway Transaction

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Initiate a new financial transaction. This is the first step in processing a payment and requires basic transaction details.

```bash
curl -X POST "https://apiexamples.vtexpayments.com.br/api/pvt/transactions" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{
    "value": 9900,
    "referenceId": "1172452900788-01",
    "savePersonalData": false,
    "optinNewsLetter": false,
    "merchantName": "apiexamples",
    "merchantSettings": []
  }'
```

--------------------------------

### Example of Markdown Escaping in API Overview

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/best-practices-for-tech-writers-when-generating-schemas.md

Demonstrates the correct use of single backslash escaping for newlines in the API overview's description field. This ensures proper rendering of markdown content.

```json
"\r\n- ``POST`` [Create order modifications](https://developers.vtex.com/docs/api-reference/orders-api#/patch-/api/order-system/orders/-changeOrderId-/changes)"
```

--------------------------------

### Checkout API - Get or Create Cart

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves the current shopping cart or creates a new one if none exists.

```APIDOC
## GET /api/checkout/pub/orderForm

### Description
Retrieves the current shopping cart (orderForm) or creates a new one if no active cart is found. The response includes an orderFormId that should be used in subsequent calls.

### Method
GET

### Endpoint
/api/checkout/pub/orderForm
```

--------------------------------

### Get Available Facets for a Query/Category

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve the available facets (e.g., brand, price range) for a given category or search query. Specify the category/query and locale.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/facets/category-1?query=shoes&locale=en-US" \
  -H "Accept: application/json"
```

--------------------------------

### API Slug Mapping with TypeScript Map

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/centralized-api-slug-mapping.md

This example demonstrates how API display names are mapped to URL-friendly slugs using a TypeScript `Map`. This is the central mechanism for ensuring consistent API referencing.

```typescript
// Example from api-slug-mapping.ts
export const fileSlugMap = new Map<string, string>([
  ["Antifraud Provider", "antifraud-provider-api"],
  ["Catalog API", "catalog-api"],
  ["Checkout API", "checkout-api"],
  // ... other mappings
]);
```

--------------------------------

### Get Product and SKU IDs by Category in VTEX Catalog API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves product and SKU IDs associated with a specific category. Supports pagination with `_from` and `_to` parameters, with a maximum of 250 items per request. Requires authentication.

```bash
# Get product and SKU IDs by category (paginated, max 250 per request)
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/catalog_system/pvt/products/GetProductAndSkuIds?categoryId=12&_from=1&_to=50" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Get all available roles using License Manager API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve a list of all available roles within your VTEX account. This is useful for understanding permissions when creating new app keys.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/license-manager/pvt/roles" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Run Prism Validation Command

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/best-practices-for-tech-writers-when-generating-schemas.md

Execute automated validation using Prism to verify that the OpenAPI schema works correctly. This command requires Node.js to be installed.

```bash
/run-prism-validation {openapi-file-path}
```

--------------------------------

### Spectral Linting Results Example

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/spectral-linting.md

This markdown output shows the results of a Spectral linting attempt, including the number of issues found, specific errors, fixes applied, and the final pass rate. It illustrates the iterative process of scanning, fixing, and re-validating.

```markdown
## 🔍 SPECTRAL LINT RESULTS

### Attempt 1/3 - Initial Scan:
- **Errors**: 10
- **Warnings**: 12
- **Info**: 3
- **Total Issues**: 25

### Issues Found:
#### ❌ ERROR: `must-end-descriptions-with-period`
**Location**: Line 1775 (exact line number in file)
**Issue**: Description doesn't end with period
**Fix**: Add missing period to description

### Fixes Applied (Attempt 1):

✅ Fixed empty descriptions (10) at lines 45, 67, 89...
✅ Fixed missing property descriptions (8) at lines 123, 156...

### Attempt 2/3 - Re-scan After Fixes:

- **Errors**: 2 (remaining)
- **Warnings**: 0 (remaining)
- **Total Issues**: 2 (remaining)

### Attempt 3/3 - Final Fixes:

✅ Fixed remaining issues at lines 234, 456

### Final Results:

- **Initial Issues**: 25
- **Final Issues**: 0
- **Issues Fixed**: 25
- **Pass Rate**: 100%
- **Attempts Used**: 3/3

✅ SPECTRAL PASSED - All issues resolved!
```

--------------------------------

### Get a product suggestion from a seller using Marketplace API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves a product suggestion from a specific seller based on their SKU ID. This is part of managing seller offers in the marketplace.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/suggestions/pvt/skuseller/{sellerId}/{sellerSkuId}" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### List All Promotions

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve a list of all active promotions and calculator configurations. Requires AppKey and AppToken.

```bash
curl -X GET "https://apiexamples.vtexcomcommercestable.com.br/api/rnb/pvt/benefits/calculatorconfiguration" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Get information about account

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves general information about the VTEX account.

```APIDOC
## GET /api/vlm/account

### Description
Retrieves information about the account.

### Method
GET

### Endpoint
/api/vlm/account
```

--------------------------------

### Create a Coupon

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Generate a new coupon with specified parameters like UTM source, campaign, code, quantity, and usage limits. Requires AppKey and AppToken.

```bash
curl -X POST "https://apiexamples.vtexcommercestable.com.br/api/rnb/pvt/coupon" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{
    "utmSource": "newsletter",
    "utmCampaign": "spring2024",
    "couponCode": "SPRING20",
    "isArchived": false,
    "maxItemsPerClient": 1,
    "expirationInteractionLimit": null,
    "quantity": 500
  }'
```

--------------------------------

### Get All Roles

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves a list of all available roles within the VTEX account.

```APIDOC
## GET /api/license-manager/pvt/roles

### Description
Retrieves all available roles in the account.

### Method
GET

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/license-manager/pvt/roles

### Headers
- X-VTEX-API-AppKey: {appKey}
- X-VTEX-API-AppToken: {appToken}
```

--------------------------------

### Get list of users

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves a paginated list of all users associated with the account.

```APIDOC
## GET /api/license-manager/site/pvt/logins/list/paged

### Description
Retrieves a paginated list of users.

### Method
GET

### Endpoint
/api/license-manager/site/pvt/logins/list/paged
```

--------------------------------

### Get Session Data

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves current session data using the session token.

```APIDOC
## GET /api/sessions

### Description
Retrieves current session data. Pass the session token in the `VtexSession` cookie.

### Method
GET

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/sessions

### Query Parameters
- **items** (string) - Required - A comma-separated list of session items to retrieve (e.g., "profile.id,profile.email,store.channel,authentication.storeUserEmail").

### Headers
- Cookie: VtexSession={sessionToken}
```

--------------------------------

### Orders API - Get Order

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves the details of a specific order using its ID.

```APIDOC
## GET /api/oms/pvt/orders/{orderId}

### Description
Retrieves the detailed information for a specific order using its unique identifier.

### Method
GET

### Endpoint
/api/oms/pvt/orders/{orderId}

### Parameters
#### Path Parameters
- **orderId** (string) - Required - The unique identifier of the order.

#### Headers
- **X-VTEX-API-AppKey** (string) - Required - Your VTEX API App Key.
- **X-VTEX-API-AppToken** (string) - Required - Your VTEX API App Token.
```

--------------------------------

### Search Products with Facets and Filters

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Perform product searches using keywords, category, brand, pagination, sorting, and locale. Requires AppKey and AppToken.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/product_search/category-1/brand-nike?query=running+shoes&page=1&count=20&sort=price_asc&locale=en-US" \
  -H "Accept: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Get Category Tree

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves the category tree structure, supporting up to 4 levels deep.

```APIDOC
## GET /api/catalog_system/pub/category/tree/{depth}

### Description
Retrieves the category tree structure up to a specified depth.

### Method
GET

### Endpoint
/api/catalog_system/pub/category/tree/{depth}

### Parameters
#### Path Parameters
- **depth** (integer) - Required - The maximum depth of the category tree to retrieve.
```

--------------------------------

### Generate Multiple Specific APIs

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/generating-openapi.md

Generate documentation for multiple APIs by listing their codebase names as comma-separated parameters. This allows for targeted documentation generation.

```bash
/generate-openapi b2b-bulk-import, audience-manager
```

--------------------------------

### Get list of roles

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves a paginated list of all available roles within the License Manager.

```APIDOC
## GET /api/license-manager/site/pvt/roles/list/paged

### Description
Retrieves a paginated list of all available roles.

### Method
GET

### Endpoint
/api/license-manager/site/pvt/roles/list/paged
```

--------------------------------

### Execute Review All APIs

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/reviewing-openapi.md

Run the command without parameters to review all codebases configured in config.json that have a non-empty 'name' value. This process clones repositories, loads OpenAPI schemas, analyzes code, and generates reports.

```bash
/review-openapi
```

--------------------------------

### Get Seller Product Suggestion

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves a product suggestion from a specific seller for a given seller SKU.

```APIDOC
## GET /api/suggestions/pvt/skuseller/{sellerId}/{sellerSkuId}

### Description
Gets a product suggestion from a seller based on their SKU.

### Method
GET

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/suggestions/pvt/skuseller/{sellerId}/{sellerSkuId}

### Path Parameters
- **sellerId** (string) - Required - The ID of the seller.
- **sellerSkuId** (string) - Required - The SKU ID from the seller.

### Headers
- X-VTEX-API-AppKey: {appKey}
- X-VTEX-API-AppToken: {appToken}
```

--------------------------------

### Get Sent Offer Status

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves the status of a sent offer using its feed ID and offer ID.

```APIDOC
## GET /api/sent-offers/feeds/{feedId}/offers/{offerId}

### Description
Gets the status of a sent offer.

### Method
GET

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/sent-offers/feeds/{feedId}/offers/{offerId}

### Path Parameters
- **feedId** (string) - Required - The ID of the feed.
- **offerId** (string) - Required - The ID of the offer.

### Headers
- X-VTEX-API-AppKey: {appKey}
- X-VTEX-API-AppToken: {appToken}
```

--------------------------------

### Execute Review Specific APIs (Multiple)

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/reviewing-openapi.md

Review multiple specific APIs by listing their codebase names as comma-separated parameters. Spaces around the commas are optional. Codebase names must exactly match the 'name' field in config.json.

```bash
/review-openapi vcs.sku-binding, organization-units
```

```bash
/review-openapi session, audience-manager, license-manager
```

```bash
/review-openapi vcs.sku-binding,organization-units,session
```

--------------------------------

### Create Session

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Creates a new shopper session and initializes namespace data.

```APIDOC
## POST /api/sessions

### Description
Creates a new shopper session and initializes namespace data. The response sets the `VtexSession` cookie for subsequent requests.

### Method
POST

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/sessions

### Headers
- Content-Type: application/json

### Request Body
- **public** (object) - Required - Public data for the session.
  - **country** (object) - Required - Country information.
    - **value** (string) - Required - Country code (e.g., "BRA").
  - **postalCode** (object) - Required - Postal code information.
    - **value** (string) - Required - Postal code (e.g., "22251-040").

### Request Example
```json
{
  "public": {
    "country": { "value": "BRA" },
    "postalCode": { "value": "22251-040" }
  }
}
```
```

--------------------------------

### Get roles by user ID or API Key

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves the roles assigned to a specific user or API key.

```APIDOC
## GET /api/license-manager/users/{userId}/roles

### Description
Retrieves the roles associated with a user or API Key.

### Method
GET

### Endpoint
/api/license-manager/users/{userId}/roles

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user or API Key whose roles are to be retrieved.
```

--------------------------------

### Generate Specific API

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/generating-openapi.md

To generate documentation for a single API, provide its codebase name as a parameter to the command. The command will then focus only on the specified API.

```bash
/generate-openapi vcs.sku-binding
```

--------------------------------

### Create user

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Creates a new user within the VTEX License Manager.

```APIDOC
## POST /api/license-manager/users

### Description
Creates a new user in the License Manager.

### Method
POST

### Endpoint
/api/license-manager/users

### Request Body
- **user** (object) - Required - User details.
  - **name** (string) - Required - The name of the user.
  - **email** (string) - Required - The email address of the user.
  - **password** (string) - Required - The password for the user.
```

--------------------------------

### Get Category Tree

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieves the category tree structure up to a specified depth. Ensure the Accept header is set to application/json.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/catalog_system/pub/category/tree/3" \
  -H "Accept: application/json"
```

--------------------------------

### Generate All APIs

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/generating-openapi.md

Execute the command without parameters to process all codebases listed in `config.json` that have a `name` value. This includes cloning repositories, analyzing code, generating OpenAPI schemas with embedded overviews, and saving outputs.

```bash
/generate-openapi
```

--------------------------------

### Create App Key

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Creates a new application key for authentication with VTEX APIs.

```APIDOC
## POST /api/license-manager/pvt/apps/keys

### Description
Creates a new application key with specified roles.

### Method
POST

### Endpoint
https://apiexamples.vtexcommercestable.com.br/api/license-manager/pvt/apps/keys

### Headers
- Content-Type: application/json
- X-VTEX-API-AppKey: {appKey}
- X-VTEX-API-AppToken: {appToken}

### Request Body
- **keyName** (string) - Required - The name for the new app key.
- **roles** (array of strings) - Required - A list of role IDs to associate with the app key.

### Request Example
```json
{
  "keyName": "integration-erp",
  "roles": ["5a6d20d6-05da-11e7-b3e5-0ac0b30f5b84"]
}
```
```

--------------------------------

### Get user information by user ID

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves detailed information about a specific user identified by their unique user ID.

```APIDOC
## GET /api/license-manager/users/{userId}

### Description
Retrieves information for a specific user by their ID.

### Method
GET

### Endpoint
/api/license-manager/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.
```

--------------------------------

### Get Spelling Correction for a Misspelled Term

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Obtain spelling suggestions for a potentially misspelled search query. Requires the query and locale.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/correction_search?query=runing+shoez&locale=en-US" \
  -H "Accept: application/json"
```

--------------------------------

### Create a new app key using License Manager API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Use this endpoint to create a new application key for accessing VTEX APIs. Ensure you provide a unique key name and the necessary role IDs.

```bash
curl -X POST "https://apiexamples.vtexcommercestable.com.br/api/license-manager/pvt/apps/keys" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{
    "keyName": "integration-erp",
    "roles": ["5a6d20d6-05da-11e7-b3e5-0ac0b30f5b84"]
  }'
```

--------------------------------

### Get user information by user email

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/license-manager.md

Retrieves user information, including their roles, based on the user's email address.

```APIDOC
## GET /api/license-manager/users/{userEmail}/roles

### Description
Retrieves user information and their associated roles using the user's email.

### Method
GET

### Endpoint
/api/license-manager/users/{userEmail}/roles

### Parameters
#### Path Parameters
- **userEmail** (string) - Required - The email address of the user.
```

--------------------------------

### AI-Powered Documentation Workflow (Cursor IDE)

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Commands for using Cursor IDE to generate, review, rate, and lint OpenAPI schemas, driven by a `config.json` file.

```APIDOC
## AI-Powered Documentation Workflow (Cursor IDE)

VTEX technical writers use Cursor IDE commands to generate, review, rate, and lint OpenAPI schemas from source code. All commands are driven by `config.json`, which maps each API to its source repository.

```bash
# config.json structure — maps APIs to source repos and output paths
# {
#   "codebases": [
#     {
#       "repo": { "organization": "vtex", "codebase_name": "orders" },
#       "documentation": "VTEX - Orders API.json"
#     }
#   ],
#   "output": {
#     "generate-openapi-output": {
#       "directory": "generated-docs/{{yyyy-mm-dd}}-{{model_name}}-Cursor/{{codebase_name}}",
#       "openapi_filename": "generated-docs/.../{{codebase_name}}-openapi.json"
#     }
#   }
# }

# In Cursor IDE chat:

# Generate OpenAPI for a single API from source code
/generate-openapi orders

# Generate multiple APIs at once
/generate-openapi b2b-bulk-import, audience-manager, session

# Review existing schema against current code (identify gaps/outdated docs)
/review-openapi vcs.checkout

# Analyze a GitHub PR for API changes and suggest schema updates
/analyze-pr-changes-openapi https://github.com/vtex/orders/pull/1234

# Rate schema quality (outputs scored report: 0–100 across 7 weighted criteria)
/rate-openapi
# Scoring: endpoints_coverage (25%), spectral_compliance (25%),
#          parameters_completeness (15%), request_bodies_accuracy (15%),
#          response_schemas_accuracy (15%), schema_components (2%), metadata (3%)

# Run Spectral linting on a schema file (auto-fixes and re-validates)
/spectral "VTEX - Orders API.json"
/spectral generated-docs/2025-05-01-Claude-4-Sonnet-Cursor/orders/orders-openapi.json
```
```

--------------------------------

### VTEX API Authentication Methods

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Demonstrates two methods for authenticating with VTEX APIs: API Key + Token for machine-to-machine integration and User Token for user-context requests. Ensure correct header values are used for each method.

```bash
# Method 1: API Key + Token (machine-to-machine)
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/oms/pvt/orders/1172452900788-01" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: vtexappkey-mystore-XXXXXXXX" \
  -H "X-VTEX-API-AppToken: TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT"

# Method 2: User Token (browser/user context)
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/oms/pvt/orders/1172452900788-01" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "VtexIdclientAutCookie: eyJhbGciOiJFUzI1NiIsImtpZCI6..."
```

--------------------------------

### Get Top 10 Searched Terms

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Retrieve a list of the most frequent search terms, useful for popular searches widgets. Specify the locale.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/top_searches?locale=en-US" \
  -H "Accept: application/json"
```

--------------------------------

### Create or Get Cart

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Creates a new shopping cart or retrieves the current active cart. The response includes an orderFormId for subsequent operations.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/checkout/pub/orderForm" \
  -H "Accept: application/json"
```

--------------------------------

### Execute OpenAPI Analysis Command

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/analyzing-pr-changes-openapi.md

Use this command in Cursor with the GitHub pull request URL to initiate the analysis. Ensure the repository has a matching entry in `config.json`.

```bash
/analyze-pr-changes-openapi https://github.com/vtex/{repository-name}/pull/{pr-number}
```

```bash
/analyze-pr-changes-openapi https://github.com/vtex/session/pull/135
```

--------------------------------

### Send Payment Information to Payments Gateway

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Provide payment details for an existing transaction. This includes payment system, installments, and cardholder information.

```bash
curl -X POST "https://apiexamples.vtexpayments.com.br/api/pub/transactions/{transactionId}/payments" \
  -H "Content-Type: application/json" \
  -d '[{
    "paymentSystem": 6,
    "paymentSystemName": "Visa",
    "group": "creditCardPaymentGroup",
    "installments": 1,
    "installmentsInterestRate": 0,
    "installmentsValue": 9900,
    "value": 9900,
    "referenceValue": 9900,
    "hasDefaultBillingAddress": false,
    "fields": {
      "holderName": "Jane Doe",
      "cardNumber": "4111111111111111",
      "validationCode": "123",
      "dueDate": "10/28",
      "document": "12345678900",
      "accountId": "",
      "address": null
    }
  }]'
```

--------------------------------

### List Orders with Filters

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Lists orders with filtering options such as order by, page number, items per page, and status. Requires authentication.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/oms/pvt/orders?orderBy=creationDate,desc&page=1&per_page=15&f_status=invoiced" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Catalog API - Create Product

Source: https://context7.com/vtex/openapi-schemas/llms.txt

This endpoint allows you to create a new product in the VTEX catalog. It requires product details such as name, category, brand, and visibility settings.

```APIDOC
## POST /api/catalog/pvt/product

### Description
Creates a new product in the VTEX catalog.

### Method
POST

### Endpoint
/api/catalog/pvt/product

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the product.
- **CategoryId** (integer) - Required - The ID of the category the product belongs to.
- **BrandId** (integer) - Required - The ID of the brand the product belongs to.
- **RefId** (string) - Required - A unique reference ID for the product.
- **IsVisible** (boolean) - Required - Indicates if the product is visible.
- **Description** (string) - Optional - A detailed description of the product.
- **IsActive** (boolean) - Required - Indicates if the product is active.
- **TaxCode** (string) - Optional - The tax code for the product.
- **MetaTagDescription** (string) - Optional - Meta tag description for SEO.
- **ShowWithoutStock** (boolean) - Required - Indicates if the product should be shown even when out of stock.

### Request Example
```json
{
  "Name": "Lightweight Jacket",
  "CategoryId": 12,
  "BrandId": 2000001,
  "RefId": "JACKET-001",
  "IsVisible": true,
  "Description": "A breathable lightweight jacket for all seasons.",
  "IsActive": true,
  "TaxCode": "",
  "MetaTagDescription": "Lightweight jacket for everyday use",
  "ShowWithoutStock": true
}
```

### Response
#### Success Response (200 OK)
- **Id** (integer) - The ID of the created product.
- **Name** (string) - The name of the created product.
- **CategoryId** (integer) - The category ID of the created product.

#### Response Example
```json
{
  "Id": 1,
  "Name": "Lightweight Jacket",
  "CategoryId": 12
}
```
```

--------------------------------

### Get Price Table Mapping

Source: https://github.com/vtex/openapi-schemas/blob/master/examples/audience.md

Retrieves the price table mapping for a specific audience. This allows you to see which price table is currently assigned to an audience.

```APIDOC
## GET /api/price-table-mapper/pvt/mapping/{audienceId}

### Description
Gets the price table mapping for a given audience ID.

### Method
GET

### Endpoint
/api/price-table-mapper/pvt/mapping/{audienceId}

### Parameters
#### Path Parameters
- **audienceId** (string) - Required - The ID of the audience for which to retrieve the price table mapping.

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Create or Update Pickup Point

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Use this endpoint to create a new pickup point or update an existing one. It requires detailed address and business hour information.

```bash
curl -X PUT "https://apiexamples.vtexcommercestable.com.br/api/logistics/pvt/configuration/pickuppoints/mystore-downtown" \
  -H "Content-Type: application/json" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}" \
  -d '{
    "id": "mystore-downtown",
    "name": "Downtown Store",
    "description": "Main street flagship store",
    "instructions": "Ask for the pick-up counter at the entrance.",
    "formatted_address": "123 Main Street, New York, NY 10001",
    "address": {
      "postalCode": "10001",
      "country": { "acronym": "USA", "name": "United States" },
      "city": "New York",
      "state": "NY",
      "neighborhood": "Midtown",
      "street": "Main Street",
      "number": "123"
    },
    "isActive": true,
    "businessHours": [
      { "dayOfWeek": 1, "openingTime": "09:00", "closingTime": "18:00" }
    ]
  }'
```

--------------------------------

### Prism Validation Report Structure

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-run-prism-validation.md

An example of the markdown report generated by Prism validation. It includes an executive summary, detailed results, identified issues, and recommendations.

```markdown
# API Name - Prism Validation Report

## Executive Summary

✅ Success Rate: 85%
⚠️ Warnings: 5
❌ Critical Issues: 2

## Detailed Results

[Complete test results for every endpoint]

## Issues Identified

[Prioritized list of problems found]

## Recommendations

[Specific actions to take]
```

--------------------------------

### Review OpenAPI Schemas

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/openapi-gen-intro.md

Use the /review-openapi command to compare existing OpenAPI schemas against your implemented code. This can be done for all APIs, a single API, or multiple APIs.

```cursor
/review-openapi
```

```cursor
/review-openapi {repository-name}
```

```cursor
/review-openapi {repository-name-1}, {repository-name-2}, {repository-name-n}
```

--------------------------------

### Get the status of a sent offer using Marketplace API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Checks the status of an offer that has been sent to the marketplace. Requires the `feedId` and `offerId` to identify the specific offer.

```bash
curl -X GET "https://apiexamples.vtexcommercestable.com.br/api/sent-offers/feeds/{feedId}/offers/{offerId}" \
  -H "X-VTEX-API-AppKey: {appKey}" \
  -H "X-VTEX-API-AppToken: {appToken}"
```

--------------------------------

### Create a new shopper session using Session Manager API

Source: https://context7.com/vtex/openapi-schemas/llms.txt

Initiates a new shopper session, aggregating profile, price, and authentication data. The response sets a `VtexSession` cookie, which should be used in subsequent calls.

```bash
curl -X POST "https://apiexamples.vtexcommercestable.com.br/api/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "public": {
      "country": { "value": "BRA" },
      "postalCode": { "value": "22251-040" }
    }
  }'
```

--------------------------------

### Execute Batched OpenAPI Review Command

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-review-openapi-batched.md

Use this command in a Cursor AI chat with Agent mode and MAX mode enabled to review OpenAPI documentation for a specific codebase.

```bash
/review-openapi-batched orders
```

--------------------------------

### Rate Schema Quality

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/openapi-gen-intro.md

Compare generated schemas against published versions using the /rate-openapi command. You will be prompted for codebase name, date, and model to get a detailed report.

```cursor
/rate-openapi
```

--------------------------------

### Run Spectral Linter Command

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/spectral-linting.md

Use the `/spectral` command followed by the schema file name to lint OpenAPI schemas. This command can target generated, published, or any specified schema file.

```bash
/spectral {schema-file-name}
```

```bash
# Lint a generated schema
/spectral generated-docs/2025-10-28-Claude-4-Sonnet-Cursor/session/session-openapi.json
```

```bash
# Lint a published schema
/spectral VTEX - Session Manager API.json
```

```bash
# Lint any schema file
/spectral path/to/your-schema.json
```

--------------------------------

### Scenario 2: Pre-Review Check

Source: https://github.com/vtex/openapi-schemas/blob/master/docs/openapi-gen/how-to-run-prism-validation.md

Command for a pre-review check using verbose mode to identify technical issues before manual review. Saves reviewer time by addressing problems upfront.

```bash
/run-prism-validation VTEX - Existing API.json --verbose
```