DEV Community: Preecha

How to Document APIs for Internal and External Stakeholders: A Complete Guide

Preecha — Fri, 07 Aug 2026 13:01:12 +0000

API documentation is the backbone of successful API adoption, but internal and external documentation serve different users and goals. Internal teams need implementation detail and organizational context; external developers need a clear path from authentication to a successful integration. This guide shows how to structure, publish, and maintain API documentation for both audiences.

Try Apidog today

What It Means to Document APIs for Internal and External Stakeholders

Documenting APIs for internal and external stakeholders means creating targeted, accessible resources that help each group understand, test, and integrate with your APIs.

Internal stakeholders often include:

Developers
QA engineers
Architects
Operations teams
Product managers

Internal documentation should prioritize technical depth, maintainability, architecture, dependencies, and edge cases.

External stakeholders commonly include:

Customers
Partners
Third-party developers

External documentation is both a technical reference and part of your product experience. It should guide developers through onboarding, authentication, endpoint usage, errors, and troubleshooting.

Why Document Both Audiences?

Accelerate onboarding and productivity

Clear documentation helps new team members and external developers start without relying on tribal knowledge or one-on-one support.

Reduce support costs

Document common integration paths, error responses, and troubleshooting steps so teams can resolve issues independently.

Drive API adoption

For external users, documentation may be their first experience with your platform. A focused quickstart and complete endpoint reference reduce integration friction.

Improve consistency and compliance

Documentation establishes shared conventions across teams and supports security, governance, and regulatory requirements.

Internal vs. External API Documentation

Factor	Internal Stakeholders	External Stakeholders
Audience	Developers, QA, Ops, product managers	Partners, customers, third-party developers
Focus	Technical depth, edge cases, internal context	Clarity, onboarding, ease of use, completeness
Security	May include sensitive implementation details	Expose only public endpoints and safe examples
Format	Detailed and technical	Polished, branded, interactive, user-friendly
Examples	Deep dives, test cases, architecture diagrams	Quickstarts, SDKs, step-by-step integration guides
Updates	Fast iteration and internal changelogs	Versioned releases, backward compatibility, public changelogs

Best Practices

1. Define each audience before writing

Start with the user journey.

For internal documentation, answer questions such as:

Which services depend on this API?
What architectural decisions affect implementation?
Which failure modes or edge cases should engineers expect?
How should teams test the integration?

For external documentation, answer:

How does a developer get credentials?
What is the fastest successful API call?
What does a valid request and response look like?
How should errors, rate limits, and authentication failures be handled?

2. Maintain a single source of truth

Store API definitions, documentation, and changelogs in a centralized location. Tools such as Apidog can help teams create, manage, and publish documentation for multiple audiences from one workspace.

A practical workflow is:

Define the API contract using OpenAPI.
Review contract changes in pull requests.
Generate or update endpoint references from the contract.
Publish internal and external documentation from the same source.
Maintain audience-specific guides separately where necessary.

3. Use a consistent documentation structure

Use a predictable structure for every API:

Overview
Authentication
Base URL and environments
Endpoints
Request and response examples
Error codes
Rate limits and usage policies
Changelog

For example, an endpoint reference should include:

## Create a user

`POST /api/v1/users`

Creates a user in the current workspace.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | Yes | User email address |
| `name` | string | Yes | Display name |

### Example request

json
{
"email": "alice@example.com",
"name": "Alice"
}


### Example response

json
{
"id": "usr_123",
"email": "alice@example.com",
"name": "Alice"
}

shell

4. Write for the intended reader

Internal documentation can use organization-specific terminology when it improves precision. Include details such as service ownership, deployment dependencies, internal authentication flows, and known limitations.

External documentation should avoid unexplained internal terminology. Assume a developer may be seeing your API for the first time and explain required concepts before asking them to use them.

5. Include runnable examples

Examples should demonstrate complete requests, including headers and expected responses.

For an external API, provide copy-pasteable examples:

curl --request POST "https://api.example.com/api/v1/users" \
  --header "Authorization: Bearer $API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com",
    "name": "Alice"
  }'

For internal APIs, add test scripts, service-specific setup instructions, and architecture diagrams where they help engineers debug or extend the system.

6. Automate documentation updates

Connect API changes to your delivery workflow:

Validate OpenAPI definitions in CI.
Require documentation updates for breaking changes.
Generate endpoint references from the API definition.
Publish changelogs with versioned releases.
Mark deprecated endpoints with migration guidance.

With Apidog, teams can publish online documentation that updates as the API evolves.

7. Make documentation discoverable

For larger API portfolios:

Use clear navigation and endpoint categories.
Add tags for domain, owner, and lifecycle status.
Provide search.
Maintain an internal API catalog.
Link related APIs, SDKs, and integration guides.

8. Separate public information from sensitive information

Internal documentation may need to cover implementation details, but access should be restricted as appropriate.

External documentation should never expose confidential information such as:

Internal hostnames
Private service topology
Production secrets
Internal credentials
Non-public endpoints
Sensitive operational procedures

Practical Steps for Documenting APIs

Step 1: Define scope and audience

Decide whether the documentation is for internal users, external users, or both.

Create a short checklist before writing:

- Who will use this API?
- What is their primary goal?
- What credentials do they need?
- What is the first successful request?
- Which errors are most likely during integration?
- Which details must remain internal?

Step 2: Choose tools that support collaboration and versioning

Use a workflow that supports collaborative, version-controlled documentation. Apidog provides an environment for API design, testing, and documentation that can support both internal and external documentation needs.

Step 3: Build audience-specific documentation

Internal documentation checklist

API overview
Internal architecture and dependencies
Endpoint definitions with request and response examples
Authentication mechanisms
Error handling and edge cases
Test scripts and test environments
Changelogs and deprecated features
Internal usage guidelines
Ownership and escalation paths

External documentation checklist

Getting started guide
Authentication and authorization flows
Endpoint reference with code samples
Rate limits and usage policies
Error handling guidance
FAQs and troubleshooting
SDKs and integration tutorials
Support and contact information

Step 4: Generate and publish documentation

Generate documentation from your API definitions where possible to reduce drift between implementation and reference material.

For external developers, publish a branded public portal with onboarding guides and endpoint references.

For internal teams, restrict access to implementation details, architecture notes, and private endpoints as needed.

Step 5: Collect feedback and iterate

Treat documentation as a product.

Useful feedback signals include:

Support tickets caused by integration issues
Search terms with no useful results
Repeated questions from internal teams
Failed onboarding steps
Time to first successful API call
Deprecated endpoint usage

Review this feedback regularly and update the relevant guides, examples, and references.

Real-World Examples

Example 1: Internal API documentation for microservices

A fintech company uses multiple internal APIs for payments, user management, and notifications. Its internal documentation includes service dependencies, system diagrams, shared library references, test cases, and detailed authentication requirements.

An OpenAPI definition for an internal authentication endpoint might look like this:

paths:
  /auth/internal-login:
    post:
      summary: Internal login for service-to-service authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternalLoginRequest'
      responses:
        '200':
          description: Authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
      security:
        - internalApiKey: []

The team can use Apidog to generate internal-facing documentation and include references to shared libraries and system diagrams.

Example 2: External API documentation for a SaaS platform

A SaaS company exposes APIs for developers building third-party applications. Its external documentation includes:

An interactive API playground powered by Apidog
A step-by-step onboarding guide
Live code samples for JavaScript, Python, and Java
Authentication and rate-limit explanations
FAQ and support contact information

A simple request example might be:

POST /api/v1/users
Content-Type: application/json

{
  "email": "alice@example.com",
  "name": "Alice"
}

The public documentation is branded, polished, and updated with each API version.

Example 3: A hybrid documentation portal

Some organizations use one portal for both audiences. Access controls show internal implementation details to authenticated employees while exposing only public references to external users.

A practical split might look like this:

Public documentation
├── Quickstart
├── Authentication
├── API reference
├── SDKs
└── Support

Internal documentation
├── Service architecture
├── Private endpoints
├── Deployment dependencies
├── Incident runbooks
└── Internal changelog

Apidog workspace and permission features can support this type of audience separation.

How Apidog Helps

Apidog is designed to streamline API documentation for internal and external stakeholders:

Centralized API design and documentation: Define, test, and document APIs in one place.
Instant online docs: Generate and publish interactive documentation for different audiences.
Access controls: Configure permissions for internal-only content and public documentation.
Automated updates: Keep documentation aligned with API changes and reduce manual maintenance.
Mock data and testing: Let internal and external teams try endpoints before full integration.

Next Steps

Effective API documentation balances internal technical depth with external usability. Start by defining your audiences, maintaining a single source of truth, standardizing endpoint references, automating updates, and collecting feedback from real users.

When internal teams can quickly understand and maintain APIs—and external developers can integrate without unnecessary support—your API becomes easier to adopt, operate, and evolve.

How to Integrate Amazon SP API: Step-by-Step Tutorial

Preecha — Fri, 07 Aug 2026 01:03:52 +0000

TL;DR

Amazon Selling Partner API (SP-API) is a REST API for accessing seller data such as orders, inventory, listings, fulfillment, reports, and notifications. Production integrations require OAuth 2.0 authorization, AWS IAM configuration, SigV4-signed requests, endpoint-specific rate-limit handling, and secure token storage.

Try Apidog today

Introduction

Amazon operates across 200+ marketplaces and handles more than 350 million products. If you are building seller tools, inventory systems, fulfillment software, or analytics products, SP-API is the integration layer for automating order sync, stock monitoring, listing changes, and reporting.

A practical SP-API implementation needs to handle:

Amazon Developer and Seller Central registration
IAM roles and least-privilege policies
OAuth 2.0 seller authorization
Login with Amazon (LWA) access-token refresh
AWS Signature Version 4 (SigV4)
Orders, inventory, listings, reports, and notifications
Dynamic rate limits, retries, logging, and alerting

Apidog can help test SP-API endpoints, validate OAuth flows, inspect signed requests, mock responses, and share repeatable test scenarios with a team.

What Is Amazon SP-API?

Amazon Selling Partner API (SP-API) provides programmatic access to Seller Central data. It replaced Marketplace Web Service (MWS) with RESTful JSON endpoints, OAuth 2.0 authorization, IAM access control, and AWS SigV4 signing.

Key capabilities

SP-API can support:

Order retrieval and shipment updates
Inventory monitoring across marketplaces
Listing creation, updates, and deletion
FBA shipment workflows
Pricing and competitive-data workflows
Reports and analytics generation
A+ Content management
Brand analytics and advertising data

SP-API vs. MWS

Feature	SP-API	MWS (Legacy)
Architecture	RESTful JSON	XML-based
Authentication	OAuth 2.0 + IAM	MWS Auth Token
Security	AWS SigV4 signing	Simple tokens
Rate limits	Dynamic per endpoint	Fixed quotas
Marketplaces	Unified endpoints	Region-specific
Status	Current	Deprecated (Dec 2025)

Amazon announced full MWS retirement for December 2025. Migrate existing MWS integrations to SP-API as soon as possible.

Regional API endpoints

SP-API uses regional endpoints:

North America: https://sellingpartnerapi-na.amazon.com
Europe:        https://sellingpartnerapi-eu.amazon.com
Far East:      https://sellingpartnerapi-fe.amazon.com

Every request needs:

A valid LWA access token
AWS SigV4 signing
IAM role permissions
Request IDs in your logs for troubleshooting

Supported marketplaces

Region	Marketplaces	API endpoint
North America	US, CA, MX	sellingpartnerapi-na.amazon.com
Europe	UK, DE, FR, IT, ES, NL, SE, PL, TR, EG, IN, AE, SA	sellingpartnerapi-eu.amazon.com
Far East	JP, AU, SG, BR	sellingpartnerapi-fe.amazon.com

Getting Started: Account and IAM Setup

Step 1: Create an Amazon Developer account

Before making SP-API calls:

Open Amazon Developer Central.
Sign in with an Amazon account that has Seller Central access.
Open Selling Partner API.
Accept the Developer Agreement.

Step 2: Register an application

In Seller Central:

Go to Apps and Services → Develop Apps.
Select Add New App.
Set:
- Application Name
- Application Type: self-developed or third-party
- Use Case
- Redirect URI: an HTTPS callback URL for OAuth
Submit the application.

Amazon provides:

Application ID
Client ID
Client Secret

Store them outside source control.

# .env
AMAZON_APPLICATION_ID="amzn1.application.xxxxx"
AMAZON_CLIENT_ID="amzn1.account.xxxxx"
AMAZON_CLIENT_SECRET="your_client_secret_here"
AMAZON_SELLER_ID="your_seller_id_here"

AWS_ACCESS_KEY_ID="your_aws_access_key"
AWS_SECRET_ACCESS_KEY="your_aws_secret_key"
AWS_REGION="us-east-1"

Step 3: Create an IAM role

SP-API requires an IAM role.

Open the AWS IAM Console.
Go to Roles → Create role.
Select Another AWS account as the trusted entity.
Enter Amazon’s regional account ID:

Region	Amazon account ID
North America	`906394416454`
Europe	`336853085554`
Far East	`774466381866`

Step 4: Attach an IAM policy

Start with the required invoke permission:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:Invoke"
      ],
      "Resource": [
        "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/*"
      ]
    }
  ]
}

Use a descriptive role name such as SellingPartnerApiRole, then copy its ARN.

Step 5: Link the role to the application

In Seller Central:

Go to Develop Apps.
Open your application.
Select Edit.
Enter the IAM Role ARN.
Save the configuration.

Amazon usually validates the role within minutes. Confirm that the application displays a linked status before testing API calls.

OAuth 2.0 Authentication Flow

SP-API uses Login with Amazon (LWA) OAuth 2.0 authorization. A typical seller authorization flow is:

A seller clicks Authorize in your application.
Redirect the seller to Amazon’s authorization URL.
The seller signs in and grants access.
Amazon redirects to your callback URL.
Exchange spapi_oauth_code for LWA tokens.
Store the refresh token securely.
Use the LWA access token in SigV4-signed SP-API requests.
Refresh access tokens before they expire.

LWA access tokens typically expire after one hour.

Step 6: Generate an authorization URL

Generate and persist a random state value for CSRF protection.

const crypto = require('crypto');

const generateAuthUrl = (clientId, redirectUri, state) => {
  const baseUrl = 'https://www.amazon.com/sp/apps/oauth/authorize';

  const params = new URLSearchParams({
    application_id: process.env.AMAZON_APPLICATION_ID,
    client_id: clientId,
    redirect_uri: redirectUri,
    state,
    scope: 'sellingpartnerapi::notifications'
  });

  return `${baseUrl}?${params.toString()}`;
};

const state = crypto.randomBytes(16).toString('hex');

const authUrl = generateAuthUrl(
  process.env.AMAZON_CLIENT_ID,
  'https://your-app.com/callback',
  state
);

console.log(`Redirect seller to: ${authUrl}`);

Store state in the seller session or a short-lived database record before redirecting.

Required OAuth scopes

Request only scopes required by the integration.

Scope	Purpose	Typical use case
`sellingpartnerapi::notifications`	Receive notifications	Webhook subscriptions
`sellingpartnerapi::migration`	Migrate from MWS	Legacy integrations

Most SP-API access is governed by IAM and application permissions rather than OAuth scopes.

Step 7: Exchange the authorization code for LWA tokens

Handle the callback, validate state, and exchange the authorization code.

const exchangeCodeForLwaToken = async (code, redirectUri) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`LWA token error: ${error.error_description}`);
  }

  return response.json();
};

app.get('/callback', async (req, res) => {
  const { spapi_oauth_code, state } = req.query;

  if (state !== req.session.oauthState) {
    return res.status(400).send('Invalid state parameter');
  }

  try {
    const tokens = await exchangeCodeForLwaToken(
      spapi_oauth_code,
      'https://your-app.com/callback'
    );

    await db.sellers.update(req.session.sellerId, {
      amazon_lwa_access_token: tokens.access_token,
      amazon_lwa_refresh_token: tokens.refresh_token,
      amazon_token_expires: Date.now() + tokens.expires_in * 1000
    });

    res.redirect('/dashboard');
  } catch (error) {
    console.error('Token exchange failed:', error);
    res.status(500).send('Authentication failed');
  }
});

Step 8: Obtain temporary AWS credentials

Use your LWA authorization and IAM configuration to obtain the credentials required for signed SP-API access.

const assumeRole = async () => {
  const stsResponse = await fetch('https://sts.amazonaws.com/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      Action: 'AssumeRole',
      RoleArn: 'arn:aws:iam::YOUR_ACCOUNT:role/SellingPartnerApiRole',
      RoleSessionName: 'sp-api-session',
      Version: '2011-06-15'
    })
  });

  if (!stsResponse.ok) {
    throw new Error(`Unable to assume role: ${stsResponse.statusText}`);
  }

  return stsResponse.text();
};

Use temporary credentials when possible instead of long-term IAM credentials.

Step 9: Refresh LWA access tokens

Refresh tokens before expiration. A five-minute buffer avoids failures during long-running requests.

const refreshLwaToken = async (refreshToken) => {
  const response = await fetch('https://api.amazon.com/auth/o2/token', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: process.env.AMAZON_CLIENT_ID,
      client_secret: process.env.AMAZON_CLIENT_SECRET,
      refresh_token: refreshToken
    })
  });

  if (!response.ok) {
    throw new Error(`Token refresh failed: ${response.statusText}`);
  }

  return response.json();
};

const ensureValidToken = async (sellerId) => {
  const seller = await db.sellers.findById(sellerId);
  const expiresSoon = seller.amazon_token_expires < Date.now() + 300_000;

  if (!expiresSoon) {
    return seller.amazon_lwa_access_token;
  }

  const tokens = await refreshLwaToken(seller.amazon_lwa_refresh_token);

  await db.sellers.update(sellerId, {
    amazon_lwa_access_token: tokens.access_token,
    amazon_lwa_refresh_token: tokens.refresh_token,
    amazon_token_expires: Date.now() + tokens.expires_in * 1000
  });

  return tokens.access_token;
};

AWS SigV4 Request Signing

Every SP-API request must use AWS Signature Version 4. The signature proves request integrity and authenticity.

The signing process creates:

A canonical request
A string to sign
A derived signing key
An Authorization header

Prefer the AWS SDK signer

Avoid maintaining a custom signing implementation unless necessary. The AWS SDK signer reduces canonicalization mistakes.

const { SignatureV4 } = require('@aws-sdk/signature-v4');
const { Sha256 } = require('@aws-crypto/sha256-js');

const signer = new SignatureV4({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  },
  region: 'us-east-1',
  service: 'execute-api',
  sha256: Sha256
});

const makeSpApiRequest = async (method, endpoint, accessToken, body = null) => {
  const url = new URL(endpoint);

  const signedRequest = await signer.sign({
    method,
    hostname: url.hostname,
    path: url.pathname,
    query: Object.fromEntries(url.searchParams),
    headers: {
      host: url.host,
      'content-type': 'application/json',
      'x-amz-access-token': accessToken,
      'x-amz-date': new Date().toISOString().replace(/[:-]|\.\d{3}/g, '')
    },
    body: body ? JSON.stringify(body) : undefined
  });

  const response = await fetch(endpoint, {
    method,
    headers: signedRequest.headers,
    body: signedRequest.body
  });

  const data = await response.json();

  if (!response.ok) {
    const message = data.errors?.[0]?.message || response.statusText;
    const error = new Error(`SP-API ${response.status}: ${message}`);
    error.status = response.status;
    error.headers = response.headers;
    error.data = data;
    throw error;
  }

  return {
    data,
    headers: response.headers,
    status: response.status
  };
};

Custom SigV4 signing example

If you need to inspect the signing process while debugging, a custom signer can expose the canonical request and string to sign.

const crypto = require('crypto');

class SigV4Signer {
  constructor(accessKey, secretKey, region, service = 'execute-api') {
    this.accessKey = accessKey;
    this.secretKey = secretKey;
    this.region = region;
    this.service = service;
  }

  hmac(key, data, encoding = 'buffer') {
    return crypto.createHmac('sha256', key).update(data).digest(encoding);
  }

  sign(method, url, body = '', headers = {}) {
    const parsedUrl = new URL(url);
    const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
    const dateStamp = amzDate.slice(0, 8);

    const requestHeaders = {
      ...headers,
      host: parsedUrl.host,
      'x-amz-date': amzDate,
      'content-type': 'application/json'
    };

    const canonicalHeaders = Object.entries(requestHeaders)
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([key, value]) => `${key.toLowerCase()}:${value.trim()}`)
      .join('\n');

    const signedHeaders = Object.keys(requestHeaders)
      .sort()
      .map((key) => key.toLowerCase())
      .join(';');

    const payloadHash = crypto
      .createHash('sha256')
      .update(body)
      .digest('hex');

    const canonicalRequest = [
      method.toUpperCase(),
      parsedUrl.pathname,
      parsedUrl.search.slice(1),
      canonicalHeaders,
      '',
      signedHeaders,
      payloadHash
    ].join('\n');

    const algorithm = 'AWS4-HMAC-SHA256';
    const credentialScope = `${dateStamp}/${this.region}/${this.service}/aws4_request`;

    const stringToSign = [
      algorithm,
      amzDate,
      credentialScope,
      crypto.createHash('sha256').update(canonicalRequest).digest('hex')
    ].join('\n');

    const kDate = this.hmac(`AWS4${this.secretKey}`, dateStamp);
    const kRegion = this.hmac(kDate, this.region);
    const kService = this.hmac(kRegion, this.service);
    const kSigning = this.hmac(kService, 'aws4_request');
    const signature = this.hmac(kSigning, stringToSign, 'hex');

    const authorization =
      `${algorithm} Credential=${this.accessKey}/${credentialScope}, ` +
      `SignedHeaders=${signedHeaders}, Signature=${signature}`;

    return {
      headers: {
        ...requestHeaders,
        Authorization: authorization
      },
      canonicalRequest,
      stringToSign,
      signature
    };
  }
}

Orders API

The Orders API is commonly the first production workflow. Use it to fetch orders, retrieve line items, and confirm shipments.

Retrieve orders

Use date, marketplace, and status filters. Persist the latest successful sync timestamp and overlap requests slightly to prevent missing updates.

const getOrders = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    createdAfter: options.createdAfter || '',
    createdBefore: options.createdBefore || '',
    orderStatuses: options.orderStatuses?.join(',') || '',
    marketplaceIds: options.marketplaceIds?.join(',') || 'ATVPDKIKX0DER',
    maxResultsPerPage: String(options.maxResultsPerPage || 100)
  });

  for (const [key, value] of params.entries()) {
    if (!value) params.delete(key);
  }

  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/orders/v0/orders?${params}`;

  return makeSpApiRequest('GET', endpoint, accessToken);
};

const orders = await getOrders(accessToken, {
  createdAfter: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  orderStatuses: ['Unshipped', 'PartiallyShipped'],
  marketplaceIds: ['ATVPDKIKX0DER']
});

Example order response

{
  "payload": {
    "orders": [
      {
        "amazon_order_id": "112-1234567-1234567",
        "seller_order_id": "ORDER-001",
        "purchase_date": "2026-03-19T10:30:00Z",
        "last_update_date": "2026-03-19T14:45:00Z",
        "order_status": "Unshipped",
        "fulfillment_channel": "AFN",
        "sales_channel": "Amazon.com",
        "order_total": {
          "currency_code": "USD",
          "amount": "89.99"
        },
        "number_of_items_shipped": 0,
        "number_of_items_unshipped": 2,
        "marketplace_id": "ATVPDKIKX0DER",
        "is_prime": true
      }
    ],
    "next_token": "eyJleHBpcmF0aW9uVGltZU9mTmV4dFRva2VuIjoxNzEwOTUwNDAwfQ=="
  }
}

AFN means Fulfillment by Amazon (FBA); MFN means merchant fulfillment.

When next_token is present, continue pagination until it is empty.

Get order items

Fetch line items separately for each order when your fulfillment or reporting workflow needs SKU-level details.

const getOrderItems = async (accessToken, orderId) => {
  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/orders/v0/orders/${orderId}/orderItems`;

  return makeSpApiRequest('GET', endpoint, accessToken);
};

const orderItems = await getOrderItems(
  accessToken,
  '112-1234567-1234567'
);

Example response:

{
  "payload": {
    "order_items": [
      {
        "asin": "B08N5WRWNW",
        "seller_sku": "MYSKU-001",
        "title": "Wireless Bluetooth Headphones",
        "quantity_ordered": 2,
        "quantity_shipped": 0,
        "item_price": {
          "currency_code": "USD",
          "amount": "44.99"
        },
        "item_total": {
          "currency_code": "USD",
          "amount": "89.98"
        }
      }
    ]
  }
}

Confirm a shipment

For merchant-fulfilled orders, send the carrier, tracking number, ship date, and item quantities.

const confirmShipment = async (accessToken, orderId, shipmentData) => {
  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/orders/v0/orders/${orderId}/shipmentConfirmation`;

  const payload = {
    packageDetails: {
      packageReferenceId: shipmentData.packageReferenceId || '1',
      carrier_code: shipmentData.carrierCode,
      tracking_number: shipmentData.trackingNumber,
      ship_date: shipmentData.shipDate || new Date().toISOString(),
      items: shipmentData.items.map((item) => ({
        order_item_id: item.orderItemId,
        quantity: item.quantity
      }))
    }
  };

  return makeSpApiRequest('POST', endpoint, accessToken, payload);
};

await confirmShipment(accessToken, '112-1234567-1234567', {
  carrierCode: 'USPS',
  trackingNumber: '9400111899223456789012',
  items: [
    { orderItemId: '12345678901234', quantity: 2 }
  ]
});

Common carrier codes:

Carrier	Carrier code
USPS	`USPS`
FedEx	`FEDEX`
UPS	`UPS`
DHL	`DHL`
Canada Post	`CANADA_POST`
Royal Mail	`ROYAL_MAIL`
Australia Post	`AUSTRALIA_POST`
Amazon Logistics	`AMZN_UK`

Inventory API

Get inventory summaries

Use the FBA Inventory API to retrieve inventory summaries.

const getInventorySummaries = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    granularityType: options.granularityType || 'Marketplace',
    granularityId: options.granularityId || 'ATVPDKIKX0DER',
    startDateTime: options.startDateTime || '',
    sellerSkus: options.sellerSkus?.join(',') || ''
  });

  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?${params}`;

  return makeSpApiRequest('GET', endpoint, accessToken);
};

const inventory = await getInventorySummaries(accessToken, {
  granularityId: 'ATVPDKIKX0DER',
  sellerSkus: ['MYSKU-001', 'MYSKU-002']
});

Example response:

{
  "payload": {
    "inventorySummaries": [
      {
        "asin": "B08N5WRWNW",
        "seller_sku": "MYSKU-001",
        "condition": "NewItem",
        "details": {
          "quantity": 150,
          "fulfillable_quantity": 145,
          "inbound_shipped_quantity": 5,
          "reserved_quantity": 5,
          "unfulfillable_quantity": 0
        },
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ]
  }
}

Updating inventory

SP-API does not provide a direct inventory update endpoint. Inventory changes are typically handled through:

FBA inbound shipments
Merchant-fulfilled order processing
Listing updates through the Listings API

For FBA, create inbound shipment plans:

const createInboundShipmentPlan = async (accessToken, shipmentData) => {
  const endpoint = 'https://sellingpartnerapi-na.amazon.com/fba/inbound/v0/plans';

  const payload = {
    ShipFromAddress: {
      Name: shipmentData.shipFromName,
      AddressLine1: shipmentData.shipFromAddress,
      City: shipmentData.shipFromCity,
      StateOrProvinceCode: shipmentData.shipFromState,
      CountryCode: shipmentData.shipFromCountry,
      PostalCode: shipmentData.shipFromPostalCode
    },
    LabelPrepPreference: 'SELLER_LABEL',
    InboundPlanItems: shipmentData.items.map((item) => ({
      SellerSKU: item.sku,
      ASIN: item.asin,
      Quantity: item.quantity,
      Condition: 'NewItem'
    }))
  };

  return makeSpApiRequest('POST', endpoint, accessToken, payload);
};

Listings API

Get listings

Retrieve listings by identifier and marketplace.

const getListings = async (accessToken, options = {}) => {
  const params = new URLSearchParams({
    marketplaceIds: options.marketplaceIds?.join(',') || 'ATVPDKIKX0DER',
    itemTypes: options.itemTypes?.join(',') || 'ASIN,SKU',
    identifiers: options.identifiers?.join(',') || '',
    issuesLocale: options.locale || 'en_US'
  });

  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items?${params}`;

  return makeSpApiRequest('GET', endpoint, accessToken);
};

const listings = await getListings(accessToken, {
  identifiers: ['B08N5WRWNW', 'B09JQKJXYZ'],
  itemTypes: ['ASIN']
});

Example listing data:

{
  "identifiers": {
    "marketplaceId": "ATVPDKIKX0DER",
    "sku": "MYSKU-001",
    "asin": "B08N5WRWNW"
  },
  "attributes": {
    "title": "Wireless Bluetooth Headphones",
    "brand": "MyBrand",
    "color": "Black"
  },
  "product_type": "LUGGAGE",
  "sales_price": {
    "currency_code": "USD",
    "amount": "89.99"
  },
  "fulfillment_availability": [
    {
      "fulfillment_channel_code": "AFN",
      "quantity": 150
    }
  ],
  "status": "ACTIVE"
}

Update a listing

Use a patch request for targeted changes.

const submitListingUpdate = async (accessToken, sku) => {
  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/${sku}`;

  const payload = {
    productType: 'LUGGAGE',
    patches: [
      {
        op: 'replace',
        path: '/attributes/title',
        value: 'Updated Wireless Bluetooth Headphones - Premium Sound'
      },
      {
        op: 'replace',
        path: '/salesPrice',
        value: {
          currencyCode: 'USD',
          amount: '79.99'
        }
      }
    ]
  };

  return makeSpApiRequest('PATCH', endpoint, accessToken, payload);
};

Delete a listing

const deleteListing = async (accessToken, sku, marketplaceIds) => {
  const params = new URLSearchParams({
    marketplaceIds: marketplaceIds.join(',')
  });

  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/${sku}?${params}`;

  return makeSpApiRequest('DELETE', endpoint, accessToken);
};

Reports API

Reports are asynchronous. Create a report, poll its status, then download the document when it is ready.

Create a report

const createReport = async (accessToken, reportType, dateRange) => {
  const endpoint =
    'https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports';

  const payload = {
    reportType,
    marketplaceIds: dateRange.marketplaceIds || ['ATVPDKIKX0DER'],
    dataStartTime: dateRange.startTime?.toISOString(),
    dataEndTime: dateRange.endTime?.toISOString()
  };

  return makeSpApiRequest('POST', endpoint, accessToken, payload);
};

const REPORT_TYPES = {
  ORDERS: 'GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL',
  ORDER_ITEMS: 'GET_FLAT_FILE_ORDER_ITEMS_DATA_BY_LAST_UPDATE_GENERAL',
  INVENTORY: 'GET_MERCHANT_LISTINGS_ALL_DATA',
  FBA_INVENTORY: 'GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA',
  SETTLEMENT: 'GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE',
  SALES_AND_TRAFFIC: 'GET_SALES_AND_TRAFFIC_REPORT',
  ADVERTISING: 'GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT'
};

const report = await createReport(accessToken, REPORT_TYPES.ORDERS, {
  marketplaceIds: ['ATVPDKIKX0DER'],
  startTime: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
  endTime: new Date()
});

Download a report document

const getReportDocument = async (accessToken, reportId) => {
  const endpoint =
    `https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports/${reportId}/document`;

  return makeSpApiRequest('GET', endpoint, accessToken);
};

const downloadReport = async (accessToken, reportId) => {
  const documentInfo = await getReportDocument(accessToken, reportId);

  const response = await fetch(documentInfo.data.payload.url);
  const content = await response.text();

  if (documentInfo.data.payload.compressionAlgorithm === 'GZIP') {
    return decompressGzip(content);
  }

  return content;
};

Reports are commonly tab-delimited or JSON. Poll report status at a controlled interval rather than continuously.

Notifications API

SP-API notifications use Amazon SNS. Use notifications to reduce polling for order, inventory, and fulfillment changes.

Create a destination

First create an SNS-backed destination.

const createSnsDestination = async (accessToken, destinationData) => {
  const endpoint =
    'https://sellingpartnerapi-na.amazon.com/notifications/v1/destinations';

  const payload = {
    resource: destinationData.snsTopicArn,
    name: destinationData.name
  };

  return makeSpApiRequest('POST', endpoint, accessToken, { payload });
};

Example SNS topic policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "notifications.amazon.com"
      },
      "Action": "SNS:Publish",
      "Resource": "arn:aws:sns:us-east-1:123456789012:sp-api-notifications"
    }
  ]
}

Create a subscription

const createSubscription = async (accessToken, subscriptionData) => {
  const endpoint =
    'https://sellingpartnerapi-na.amazon.com/notifications/v1/subscriptions';

  const payload = {
    payload: {
      destination: {
        resource: subscriptionData.destinationArn,
        name: subscriptionData.name
      },
      modelVersion: '1.0',
      eventFilter: {
        eventCode: subscriptionData.eventCode,
        marketplaceIds: subscriptionData.marketplaceIds
      }
    }
  };

  return makeSpApiRequest('POST', endpoint, accessToken, payload);
};

const EVENT_CODES = {
  ORDER_STATUS_CHANGE: 'OrderStatusChange',
  ORDER_ITEM_CHANGE: 'OrderItemChange',
  ORDER_CHANGE: 'OrderChange',
  FBA_ORDER_STATUS_CHANGE: 'FBAOrderStatusChange',
  FBA_OUTBOUND_SHIPMENT_STATUS: 'FBAOutboundShipmentStatus',
  INVENTORY_LEVELS: 'InventoryLevels',
  PRICING_HEALTH: 'PricingHealth'
};

await createSubscription(accessToken, {
  destinationArn: 'arn:aws:sns:us-east-1:123456789012:sp-api-notifications',
  name: 'OrderStatusNotifications',
  eventCode: EVENT_CODES.ORDER_STATUS_CHANGE,
  marketplaceIds: ['ATVPDKIKX0DER']
});

Process SNS notifications

Your webhook must validate SNS messages, handle subscription confirmation, and return a successful response promptly.

const express = require('express');
const app = express();

app.post(
  '/webhooks/amazon',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-amz-sns-message-signature'];
    const payload = req.body;

    const isValid = await verifySnsSignature(payload, signature);

    if (!isValid) {
      return res.status(401).send('Unauthorized');
    }

    const message = JSON.parse(payload.toString());

    if (message.Type === 'SubscriptionConfirmation') {
      await fetch(message.SubscribeURL);
    }

    if (message.Type === 'Notification') {
      const notification = JSON.parse(message.Message);
      await handleSpApiNotification(notification);
    }

    res.status(200).send('OK');
  }
);

async function handleSpApiNotification(notification) {
  const { notificationType, payload } = notification;

  switch (notificationType) {
    case 'OrderStatusChange':
      await syncOrderStatus(payload.amazonOrderId);
      break;
    case 'OrderChange':
      await syncOrderDetails(payload.amazonOrderId);
      break;
    case 'InventoryLevels':
      await updateInventoryCache(payload);
      break;
  }
}

Use notifications as a trigger, then fetch the current resource state from SP-API before updating your local database.

Rate Limiting and Quotas

SP-API rate limits are dynamic and differ by operation. Check the x-amzn-RateLimit-Limit response header instead of assuming a fixed quota.

Endpoint category	Rate limit	Burst limit
Orders	10 requests/second	20
Order Items	5 requests/second	10
Inventory	2 requests/second	5
Listings	10 requests/second	20
Reports	0.5 requests/second	1
Notifications	1 request/second	2
FBA Inbound	2 requests/second	5

Retry 429 and 503 responses

Use Retry-After when Amazon provides it. Otherwise, apply exponential backoff.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const makeRateLimitedRequest = async (
  method,
  endpoint,
  accessToken,
  body = null,
  maxRetries = 5
) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await makeSpApiRequest(method, endpoint, accessToken, body);
    } catch (error) {
      const retryable = error.status === 429 || error.status === 503;

      if (!retryable || attempt === maxRetries) {
        throw error;
      }

      const retryAfter = Number(error.headers?.get('Retry-After'));
      const delayMs = Number.isFinite(retryAfter)
        ? retryAfter * 1000
        : 2 ** attempt * 1000;

      console.warn(
        `SP-API request failed with ${error.status}. Retrying in ${delayMs}ms.`
      );

      await sleep(delayMs);
    }
  }
};

Queue outbound requests

A token-bucket queue prevents bursts from exceeding endpoint limits.

class RateLimitedQueue {
  constructor(rateLimit, burstLimit = rateLimit * 2) {
    this.rateLimit = rateLimit;
    this.burstLimit = burstLimit;
    this.tokens = burstLimit;
    this.lastRefill = Date.now();
    this.queue = [];
    this.processing = false;
  }

  add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  refillTokens() {
    const now = Date.now();
    const elapsedSeconds = (now - this.lastRefill) / 1000;

    this.tokens = Math.min(
      this.burstLimit,
      this.tokens + elapsedSeconds * this.rateLimit
    );

    this.lastRefill = now;
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;

    while (this.queue.length > 0) {
      this.refillTokens();

      if (this.tokens < 1) {
        await new Promise((resolve) => {
          setTimeout(resolve, (1 / this.rateLimit) * 1000);
        });
        continue;
      }

      this.tokens -= 1;

      const { requestFn, resolve, reject } = this.queue.shift();

      try {
        resolve(await requestFn());
      } catch (error) {
        reject(error);
      }
    }

    this.processing = false;
  }
}

const ordersQueue = new RateLimitedQueue(10, 20);

const orders = await ordersQueue.add(() =>
  getOrders(accessToken, {
    marketplaceIds: ['ATVPDKIKX0DER']
  })
);

Maintain separate queues per API operation or endpoint group because quotas differ.

Security Best Practices

Keep credentials out of source code

// Bad
const AWS_ACCESS_KEY = 'AKIAIOSFODNN7EXAMPLE';
const AWS_SECRET = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY';

// Good
const AWS_ACCESS_KEY = process.env.AWS_ACCESS_KEY_ID;
const AWS_SECRET = process.env.AWS_SECRET_ACCESS_KEY;

Use AWS Secrets Manager or another managed secret store for production credentials.

const {
  SecretsManagerClient,
  GetSecretValueCommand
} = require('@aws-sdk/client-secrets-manager');

const secretsClient = new SecretsManagerClient({ region: 'us-east-1' });

const getCredentials = async () => {
  const response = await secretsClient.send(
    new GetSecretValueCommand({
      SecretId: 'prod/sp-api/credentials'
    })
  );

  return JSON.parse(response.SecretString);
};

Encrypt stored tokens

Protect refresh tokens and access tokens with encryption at rest, TLS in transit, limited service-account access, and audit logging.

const crypto = require('crypto');

class TokenStore {
  constructor(encryptionKey) {
    this.algorithm = 'aes-256-gcm';
    this.key = crypto
      .createHash('sha256')
      .update(encryptionKey)
      .digest()
      .subarray(0, 32);
  }

  encrypt(token) {
    const iv = crypto.randomBytes(16);
    const cipher = crypto.createCipheriv(this.algorithm, this.key, iv);

    const encrypted = Buffer.concat([
      cipher.update(token, 'utf8'),
      cipher.final()
    ]);

    return {
      iv: iv.toString('hex'),
      encryptedData: encrypted.toString('hex'),
      authTag: cipher.getAuthTag().toString('hex')
    };
  }

  decrypt(value) {
    const decipher = crypto.createDecipheriv(
      this.algorithm,
      this.key,
      Buffer.from(value.iv, 'hex')
    );

    decipher.setAuthTag(Buffer.from(value.authTag, 'hex'));

    return Buffer.concat([
      decipher.update(Buffer.from(value.encryptedData, 'hex')),
      decipher.final()
    ]).toString('utf8');
  }
}

Apply IAM least privilege

Do not use broad wildcards in production when endpoint-specific permissions are possible.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SPAPIOrdersAccess",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/orders/*"
    },
    {
      "Sid": "SPAPIInventoryAccess",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*/prod/*/sellingpartnerapi/fba/inventory/*"
    }
  ]
}

Validate signing prerequisites

For SigV4 requests:

Use HTTPS.
Include all required headers in the signature.
Keep server time synchronized.
Rotate AWS credentials.
Prefer IAM roles and temporary credentials.

AWS can reject requests when timestamps differ by more than five minutes.

const validateTimestamp = (amzDate) => {
  const requestTime = new Date(amzDate);
  const difference = Math.abs(Date.now() - requestTime.getTime());

  if (difference > 5 * 60 * 1000) {
    throw new Error('Request timestamp is too old. Check server clock synchronization.');
  }
};

Testing SP-API Integrations with Apidog

SP-API testing involves OAuth redirects, LWA tokens, SigV4 signatures, dynamic limits, and asynchronous workflows. Test each layer independently before combining them.

1. Import the SP-API specification

In Apidog:

Create a project.
Import Amazon’s SP-API OpenAPI specification.
Create sandbox and production environments.
Add environment variables for API endpoints and credentials.

Example environment values:

Base URL (Sandbox):    https://sandbox.sellingpartnerapi-na.amazon.com
Base URL (Production): https://sellingpartnerapi-na.amazon.com
LWA Access Token:      {{lwa_access_token}}
AWS Access Key:        {{aws_access_key}}
AWS Secret Key:        {{aws_secret_key}}
Region:                us-east-1

2. Add a pre-request signing script

Use a pre-request script to add the LWA token and signed headers before each API call.

const crypto = require('crypto');

const accessKey = apidog.variables.get('aws_access_key');
const secretKey = apidog.variables.get('aws_secret_key');
const accessToken = apidog.variables.get('lwa_access_token');
const region = apidog.variables.get('region');

const method = apidog.request.method;
const url = new URL(apidog.request.url);
const body = apidog.request.body;

const signer = new SigV4Signer(accessKey, secretKey, region);

const signedHeaders = signer.sign(method, url.href, body, {
  'x-amz-access-token': accessToken
});

apidog.request.headers = {
  ...apidog.request.headers,
  ...signedHeaders.headers
};

3. Build workflow tests

Test an end-to-end order workflow:

Exchange OAuth code for an access token.
Request orders for a time range.
Validate the response.
Extract order IDs.
Request line items for each order.

const ordersResponse = await apidog.send({
  method: 'GET',
  url: '/orders/v0/orders',
  params: {
    createdAfter: new Date(Date.now() - 86_400_000).toISOString(),
    marketplaceIds: 'ATVPDKIKX0DER'
  }
});

apidog.assert(
  ordersResponse.status === 200,
  'Orders request failed'
);

apidog.assert(
  ordersResponse.data.payload.orders.length > 0,
  'No orders found'
);

const orderIds = ordersResponse.data.payload.orders.map(
  (order) => order.amazon_order_id
);

apidog.variables.set('order_ids', JSON.stringify(orderIds));

4. Mock SP-API responses

Mock responses let frontend and integration work continue without repeatedly calling live endpoints.

{
  "payload": {
    "orders": [
      {
        "amazon_order_id": "112-{{randomNumber}}-{{randomNumber}}",
        "order_status": "Unshipped",
        "purchase_date": "{{now}}",
        "order_total": {
          "currency_code": "USD",
          "amount": "{{randomFloat 10 500}}"
        }
      }
    ],
    "next_token": null
  }
}

5. Add API tests to CI/CD

Run sandbox tests in CI before deploying changes.

name: SP-API Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog Tests
        uses: apidog/test-action@v1
        with:
          project-id: ${{ secrets.APIDOG_PROJECT_ID }}
          api-key: ${{ secrets.APIDOG_API_KEY }}
          environment: sandbox

      - name: Notify on Failure
        if: failure()
        run: |
          echo "SP-API tests failed - check Apidog dashboard"

Marketplace ID Reference

Country	Marketplace ID
United States	`ATVPDKIKX0DER`
Canada	`A2EUQ1WTGCTBG2`
Mexico	`A1AM78C64UM0Y8`
United Kingdom	`A1F83G8C2ARO7P`
Germany	`A1PA6795UKMFR9`
France	`A13V1IB3VIYZZH`
Italy	`APJ6JRA9NG5V4`
Spain	`A1RKKUPIHCS9HS`
Japan	`A1VC38T7YXB528`
Australia	`A39IBJ37TRP1C6`
India	`A21TJRUUN4KGV`
Brazil	`A2Q3Y263D00KWC`

Troubleshooting Common Issues

403 Unauthorized or Access Denied

Common causes:

Expired LWA access token
Invalid AWS credentials
Incorrect IAM role configuration
IAM role not linked to the application
Missing x-amz-access-token
Invalid SigV4 region, date, canonical request, or signature

Log the response body and request ID:

const error = await response.json();

console.error('SP-API authorization error:', {
  status: response.status,
  requestId: response.headers.get('x-amzn-requestid'),
  error
});

429 Rate Limit Exceeded

Use these mitigations:

Queue requests by endpoint.
Respect Retry-After.
Apply exponential backoff.
Paginate with next_token.
Monitor x-amzn-RateLimit-Limit.
Request higher limits through Seller Central for approved high-volume cases.

404 Not Found

Check:

The regional endpoint matches the marketplace.
The marketplace ID is valid.
The resource exists.
The API version in the route is correct, such as /v0/ or /2021-08-01/.

400 Bad Request

Typical causes:

Invalid ISO 8601 date values
Missing required query parameters
Invalid marketplace ID
Malformed JSON body

Validate date inputs before sending requests:

const validateIsoDate = (dateString) => {
  const date = new Date(dateString);

  if (Number.isNaN(date.getTime())) {
    throw new Error('Invalid ISO 8601 date format');
  }

  return dateString;
};

Reports remain in `INIT_STATE`

Reports can take 15–30 minutes or longer depending on report type and date range.

Poll report status about every 30 seconds.
Confirm that the report type is available for the seller account.
Try a smaller date range.
Verify required permissions.

Notifications are not arriving

Check:

Subscription status
SNS topic resource policy
HTTPS endpoint reachability
SSL certificate validity
CloudWatch delivery logs
Response time from the webhook

Return 200 OK within 30 seconds and automatically confirm SubscriptionConfirmation messages.

Production Deployment Checklist

Before enabling production traffic:

[ ] Register the application in production Seller Central.
[ ] Configure a production IAM role with least-privilege permissions.
[ ] Update OAuth redirect URIs to production URLs.
[ ] Encrypt tokens in storage.
[ ] Implement automatic token refresh.
[ ] Add endpoint-specific rate limiting and queuing.
[ ] Configure an SNS destination and subscriptions.
[ ] Implement retries for 429 and 503 responses.
[ ] Log API calls and Amazon request IDs.
[ ] Monitor rate-limit usage.
[ ] Test multiple marketplace IDs.
[ ] Document seller onboarding and OAuth recovery steps.
[ ] Create a runbook for common failures.
[ ] Alert on token refresh and authentication failures.

Monitoring and alerting

Track API success rates, rate-limit usage, token refresh failures, notification processing, and report generation status.

const metrics = {
  apiCalls: {
    total: 0,
    successful: 0,
    failed: 0,
    rateLimited: 0
  },
  rateLimitUsage: {
    orders: { current: 0, limit: 10 },
    inventory: { current: 0, limit: 2 },
    listings: { current: 0, limit: 10 }
  },
  oauthTokens: {
    active: 0,
    expiringSoon: 0,
    refreshFailures: 0
  },
  notifications: {
    received: 0,
    processed: 0,
    failed: 0
  },
  reports: {
    pending: 0,
    completed: 0,
    failed: 0
  }
};

const failureRate =
  metrics.apiCalls.total === 0
    ? 0
    : metrics.apiCalls.failed / metrics.apiCalls.total;

if (failureRate > 0.05) {
  sendAlert('SP-API failure rate above 5%');
}

for (const [endpoint, usage] of Object.entries(metrics.rateLimitUsage)) {
  if (usage.current / usage.limit > 0.8) {
    sendAlert(`${endpoint} rate limit is above 80% capacity`);
  }
}

Real-World Implementation Patterns

Multi-marketplace inventory sync

A central inventory service can use InventoryLevels notifications and scheduled inventory-summary pulls to keep marketplaces synchronized.

Implementation flow:

Receive an InventoryLevels SNS notification.
Fetch or reconcile current inventory state.
Calculate available quantity for each marketplace.
Submit listing updates through a rate-limited queue.
Record the request and result in an audit log.

This pattern helps reduce overselling caused by delayed manual updates.

Automated order fulfillment

A fulfillment workflow can:

Receive an OrderStatusChange notification.
Fetch current order details and line items.
Send the order to a warehouse management system.
Receive tracking data from the warehouse.
Confirm the shipment through SP-API.
Store every state transition for support and reconciliation.

Seller analytics dashboard

For multi-seller applications:

Store encrypted refresh tokens per seller.
Refresh access tokens only when needed.
Queue report and order requests by seller and endpoint.
Aggregate orders, inventory, listings, and reports into normalized tables.
Keep marketplace IDs as first-class data fields.

Sellers operating across multiple storefronts may also need an Etsy integration after Amazon. The Etsy API has comparable OAuth and listing workflows, but its scopes and rate limits should be mapped separately.

Conclusion

Amazon SP-API provides access to Seller Central workflows for orders, inventory, listings, reports, fulfillment, and notifications.

For a production-ready integration:

Use OAuth 2.0 and IAM roles with secure token storage.
Refresh LWA access tokens automatically.
Sign every request using AWS SigV4.
Use SDK signing support or a well-tested signer.
Respect endpoint-specific rate limits with queues and backoff.
Use SNS notifications for near-real-time order and inventory workflows.
Log request IDs, failures, rate-limit data, and token events.
Test OAuth, signed requests, retries, and webhook processing before production.

FAQ

What is Amazon SP-API?

Amazon Selling Partner API is a REST API for accessing Seller Central data, including orders, inventory, listings, reports, and fulfillment workflows. It replaced MWS and uses OAuth 2.0 plus AWS SigV4 signing.

How do I get Amazon SP-API credentials?

Register an application in Seller Central under Apps and Services → Develop Apps. Amazon provides an Application ID, Client ID, and Client Secret. You also need an AWS IAM role linked to the application.

Is Amazon SP-API free to use?

SP-API access is free for registered Amazon sellers. Rate limits apply and vary by endpoint. Higher limits may require Amazon approval for high-volume use cases.

What authentication does SP-API use?

SP-API uses OAuth 2.0 for seller authorization, AWS IAM for access control, and AWS SigV4 for request signing.

How should I handle SP-API rate limits?

Create endpoint-specific request queues, read x-amzn-RateLimit-Limit, respect Retry-After, use exponential backoff after HTTP 429, and paginate results with next_token.

Can I test SP-API without a live seller account?

Amazon provides a sandbox environment for SP-API development. Sandbox availability differs by endpoint, so test critical workflows against the environments available to your application.

How do webhooks work with SP-API?

SP-API notifications are delivered through Amazon SNS. Create a destination, subscribe to event types, validate SNS messages at your HTTPS endpoint, confirm subscriptions, and fetch the current resource state after receiving a notification.

What happens when an OAuth token expires?

LWA access tokens expire after approximately one hour. Use the stored refresh token to get a new access token before expiration.

How do I migrate from MWS to SP-API?

Migration includes replacing MWS tokens with OAuth 2.0, adding SigV4 signing, updating endpoint URLs, and converting XML request/response handling to JSON. MWS retirement is scheduled for December 2025.

Why am I getting 403 errors?

Common causes are expired OAuth tokens, missing access-token headers, invalid SigV4 signatures, incorrect regions, IAM permission issues, or an IAM role that is not linked to the Seller Central application.

MiMo-V2-Pro & Omni Pricing and How to Use the API

Preecha — Thu, 06 Aug 2026 13:01:37 +0000

TL;DR

MiMo-V2-Pro costs $1/1M input tokens and $3/1M output tokens for requests up to 256K context. MiMo-V2-Omni supports text, image, audio, and video inputs through a unified model. Both are available through an OpenAI-compatible API at platform.xiaomimimo.com. Use Apidog to inspect requests visually, then use Python and mocked unit tests for production integrations.

Try Apidog today

Introduction

Xiaomi released three AI models on March 18, 2026. The two flagship models are:

MiMo-V2-Pro for deep reasoning, agent workflows, coding, and long-context tasks.
MiMo-V2-Omni for multimodal workflows involving text, images, audio, and video.

This guide covers pricing, API setup, request validation in Apidog, a Python integration, and unit tests that avoid API spend in CI.

Before writing code, download Apidog for free. You can send requests, inspect response payloads, validate token usage, and add assertions before integrating the API into your application.

MiMo-V2-Pro Pricing and MiMo-V2-Omni Pricing

Start by estimating request costs. Both models use token-based pricing, and MiMo-V2-Pro pricing changes based on context length.

MiMo-V2-Pro Pricing by Context Length

Context length	Input price per 1M tokens	Output price per 1M tokens
≤ 256K tokens	$1.00	$3.00
256K–1M tokens	$2.00	$6.00

MiMo-V2-Pro supports a 1M-token context window. Requests that remain under 256K tokens use the lower tier. The higher tier applies to long-context workloads such as full-codebase analysis or extended planning sequences.

For example, estimate the cost of a request with 20,000 input tokens and 5,000 output tokens in the lower tier:

Input cost  = (20,000 / 1,000,000) × $1.00 = $0.020
Output cost = (5,000 / 1,000,000) × $3.00 = $0.015
Total cost  = $0.035

MiMo-V2-Omni Pricing

MiMo-V2-Omni uses a similar pricing structure, with multimodal token usage as an additional consideration.

The model natively processes:

Text
Images
Audio
Video

Image and audio inputs are tokenized alongside text. As a result, multimodal requests can consume more tokens than text-only requests. Measure token usage from API responses and use current rates from platform.xiaomimimo.com when estimating cost.

MiMo-V2 Family Pricing Comparison

Model	Input price per 1M tokens	Output price per 1M tokens	Context window	Modalities
MiMo-V2-Pro	$1.00 / $2.00*	$3.00 / $6.00*	1M tokens	Text
MiMo-V2-Omni	~$1.00*	~$3.00*	256K tokens	Text, image, audio, video
MiMo-V2-Flash	$0.10	$0.30	256K tokens	Text

* Tiered or approximate. Verify current rates at platform.xiaomimimo.com.

Choose the model based on the workload:

Use MiMo-V2-Flash for low-cost text tasks.
Use MiMo-V2-Pro for long-context reasoning, planning, and code tasks.
Use MiMo-V2-Omni when one request needs text plus images, audio, or video.

MiMo-V2-Pro and MiMo-V2-Omni API Capabilities

MiMo-V2-Pro

MiMo-V2-Pro is Xiaomi's flagship reasoning model. Its published capabilities include:

1 trillion total parameters and 42 billion active parameters
1M-token context window
Multi-Token Prediction (MTP) for faster inference
Support for autonomous multi-step reasoning, tool execution, and software-engineering tasks
#1 ranking among 160 models in its price tier on the Artificial Analysis Intelligence Index, with a score of 49 versus a median of 13
Strong SWE-Bench and coding benchmark performance

Use it for text-only workflows that require planning, code generation, debugging, or multi-step reasoning.

MiMo-V2-Omni

MiMo-V2-Omni is Xiaomi's multimodal foundation model. It supports:

Text, images, audio, and video
Integrated image and audio encoders
Document understanding
Audio transcription
Video analysis
Cross-modal reasoning

Use it when a workflow needs to reason over more than text.

Both models are available from platform.xiaomimimo.com through OpenAI-compatible endpoints. If your application already uses the OpenAI SDK, you can typically switch the base_url and model name rather than adopting a new SDK.

Test MiMo API Requests with Apidog

Use Apidog to validate the endpoint, headers, request body, response format, and token usage before implementing application code.

1. Create a Request

Create a project such as MiMo-V2 API Tests, then add a new HTTP request.

Method: POST
URL: https://api.xiaomimimo.com/v1/chat/completions

2. Configure Headers

Add these headers:

Key	Value
`Authorization`	`Bearer YOUR_MIMO_API_KEY`
`Content-Type`	`application/json`

3. Send a MiMo-V2-Pro Request

In Body → JSON, add:

{
  "model": "mimo-v2-pro",
  "messages": [
    {
      "role": "user",
      "content": "Write a Python function that checks if a number is prime, and explain how you would unit test it."
    }
  ],
  "temperature": 0.6,
  "max_tokens": 512
}

Click Send and inspect:

HTTP status
choices[0].message.content
Returned model ID
usage.prompt_tokens
usage.completion_tokens
usage.total_tokens

4. Send a MiMo-V2-Omni Request

Change the model name and provide multimodal content:

{
  "model": "mimo-v2-omni",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe what you see in this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/diagram.png"
          }
        }
      ]
    }
  ],
  "max_tokens": 300
}

This lets you confirm that your image input format and response schema work before implementing the request in code.

Add Response Assertions in Apidog

Open the Tests tab and add assertions for the response contract:

// HTTP status is successful
pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

// Returned model is a MiMo model
pm.test("Model ID is correct", function () {
  const json = pm.response.json();
  pm.expect(json.model).to.include("mimo-v2");
});

// Response includes assistant content
pm.test("Assistant message is present", function () {
  const json = pm.response.json();
  pm.expect(json.choices[0].message.content)
    .to.be.a("string")
    .and.not.empty;
});

// Usage is present for cost tracking
pm.test("Token usage is present", function () {
  const json = pm.response.json();
  pm.expect(json.usage.total_tokens).to.be.above(0);
});

These checks validate four important integration points:

The API endpoint is reachable.
The expected model handled the request.
The response contains usable assistant content.
Token usage is available for pricing analysis.

Save the request collection and run it with Apidog's CLI runner in CI when you need request-level regression coverage.

Use the MiMo API with Python

For production code, use the OpenAI Python SDK with MiMo's API base URL.

Install Dependencies

pip install openai pytest

Create a MiMo-V2-Pro Client

Create mimo_client.py:

from openai import OpenAI

# Point the OpenAI client at the MiMo API.
client = OpenAI(
    api_key="YOUR_MIMO_API_KEY",
    base_url="https://api.xiaomimimo.com/v1"
)

def ask_mimo_pro(prompt: str) -> dict:
    """Call MiMo-V2-Pro and return the fields needed by the application."""
    response = client.chat.completions.create(
        model="mimo-v2-pro",
        messages=[
            {
                "role": "user",
                "content": prompt,
            }
        ],
        temperature=0.6,
        max_tokens=512,
    )

    return {
        "content": response.choices[0].message.content,
        "model": response.model,
        "prompt_tokens": response.usage.prompt_tokens,
        "completion_tokens": response.usage.completion_tokens,
        "total_tokens": response.usage.total_tokens,
    }

if __name__ == "__main__":
    result = ask_mimo_pro("What is a unit test and why does it matter?")
    print(result["content"])

    # Estimate cost using the MiMo-V2-Pro ≤256K pricing tier.
    input_cost = (result["prompt_tokens"] / 1_000_000) * 1.00
    output_cost = (result["completion_tokens"] / 1_000_000) * 3.00

    print(f"Estimated cost: ${input_cost + output_cost:.6f}")

Run it:

python mimo_client.py

For deployment, store YOUR_MIMO_API_KEY in an environment variable or your platform's secret manager rather than committing it to source control.

Unit Test the MiMo Python Integration

Do not call the live API in normal unit tests. Mock the SDK call so tests are fast and do not consume tokens.

Create test_mimo_client.py:

import pytest
from unittest.mock import MagicMock, patch

from mimo_client import ask_mimo_pro

@pytest.fixture
def mock_mimo_response():
    """Mock a MiMo-V2-Pro API response."""
    mock = MagicMock()
    mock.choices[0].message.content = (
        "A unit test verifies a single function behaves correctly in isolation."
    )
    mock.model = "mimo-v2-pro"
    mock.usage.prompt_tokens = 20
    mock.usage.completion_tokens = 30
    mock.usage.total_tokens = 50
    return mock

@patch("mimo_client.client.chat.completions.create")
def test_returns_content(mock_create, mock_mimo_response):
    """The wrapper returns non-empty assistant content."""
    mock_create.return_value = mock_mimo_response

    result = ask_mimo_pro("What is a unit test?")

    assert isinstance(result["content"], str)
    assert len(result["content"]) > 0

@patch("mimo_client.client.chat.completions.create")
def test_correct_model(mock_create, mock_mimo_response):
    """The response identifies MiMo-V2-Pro."""
    mock_create.return_value = mock_mimo_response

    result = ask_mimo_pro("Hello")

    assert result["model"] == "mimo-v2-pro"

@patch("mimo_client.client.chat.completions.create")
def test_token_usage_for_pricing(mock_create, mock_mimo_response):
    """Token fields are available for cost tracking."""
    mock_create.return_value = mock_mimo_response

    result = ask_mimo_pro("Hello")

    assert result["total_tokens"] > 0
    assert (
        result["prompt_tokens"] + result["completion_tokens"]
        == result["total_tokens"]
    )

Run the test suite:

pytest test_mimo_client.py -v

Expected output:

test_mimo_client.py::test_returns_content        PASSED
test_mimo_client.py::test_correct_model          PASSED
test_mimo_client.py::test_token_usage_for_pricing PASSED

3 passed in 0.28s

Mocking the API client gives you code-level coverage without generating token costs during CI runs.

Production Best Practices

1. Log Token Usage Per Request

Record prompt_tokens, completion_tokens, and total_tokens for every API call.

For MiMo-V2-Pro's lower tier:

Input tokens cost $1/1M.
Output tokens cost $3/1M.

Verbose prompts and large generated responses can increase cost quickly. Keep system prompts focused and set reasonable output limits.

2. Validate Requests Before Coding

Use Apidog to prototype requests before adding SDK code. Validate:

Authentication headers
Model IDs
Request-body schema
Multimodal input structure
Response fields
Token usage payloads

This reduces time spent debugging malformed requests in application code.

3. Separate Unit Tests from Live API Tests

Use unittest.mock and pytest for unit tests. Reserve live API calls for manual checks or explicitly marked integration tests.

A practical split is:

Unit tests: mock the API client.
Apidog tests: validate request and response contracts.
Integration tests: call the real endpoint only when required.

4. Match the Model to the Workload

Use MiMo-V2-Pro for:

Code generation and review
Multi-step reasoning
Planning workflows
Long-context text analysis

Use MiMo-V2-Omni for:

Image understanding
Audio transcription
Video analysis
Cross-modal workflows

Avoid using a multimodal model for text-only workloads when a text model is sufficient.

5. Stay Under 256K Context When Possible

MiMo-V2-Pro pricing doubles in the 256K–1M context tier. For retrieval-augmented generation workflows, retrieve only the most relevant chunks instead of including every available document.

6. Reuse Existing OpenAI SDK Patterns

Because the MiMo API is OpenAI-compatible, existing OpenAI SDK code can often be adapted by changing:

base_url="https://api.xiaomimimo.com/v1"

and selecting the appropriate MiMo model:

model="mimo-v2-pro"

Conclusion

MiMo-V2-Pro costs $1/1M input tokens and $3/1M output tokens for contexts up to 256K tokens, with higher rates for 256K–1M-token requests. MiMo-V2-Omni extends the API to multimodal inputs, including text, images, audio, and video.

A practical implementation workflow is:

Prototype the request in Apidog.
Add response and token-usage assertions.
Implement the request with the OpenAI Python SDK.
Mock the API client in pytest tests.
Monitor token usage in production.

Start by validating the endpoint and payload format, then move the tested request into your application code.

FAQ

What is MiMo-V2-Pro pricing?

MiMo-V2-Pro costs $1/1M input tokens and $3/1M output tokens for contexts up to 256K tokens. For contexts between 256K and 1M tokens, it costs $2/1M input tokens and $6/1M output tokens.

What is MiMo-V2-Omni pricing?

MiMo-V2-Omni pricing is comparable to MiMo-V2-Pro for text inputs. Images, audio, and video are tokenized and billed alongside text. Check platform.xiaomimimo.com for current rates.

How do I use the MiMo-V2-Pro API?

Use the OpenAI Python SDK with:

base_url="https://api.xiaomimimo.com/v1"

Then send a chat completion request with:

model="mimo-v2-pro"

Use Apidog to validate the request format and response before integrating it into your application.

How do I write a unit test for the MiMo API?

Mock client.chat.completions.create with unittest.mock, then assert on your wrapper function's returned content, model ID, and token usage. In Apidog, add JavaScript assertions in the Tests tab.

What is the difference between MiMo-V2-Pro and MiMo-V2-Omni?

MiMo-V2-Pro is a text-only reasoning model with 1T parameters and a 1M-token context window. MiMo-V2-Omni is a multimodal model that natively handles text, images, audio, and video.

How does MiMo-V2-Pro compare with MiMo-V2-Flash?

MiMo-V2-Flash costs $0.10/1M input tokens and $0.30/1M output tokens. MiMo-V2-Pro costs more but provides stronger reasoning and a 1M-token context window. Choose based on the complexity and context requirements of the task.

Where can I access the MiMo API?

The MiMo API is available at platform.xiaomimimo.com. MiMo-V2-Pro and MiMo-V2-Omni are also accessible through third-party providers such as OpenRouter and Vercel AI Gateway.

GPT-5.4 mini Pricing and How to Use GPT-5.4 mini API

Preecha — Thu, 06 Aug 2026 01:01:59 +0000

L;DR

GPT-5.4 mini costs $0.75 per 1M input tokens and $4.50 per 1M output tokens, with a 400k context window and 2x the speed of GPT-5 mini. Call it with the gpt-5.4-mini model ID through OpenAI's API, then validate responses visually in Apidog or programmatically with Python and pytest.

Try Apidog today

Introduction

OpenAI announced GPT-5.4 mini in March 2026 as its most capable small model yet, bringing near-flagship intelligence at a lower cost. This guide covers GPT-5.4 mini pricing, API capabilities, and two integration paths:

Test requests and assertions in Apidog.
Build and test a Python integration with pytest.

Before calling the API, download Apidog for free. You can test prompts, inspect responses, add unit test assertions, and review token usage visually without writing code.

GPT-5.4 mini Pricing Breakdown

Input and output token costs

GPT-5.4 mini pricing:

Input tokens: $0.75 per 1M tokens
Output tokens: $4.50 per 1M tokens
Context window: 400,000 tokens

For regional processing, OpenAI applies a 10% uplift:

Regional input tokens: $0.825 per 1M tokens
Regional output tokens: $4.95 per 1M tokens

GPT-5.4 mini vs. GPT-5.4 nano

Model	Input (per 1M tokens)	Output (per 1M tokens)	Context window
GPT-5.4	~$5.00	~$20.00	400k
GPT-5.4 mini	$0.75	$4.50	400k
GPT-5.4 nano	$0.20	$1.25	400k

GPT-5.4 nano is the lower-cost option. GPT-5.4 mini is positioned between cost and capability for coding, reasoning, and multimodal tasks where nano may not be sufficient.

GPT-5.4 mini in Codex

In OpenAI's Codex environment, GPT-5.4 mini consumes 30% of the GPT-5.4 quota. A practical multi-agent split is:

Use GPT-5.4 for planning and coordination.
Use GPT-5.4 mini for parallel, narrowly scoped subtasks.

GPT-5.4 mini API Capabilities

GPT-5.4 mini supports:

Text and image inputs
Tool use and function calling
Structured outputs for agentic workflows
Web search
File search over uploaded documents
Computer use
Skills for composable task modules

The model runs more than 2x faster than GPT-5 mini and approaches GPT-5.4 performance on benchmarks including SWE-Bench Pro and OSWorld-Verified.

Use this model ID in API requests:

gpt-5.4-mini

How to Use GPT-5.4 mini API with Apidog

Apidog provides a GUI workflow for creating, sending, debugging, and testing API requests. Use it to validate your request format and response schema before wiring the API into application code.

Create the request

Open Apidog and create a project, such as GPT-5.4 mini API Test.
Create a new HTTP request with these settings:

Setting	Value
Method	`POST`
URL	`https://api.openai.com/v1/chat/completions`

Add these headers:

Key	Value
`Authorization`	`Bearer YOUR_OPENAI_API_KEY`
`Content-Type`	`application/json`

Under Body → JSON, add this request body:

{
  "model": "gpt-5.4-mini",
  "messages": [
    {
      "role": "user",
      "content": "Explain what a unit test is in one sentence."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 200
}

Click Send.

Apidog displays the full response, including token usage. Use the returned usage values to estimate request costs.

Example response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "A unit test is an automated check that verifies a single function or component behaves as expected in isolation."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 28,
    "total_tokens": 46
  }
}

Add response assertions in Apidog

Open the Tests tab and add assertions for the response status, model, content, and token usage:

// Verify HTTP status
pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

// Confirm the requested model was used
pm.test("GPT-5.4 mini API model is correct", function () {
  const json = pm.response.json();
  pm.expect(json.model).to.include("gpt-5.4-mini");
});

// Verify the response contains assistant content
pm.test("Response has assistant message", function () {
  const json = pm.response.json();
  pm.expect(json.choices[0].message.content)
    .to.be.a("string")
    .and.not.empty;
});

// Verify token usage is returned
pm.test("Token usage is present", function () {
  const json = pm.response.json();
  pm.expect(json.usage.total_tokens).to.be.above(0);
});

These assertions validate the core integration contract:

The request succeeded.
The expected model handled the request.
The API returned assistant content.
Token usage is available for cost tracking.

Save the request in an Apidog test suite to run it through CI/CD using Apidog's CLI runner.

How to Use GPT-5.4 mini API with Python

For production code, install the OpenAI SDK and pytest:

pip install openai pytest

Create a GPT-5.4 mini client

Create gpt54mini_client.py:

from openai import OpenAI

client = OpenAI()  # Reads OPENAI_API_KEY from the environment

def ask_gpt54_mini(prompt: str) -> dict:
    """Call GPT-5.4 mini and return content plus usage metadata."""
    response = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=[
            {"role": "user", "content": prompt}
        ],
        temperature=0.7,
        max_tokens=500
    )

    return {
        "content": response.choices[0].message.content,
        "model": response.model,
        "total_tokens": response.usage.total_tokens,
        "prompt_tokens": response.usage.prompt_tokens,
        "completion_tokens": response.usage.completion_tokens,
    }

if __name__ == "__main__":
    result = ask_gpt54_mini("What is a unit test?")
    print(result["content"])

    input_cost = (result["prompt_tokens"] / 1_000_000) * 0.75
    output_cost = (result["completion_tokens"] / 1_000_000) * 4.50

    print(f"Estimated cost: ${input_cost + output_cost:.6f}")

Set your API key before running the script:

export OPENAI_API_KEY="your_api_key"
python gpt54mini_client.py

Unit test the integration without calling the API

Mock the client so CI does not consume tokens. Create test_gpt54mini_client.py:

import pytest
from unittest.mock import MagicMock, patch

from gpt54mini_client import ask_gpt54_mini

@pytest.fixture
def mock_openai_response():
    """Mock a GPT-5.4 mini API response."""
    mock_response = MagicMock()
    mock_response.choices[0].message.content = (
        "A unit test verifies a single function in isolation."
    )
    mock_response.model = "gpt-5.4-mini"
    mock_response.usage.total_tokens = 46
    mock_response.usage.prompt_tokens = 18
    mock_response.usage.completion_tokens = 28
    return mock_response

@patch("gpt54mini_client.client.chat.completions.create")
def test_returns_content(mock_create, mock_openai_response):
    """GPT-5.4 mini returns non-empty content."""
    mock_create.return_value = mock_openai_response

    result = ask_gpt54_mini("What is a unit test?")

    assert isinstance(result["content"], str)
    assert len(result["content"]) > 0

@patch("gpt54mini_client.client.chat.completions.create")
def test_correct_model(mock_create, mock_openai_response):
    """The response identifies GPT-5.4 mini."""
    mock_create.return_value = mock_openai_response

    result = ask_gpt54_mini("Hello")

    assert result["model"] == "gpt-5.4-mini"

@patch("gpt54mini_client.client.chat.completions.create")
def test_token_usage_reported(mock_create, mock_openai_response):
    """Token usage is available for pricing calculations."""
    mock_create.return_value = mock_openai_response

    result = ask_gpt54_mini("Hello")

    assert result["total_tokens"] > 0
    assert result["prompt_tokens"] + result["completion_tokens"] == result["total_tokens"]

Run the tests:

pytest test_gpt54mini_client.py -v

Expected output:

test_gpt54mini_client.py::test_returns_content      PASSED
test_gpt54mini_client.py::test_correct_model        PASSED
test_gpt54mini_client.py::test_token_usage_reported PASSED

3 passed in 0.31s

Mocking API calls keeps test suites fast and prevents token usage during CI runs.

GPT-5.4 mini API Best Practices

1. Track input and output tokens

Log prompt_tokens and completion_tokens for every request. Input tokens cost $0.75 per 1M tokens, while output tokens cost $4.50 per 1M tokens.

Keep prompts and system instructions focused, especially for high-volume workloads.

2. Prototype requests before writing integration code

Use Apidog to verify:

Request headers
JSON payload structure
Response shape
Token usage fields
Error responses

This helps catch request issues before they reach application code.

3. Mock API calls in unit tests

Do not call the live API in standard unit tests. Mock the API client and test your own behavior around:

Parsing assistant content
Handling response metadata
Tracking token counts
Propagating errors

Use live calls separately for integration or smoke tests.

4. Use the 400k context window selectively

GPT-5.4 mini supports 400k tokens of context, but all processed tokens affect cost. In RAG pipelines, retrieve only the most relevant chunks instead of sending every available document.

5. Use regional endpoints only when necessary

Regional processing adds a 10% uplift. Use data residency endpoints when compliance requirements require them.

6. Delegate focused agent tasks to GPT-5.4 mini

For multi-agent workflows, reserve GPT-5.4 for planning and coordination. Route parallel, high-frequency subtasks to GPT-5.4 mini.

Conclusion

GPT-5.4 mini costs $0.75 per 1M input tokens and $4.50 per 1M output tokens, with a 400k-token context window. It supports multimodal inputs, function calling, web search, file search, computer use, and skills.

Start by validating requests in Apidog, including response assertions and token usage checks. Then move to a Python integration with mocked unit tests so your CI pipeline stays fast and does not consume API tokens.

FAQ

What is GPT-5.4 mini pricing?

GPT-5.4 mini costs $0.75 per 1M input tokens and $4.50 per 1M output tokens. Regional processing endpoints add a 10% uplift.

What is the GPT-5.4 mini API model ID?

Use gpt-5.4-mini as the model parameter.

How do I test GPT-5.4 mini without writing code?

Use Apidog to create a POST request to:

https://api.openai.com/v1/chat/completions

Set the model to gpt-5.4-mini, send the request, and add assertions in the Tests tab.

How do I write a unit test for GPT-5.4 mini?

In Python, mock the OpenAI client with unittest.mock and assert against the response data your code returns. In Apidog, add JavaScript assertions in the Tests tab.

How does GPT-5.4 mini compare with GPT-5.4 nano?

GPT-5.4 nano costs $0.20 per 1M input tokens and $1.25 per 1M output tokens. GPT-5.4 mini costs more but provides stronger capability for coding and reasoning tasks.

Can I use GPT-5.4 mini in Codex?

Yes. GPT-5.4 mini is available in Codex and consumes 30% of the GPT-5.4 quota.

Is GPT-5.4 mini available in ChatGPT?

Yes. GPT-5.4 mini is available through the OpenAI API, Codex, and ChatGPT.

How to Use Firebase API: Complete Integration Guide (2026)

Preecha — Wed, 05 Aug 2026 13:02:49 +0000

You’re building an app. Users need to sign in, data needs to sync in real time, and files need storage. You can spend weeks managing servers, databases, and infrastructure—or use Firebase.

Try Apidog today

Firebase powers over 1.5 million apps, including The New York Times, Duolingo, and Alibaba. Its SDKs remove much of the backend setup so you can focus on features instead of server maintenance. The tradeoff is that Firebase has important implementation details: authentication flows, database rules, query constraints, and Cloud Function triggers can all cause production issues if you treat them as magic.

This guide walks through Firebase Authentication, Firestore, Cloud Functions, and Cloud Storage with working JavaScript examples. It also covers security rules, testing, common failures, and production patterns.

💡 Testing Firebase APIs is easier with an API client. Apidog can help you organize endpoints, test authentication flows, and share request collections with your team.

What Is the Firebase API?

Firebase is not a single API. It is a set of backend services available through Firebase SDKs, REST endpoints, and deployment tooling.

Core Firebase Services

Service	Purpose	API type
Authentication	User sign-in and identity	SDK + REST
Firestore Database	NoSQL document database	SDK + REST
Realtime Database	JSON real-time synchronization	SDK + REST
Cloud Storage	File storage and CDN delivery	SDK + REST
Cloud Functions	Serverless compute	Deployment CLI
Hosting	Static web hosting	Deployment CLI
Cloud Messaging	Push notifications	HTTP v1 API

When Firebase Makes Sense

Use Firebase when you need:

Real-time synchronization for chat, collaboration, or live updates.
A serverless architecture without managing infrastructure.
Mobile and web SDKs that handle platform differences.
Offline support through SDK caching.
Built-in authentication for Google, Apple, email/password, or phone sign-in.

Consider another approach when you need:

Complex relational queries—PostgreSQL is often a better fit.
Strict data-residency requirements.
Full SQL capabilities.
Lower infrastructure costs at very large scale, where self-hosting may be cheaper.

Firebase Architecture

Firebase client SDKs handle authentication tokens, offline caching, and real-time listeners. Under the hood, client operations become authenticated API requests over HTTPS and WebSockets.

┌─────────────────────────────────────────────────────────┐
│                    Your Application                      │
├─────────────────────────────────────────────────────────┤
│  Firebase SDK (Client)                                   │
│  - Auto-handles auth tokens                              │
│  - Manages offline cache                                 │
│  - Real-time listeners                                   │
└─────────────────────────────────────────────────────────┘
                          │
                          │ HTTPS + WebSocket
                          ▼
┌─────────────────────────────────────────────────────────┐
│                   Firebase Backend                       │
├──────────────┬──────────────┬──────────────┬────────────┤
│   Auth       │  Firestore   │   Storage    │ Functions  │
│   Service    │  Database    │   Service    │  Runtime   │
└──────────────┴──────────────┴──────────────┴────────────┘

Firebase Authentication: Complete Setup

Authentication is usually the first Firebase integration. Set it up before writing database rules or protected backend endpoints.

Step 1: Create a Firebase Project

Open the Firebase Console.
Click Add project.
Enter a project name without spaces.

Enable Google Analytics if needed.

Click Create project.

Wait for provisioning to finish, then open the project dashboard.

Step 2: Register Your App

Web

In Firebase Console → Project Settings → General:

Click Add app.
Choose the Web icon.
Copy the generated configuration into your application.

const firebaseConfig = {
  apiKey: "AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  authDomain: "your-app.firebaseapp.com",
  projectId: "your-app",
  storageBucket: "your-app.appspot.com",
  messagingSenderId: "123456789012",
  appId: "1:123456789012:web:abc123def456"
};

import { initializeApp } from "firebase/app";

const app = initializeApp(firebaseConfig);

iOS

Download GoogleService-Info.plist and add it to your Xcode project. Confirm that Target Membership includes your app target.

Android

Download google-services.json and place it in your app module directory.

Add the Google Services plugin:

// Project-level build.gradle
buildscript {
    dependencies {
        classpath 'com.google.gms:google-services:4.4.0'
    }
}

// App-level build.gradle
plugins {
    id 'com.google.gms.google-services'
}

Step 3: Enable Sign-In Methods

In Firebase Console → Authentication → Sign-in method, enable the providers your app needs:

Email/Password for standard account registration.
Google for Google OAuth. Configure SHA-1 fingerprints on Android or bundle IDs on iOS.
Apple when required for iOS apps that offer other social login providers.
Phone for SMS-based sign-in. This requires billing.

Step 4: Implement Email and Password Sign-Up

import {
  createUserWithEmailAndPassword,
  getAuth,
  updateProfile
} from "firebase/auth";

const auth = getAuth(app);

async function signUp(email, password, displayName) {
  try {
    const userCredential = await createUserWithEmailAndPassword(
      auth,
      email,
      password
    );

    await updateProfile(userCredential.user, {
      displayName
    });

    console.log("User created:", userCredential.user.uid);

    return userCredential.user;
  } catch (error) {
    switch (error.code) {
      case "auth/email-already-in-use":
        throw new Error("This email is already registered");
      case "auth/weak-password":
        throw new Error("Password must be at least 6 characters");
      case "auth/invalid-email":
        throw new Error("Invalid email address");
      default:
        throw new Error(`Sign up failed: ${error.message}`);
    }
  }
}

Step 5: Implement Sign-In and Sign-Out

import {
  signInWithEmailAndPassword,
  signOut
} from "firebase/auth";

async function signIn(email, password) {
  try {
    const userCredential = await signInWithEmailAndPassword(
      auth,
      email,
      password
    );

    const user = userCredential.user;

    // Use this token when calling your own protected APIs.
    const idToken = await user.getIdToken();

    console.log("Auth token:", idToken);

    return user;
  } catch (error) {
    switch (error.code) {
      case "auth/user-not-found":
        throw new Error("No account with this email");
      case "auth/wrong-password":
        throw new Error("Incorrect password");
      case "auth/too-many-requests":
        throw new Error("Too many attempts. Try again later");
      default:
        throw new Error("Sign in failed");
    }
  }
}

async function logOut() {
  await signOut(auth);
  console.log("User signed out");
}

Step 6: Add Google Sign-In for Web

import {
  GoogleAuthProvider,
  signInWithPopup
} from "firebase/auth";

async function signInWithGoogle() {
  const provider = new GoogleAuthProvider();

  provider.addScope("email");
  provider.addScope("profile");

  try {
    const result = await signInWithPopup(auth, provider);
    const user = result.user;

    const credential = GoogleAuthProvider.credentialFromResult(result);
    const googleAccessToken = credential.accessToken;

    return user;
  } catch (error) {
    if (error.code === "auth/popup-closed-by-user") {
      throw new Error("Sign-in cancelled");
    }

    throw new Error("Google sign-in failed");
  }
}

Step 7: Protect Routes with Authentication State

Subscribe once to authentication state changes and redirect users based on the current session.

import { onAuthStateChanged } from "firebase/auth";

onAuthStateChanged(auth, (user) => {
  if (user) {
    console.log("User:", user.email);
    window.location.href = "/dashboard";
    return;
  }

  console.log("No user");
  window.location.href = "/login";
});

Common Authentication Mistakes

Do not cache ID tokens indefinitely

Firebase SDKs refresh tokens automatically. If your server caches a token, it expires after one hour. Verify the token on every protected request, or implement explicit refresh logic.

Never expose service account credentials

Do not add Firebase Admin SDK keys to browser, iOS, or Android code. Service accounts bypass Firebase Security Rules and must only run in trusted server environments.

Require email verification when appropriate

import { sendEmailVerification } from "firebase/auth";

async function sendVerificationEmail(user) {
  await sendEmailVerification(user);
  console.log("Verification email sent");
}

if (!auth.currentUser.emailVerified) {
  console.log("Email not verified");
  // Restrict access to verification-required features.
}

Firestore Database: Documents, Queries, and Rules

Firestore is Firebase’s NoSQL document database. Data is organized into collections and documents, with optional subcollections.

Example Data Structure

your-project
└── users
    ├── userId123
    │   ├── name: "John"
    │   ├── email: "john@example.com"
    │   └── posts
    │       ├── postId1
    │       └── postId2
    └── userId456

Initialize Firestore

import { getFirestore } from "firebase/firestore";

const db = getFirestore(app);

Create Documents

Use addDoc() when Firestore should generate the document ID. Use setDoc() when you already have a stable ID, such as the authenticated user UID.

import {
  addDoc,
  collection,
  doc,
  setDoc
} from "firebase/firestore";

// Auto-generated ID
async function createUser(userData) {
  const docRef = await addDoc(collection(db, "users"), userData);

  console.log("Document written with ID:", docRef.id);

  return docRef.id;
}

// Custom ID
async function createUserWithId(userId, userData) {
  await setDoc(doc(db, "users", userId), userData);

  console.log("Document written with custom ID:", userId);
}

const userId = await createUser({
  name: "Alice",
  email: "alice@example.com",
  createdAt: new Date(),
  role: "user"
});

Read Documents and Query Collections

import {
  collection,
  doc,
  getDoc,
  getDocs,
  limit,
  orderBy,
  query,
  where
} from "firebase/firestore";

async function getUser(userId) {
  const docRef = doc(db, "users", userId);
  const docSnap = await getDoc(docRef);

  if (!docSnap.exists()) {
    throw new Error("User not found");
  }

  return docSnap.data();
}

async function getUsersByRole(role) {
  const q = query(
    collection(db, "users"),
    where("role", "==", role),
    orderBy("createdAt", "desc"),
    limit(10)
  );

  const querySnapshot = await getDocs(q);

  return querySnapshot.docs.map((document) => ({
    id: document.id,
    ...document.data()
  }));
}

const adminUsers = await getUsersByRole("admin");
console.log("Admin users:", adminUsers);

Update Documents with Atomic Operations

Use Firestore atomic operators for counters and arrays rather than reading, modifying, and writing values manually.

import {
  arrayRemove,
  arrayUnion,
  doc,
  increment,
  updateDoc
} from "firebase/firestore";

async function updateUser(userId, updates) {
  const userRef = doc(db, "users", userId);
  await updateDoc(userRef, updates);
}

await updateUser("userId123", {
  loginCount: increment(1),
  tags: arrayUnion("premium", "beta-tester"),
  lastLogin: new Date()
});

await updateUser("userId123", {
  tags: arrayRemove("beta-tester")
});

Delete Documents

import { deleteDoc, doc } from "firebase/firestore";

async function deleteUser(userId) {
  await deleteDoc(doc(db, "users", userId));
  console.log("User deleted");
}

Subscribe to Real-Time Changes

Always keep the unsubscribe function and call it when a component unmounts or a page no longer needs the listener.

import {
  collection,
  doc,
  onSnapshot,
  query,
  where
} from "firebase/firestore";

const unsubscribe = onSnapshot(
  doc(db, "users", userId),
  (document) => {
    console.log("User updated:", document.data());
  },
  (error) => {
    console.error("Listen error:", error);
  }
);

const q = query(
  collection(db, "posts"),
  where("published", "==", true)
);

const unsubscribeQuery = onSnapshot(q, (snapshot) => {
  const posts = snapshot.docs.map((document) => ({
    id: document.id,
    ...document.data()
  }));

  console.log("Published posts:", posts);
});

// Call these when listeners are no longer needed.
unsubscribe();
unsubscribeQuery();

Secure Firestore with Rules

Without rules, clients may be able to read or modify data they should not access. Configure rules in Firebase Console → Firestore Database → Rules.

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    function isAuthenticated() {
      return request.auth != null;
    }

    function isOwner(userId) {
      return request.auth.uid == userId;
    }

    match /users/{userId} {
      allow read: if isAuthenticated();
      allow create: if isAuthenticated() && isOwner(userId);
      allow update, delete: if isOwner(userId);
    }

    match /posts/{postId} {
      allow read: if true;
      allow create: if isAuthenticated();
      allow update, delete: if resource.data.authorId == request.auth.uid;
    }

    match /users/{userId}/private/{document} {
      allow read, write: if isOwner(userId);
    }
  }
}

Firestore Query Constraints

Plan data models around Firestore limitations:

No arbitrary OR queries. Use in queries or combine multiple requests.
No wildcard or full-text search. Use Algolia or Meilisearch for search.
Multi-field queries may require composite indexes.
in queries support up to 30 disjunctions.

For example, run separate queries and merge results when you need an OR condition:

const activeQuery = query(
  collection(db, "tasks"),
  where("status", "==", "active")
);

const pendingQuery = query(
  collection(db, "tasks"),
  where("status", "==", "pending")
);

const [activeSnap, pendingSnap] = await Promise.all([
  getDocs(activeQuery),
  getDocs(pendingQuery)
]);

const tasks = [
  ...activeSnap.docs,
  ...pendingSnap.docs
].map((document) => ({
  id: document.id,
  ...document.data()
}));

Cloud Functions: Serverless Backend Logic

Cloud Functions run backend code without managing servers. You can trigger functions from HTTP requests, Firestore changes, and schedules.

Set Up Cloud Functions

# Install Firebase CLI
npm install -g firebase-tools

# Authenticate
firebase login

# Initialize Functions
firebase init functions

During setup, select:

JavaScript
ESLint: Yes
Express.js: No

Create HTTP API Endpoints

Use the Admin SDK inside Cloud Functions for trusted server-side operations.

// functions/index.js
const { onRequest } = require("firebase-functions/v2/https");
const admin = require("firebase-admin");

admin.initializeApp();

const db = admin.firestore();

exports.getPublicData = onRequest(async (req, res) => {
  res.set("Access-Control-Allow-Origin", "*");

  try {
    const snapshot = await db.collection("public").get();

    const data = snapshot.docs.map((document) => document.data());

    res.json({
      success: true,
      data
    });
  } catch (error) {
    res.status(500).json({
      error: error.message
    });
  }
});

exports.getUserProfile = onRequest(async (req, res) => {
  res.set("Access-Control-Allow-Origin", "*");

  const authHeader = req.headers.authorization || "";
  const token = authHeader.split("Bearer ")[1];

  if (!token) {
    return res.status(401).json({
      error: "Unauthorized"
    });
  }

  try {
    const decodedToken = await admin.auth().verifyIdToken(token);
    const userId = decodedToken.uid;

    const userDoc = await db.collection("users").doc(userId).get();

    if (!userDoc.exists) {
      return res.status(404).json({
        error: "User not found"
      });
    }

    return res.json({
      success: true,
      data: {
        id: userId,
        ...userDoc.data()
      }
    });
  } catch (error) {
    return res.status(401).json({
      error: "Invalid token"
    });
  }
});

Deploy a single function:

firebase deploy --only functions:getUserProfile

Call it from the client with the Firebase ID token:

async function getUserProfile(token) {
  const response = await fetch(
    "https://us-central1-your-app.cloudfunctions.net/getUserProfile",
    {
      headers: {
        Authorization: `Bearer ${token}`
      }
    }
  );

  return response.json();
}

Trigger Functions from Firestore Changes

const { onDocumentWritten } = require("firebase-functions/v2/firestore");

exports.onUserUpdate = onDocumentWritten(
  "users/{userId}",
  async (event) => {
    const userId = event.params.userId;
    const before = event.data?.before?.data();
    const after = event.data?.after?.data();

    if (before?.email !== after?.email) {
      console.log(
        `User ${userId} email changed: ${before?.email} → ${after?.email}`
      );

      await admin.auth().getUser(userId);

      // Add email notification logic here.
    }
  }
);

exports.onNewPost = onDocumentWritten(
  "posts/{postId}",
  async (event) => {
    const post = event.data?.after?.data();

    if (!post) {
      return;
    }

    if (!event.data?.before?.exists) {
      console.log("New post created:", post.title);

      const followersSnap = await admin
        .firestore()
        .collection("users")
        .where("following", "array-contains", post.authorId)
        .get();

      const notifications = followersSnap.docs.map((document) => ({
        userId: document.id,
        postId: event.params.postId,
        type: "new_post",
        createdAt: admin.firestore.FieldValue.serverTimestamp()
      }));

      const batch = admin.firestore().batch();

      notifications.forEach((notification) => {
        const ref = admin.firestore().collection("notifications").doc();
        batch.set(ref, notification);
      });

      await batch.commit();
    }
  }
);

Run Scheduled Jobs

const { onSchedule } = require("firebase-functions/v2/scheduler");

exports.dailyCleanup = onSchedule("every 24 hours", async () => {
  console.log("Running daily cleanup");

  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const oldNotifs = await admin
    .firestore()
    .collection("notifications")
    .where("createdAt", "<", thirtyDaysAgo)
    .get();

  const batch = admin.firestore().batch();

  oldNotifs.forEach((document) => batch.delete(document.ref));

  await batch.commit();

  console.log(`Deleted ${oldNotifs.size} old notifications`);
});

Configure Environment Variables

firebase functions:config:set \
  stripe.secret="sk_test_xxx" \
  email.api_key="key_xxx"

Access configuration from the function:

const config = require("firebase-functions/config");
const stripe = require("stripe")(config.stripe.secret);

Cloud Storage: Upload, Download, and Delete Files

Cloud Storage is useful for user uploads, images, and other files. Firebase handles storage access through SDKs and can distribute content through a CDN.

Configure Storage Rules

Set rules in Firebase Console → Storage → Rules.

rules_version = '2';

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/{allPaths=**} {
      allow read: if true;
      allow write: if request.auth.uid == userId;
      allow delete: if request.auth.uid == userId;
    }

    match /public/{allPaths=**} {
      allow read: if true;
      allow write: if false;
    }
  }
}

Upload Files from the Client

import {
  getDownloadURL,
  getStorage,
  ref,
  uploadBytesResumable
} from "firebase/storage";

const storage = getStorage(app);

async function uploadProfileImage(userId, file) {
  const storageRef = ref(
    storage,
    `users/${userId}/profile/${file.name}`
  );

  const uploadTask = uploadBytesResumable(storageRef, file);

  return new Promise((resolve, reject) => {
    uploadTask.on(
      "state_changed",
      (snapshot) => {
        const progress =
          (snapshot.bytesTransferred / snapshot.totalBytes) * 100;

        console.log(`Upload: ${progress.toFixed(0)}%`);
      },
      (error) => {
        switch (error.code) {
          case "storage/unauthorized":
            reject(new Error("You do not have permission"));
            break;
          case "storage/canceled":
            reject(new Error("Upload cancelled"));
            break;
          default:
            reject(new Error("Upload failed"));
        }
      },
      async () => {
        const downloadURL = await getDownloadURL(uploadTask.snapshot.ref);

        console.log("File available at:", downloadURL);

        resolve(downloadURL);
      }
    );
  });
}

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

if (file) {
  const imageUrl = await uploadProfileImage(
    auth.currentUser.uid,
    file
  );

  await updateDoc(doc(db, "users", auth.currentUser.uid), {
    profileImage: imageUrl
  });
}

Download Files

import { getDownloadURL, ref } from "firebase/storage";

async function getProfileImage(userId) {
  const imageRef = ref(
    storage,
    `users/${userId}/profile/avatar.png`
  );

  try {
    return await getDownloadURL(imageRef);
  } catch (error) {
    if (error.code === "storage/object-not-found") {
      return null;
    }

    throw error;
  }
}

Delete Files

import { deleteObject, ref } from "firebase/storage";

async function deleteProfileImage(userId) {
  const imageRef = ref(
    storage,
    `users/${userId}/profile/avatar.png`
  );

  await deleteObject(imageRef);

  console.log("Profile image deleted");
}

Testing Firebase APIs with Apidog

Firebase exposes REST APIs for its services. Calling them directly is useful for debugging SDK behavior, validating tokens, and understanding request payloads.

Add Firebase REST Requests

In Apidog:

Create a project named Firebase API.
Import an OpenAPI specification from Firebase documentation, or add requests manually.
Create environments for your Firebase project ID, API key, and auth token.

Example Firestore REST request:

POST https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents
Authorization: Bearer {oauth2_token}
Content-Type: application/json

{
  "fields": {
    "name": { "stringValue": "John" },
    "email": { "stringValue": "john@example.com" },
    "age": { "integerValue": 30 }
  }
}

Example Authentication request:

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={api_key}
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret123",
  "returnSecureToken": true
}

Test an Authentication Flow

Create a Sign In request.
Set the method to POST.
Add the email and password JSON body.
Save the returned token as an environment variable.
Use {{token}} in the Authorization header of protected requests.

Test Rules Locally with the Emulator Suite

firebase emulators:start

The local Firestore emulator runs at:

http://localhost:8080

Use the emulator before deploying rule changes to production.

Production Best Practices

1. Retry Transient Firestore Failures

Retry only temporary failures such as unavailable services and deadlines.

async function firestoreWithRetry(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (
        error.code === "unavailable" ||
        error.code === "deadline-exceeded"
      ) {
        const delay = Math.pow(2, i) * 1000;

        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      throw error;
    }
  }
}

2. Create Composite Indexes for Multi-Field Queries

This query needs a composite index:

const q = query(
  collection(db, "posts"),
  where("category", "==", "tech"),
  where("views", ">", 1000),
  orderBy("views", "desc")
);

Firestore provides a direct index-creation link when a query requires one.

3. Use Batch Writes

Use batch writes when updating multiple documents together.

import {
  doc,
  writeBatch
} from "firebase/firestore";

async function bulkUpdate(userIds, updates) {
  const batch = writeBatch(db);

  userIds.forEach((id) => {
    const ref = doc(db, "users", id);
    batch.update(ref, updates);
  });

  await batch.commit();

  console.log(`Updated ${userIds.length} users`);
}

Firestore supports a maximum of 500 operations per batch.

4. Monitor Costs

Service	Free tier	Paid usage
Firestore	50K reads/day	$0.036/100K reads
Storage	5 GB	$0.023/GB
Functions	2M invocations	$0.40/1M
Auth	10K/month	$0.0055/100K

Set budget alerts in Google Cloud Console so unexpected traffic does not become an unexpected bill.

5. Keep Service Accounts on Trusted Servers

Never load service account files in client-side code.

// Wrong: never do this in browser, iOS, or Android code.
admin.initializeApp({
  credential: admin.credential.cert(
    require("./serviceAccountKey.json")
  )
});

Use environment-managed credentials only in server environments:

const serviceAccount = JSON.parse(
  process.env.FIREBASE_SERVICE_ACCOUNT
);

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
});

6. Handle Offline Scenarios

Enable multi-tab IndexedDB persistence for web applications:

import {
  enableMultiTabIndexedDbPersistence
} from "firebase/firestore";

enableMultiTabIndexedDbPersistence(db).catch((error) => {
  if (error.code === "failed-precondition") {
    // Multiple tabs are open.
  } else if (error.code === "unimplemented") {
    // Browser does not support persistence.
  }
});

You can also use document listeners to update offline UI state:

import {
  doc,
  onSnapshot
} from "firebase/firestore";

onSnapshot(doc(db, "status", "online"), (document) => {
  if (!document.exists()) {
    console.log("You are offline");
    // Show offline UI.
  }
});

Common Firebase API Issues and Fixes

Permission Denied Errors

Symptom

Error: 7 PERMISSION_DENIED

Cause: Firebase Security Rules block the operation.

Fix:

Review rules in Firebase Console.
Confirm request.auth.uid matches the expected user.
Test rules with the Rules Playground or Emulator Suite.

Expired Tokens

Symptom

Error: ID token expired

Force a token refresh before retrying the request:

const user = auth.currentUser;

if (user) {
  await user.getIdToken(true);
}

Cloud Function Cold Starts

Symptom: A Cloud Function takes 2–5 seconds on its first call.

You can schedule periodic health requests:

exports.keepWarm = onSchedule("every 60 seconds", async () => {
  await fetch("https://your-function.cloudfunctions.net/health");
});

Empty Firestore Query Results

Symptom: A query returns an empty array when you expect data.

Possible causes:

A missing composite index.
Incorrect field names or field ordering.
Security Rules preventing reads.

Check Firestore Console → Indexes and confirm the query matches the stored document shape.

Real-World Use Cases

Fintech: Real-Time Transaction Updates

A payment startup used Firebase Firestore for real-time transaction notifications. When a payment processes, Cloud Functions trigger updates to connected admin dashboards within 200ms. The result was a 40% reduction in support tickets about pending transactions.

E-Commerce: Inventory Synchronization

An online retailer synchronizes inventory across web, iOS, and Android clients with Firestore listeners. Stock changes appear across connected clients automatically. Offline persistence lets warehouse workers scan items without connectivity and sync changes when they reconnect.

SaaS: Multi-Tenant Authentication

A B2B platform uses Firebase Authentication with custom claims for role-based access. Cloud Functions validate permissions against Firestore tenant configurations. A single codebase serves more than 500 organizations while isolating tenant data.

Firebase handles real-time synchronization and authentication cleanly, but Firebase's biggest open-source rival takes a different approach to the same problems. A Supabase CLI workflow focuses on local development, migrations, and type generation on the Postgres side.

If your backend is a commerce platform, the integration model is different again. Magento 2 REST and GraphQL APIs use their own token flows and resource hierarchy, which need a separate setup pass.

Conclusion

A practical Firebase integration usually relies on four core services:

Authentication: Email, Google, Apple, and phone sign-in with JWT tokens.
Firestore: A NoSQL database with real-time listeners and Security Rules.
Cloud Functions: Serverless backend logic triggered by HTTP, events, or schedules.
Cloud Storage: File uploads and downloads with access rules.

Start with Authentication and Security Rules, then add Firestore data access, Cloud Functions for trusted backend logic, and Storage for uploads. Use retries, batch writes, indexes, offline support, and local emulators before shipping to production.

FAQ

Is Firebase free to use?

Yes. Firebase has a free Spark Plan that includes 5 GB of storage, 50K Firestore reads per day, 2M Cloud Function invocations, and 10K Auth users per month. The Blaze plan uses pay-as-you-go pricing.

Can I use Firebase with existing databases?

Yes. You can use Firebase Extensions to synchronize with PostgreSQL, MySQL, or MongoDB. You can also call external APIs from Cloud Functions.

How do I migrate from Firebase to another platform?

Export data with Firestore export functions or the Firebase CLI. For large datasets, use the Dataflow export pipeline. Migration complexity depends on your data model.

Does Firebase support GraphQL?

Not natively. Use a third-party option such as firestore-graphql, or build a GraphQL layer with Cloud Functions and Apollo Server.

Can I run Firebase on-premise?

No. Firebase runs on Google Cloud. For self-hosted alternatives, consider Appwrite, Supabase, or Nhost.

How do I upload files larger than 100 MB?

Use resumable uploads with chunking. The Firebase SDK handles resumable uploads automatically. For very large files, use Google Cloud Storage with signed URLs.

What happens if I exceed Firestore query limits?

The query fails with a FAILED_PRECONDITION error. Add the required index or restructure the query. Firestore error messages include direct links for creating missing indexes.

Is Firebase GDPR compliant?

Yes. Firebase offers GDPR-compliant data processing. Configure regional data residency where available, implement user-data export and deletion flows, and sign Google’s Data Processing Amendment.

What Is gstack? This will Change How you Code Forever

Preecha — Wed, 05 Aug 2026 01:02:29 +0000

TL;DR / Quick Answer

gstack is Garry Tan’s open-source system that turns Claude Code into a virtual engineering team of 20 specialists. As Y Combinator’s President and CEO, Garry ships 10,000–20,000 lines of production code per day (35% tests) while running YC full-time. gstack uses structured slash commands such as /office-hours for product strategy, /plan-ceo-review for scope validation, /review for bug detection, /qa for browser testing, and /ship for deployment. Install it with git clone ~/.claude/skills/gstack && ./setup. It is free and MIT licensed.

Try Apidog today

Introduction

“I don’t think I’ve typed like a line of code probably since December, basically, which is an extremely large change.”

When Andrej Karpathy said this on the No Priors podcast in March 2026, he described a major workflow shift: one developer using AI agents can ship at the pace of a much larger team.

Peter Steinberger demonstrated a similar model by building OpenClaw—247,000 GitHub stars—essentially solo with AI agents.

Garry Tan built gstack around that workflow. As President and CEO of Y Combinator, he works with startups such as Coinbase, Instacart, and Rippling at their earliest stages. Before YC, he was an early engineer at Palantir, cofounded Posterous (sold to Twitter), and built Bookface, YC’s internal social network.

gstack answers a practical question: how can one developer run a repeatable product, engineering, QA, security, and release process with AI agents?

According to Garry’s reported numbers from the last 60 days:

600,000+ lines of production code
35% test code
10,000–20,000 lines per day
Work completed part-time while running YC full-time
A recent /retro across three projects reported 140,751 lines added, 362 commits, and approximately 115k net LOC in one week

This guide shows how to install gstack, choose the right skills, and run an implementation workflow from idea to production.

💡 Building API products? gstack can fit into an API testing and documentation workflow. For example, use /qa to validate API-backed browser flows and /document-release to keep API documentation aligned with shipped changes.

What Is gstack?

gstack is an open-source collection of 28 Claude Code skills. Each skill gives the agent a specialized role, such as:

Product strategist
CEO or founder reviewer
Engineering manager
Product designer
Staff engineer
QA engineer
Security officer
Release engineer
SRE
Technical writer

The skills are invoked as slash commands and defined in Markdown. gstack is free and MIT licensed.

The Core Workflow

Most AI coding workflows start with a prompt and immediately generate code. gstack encourages a staged process:

Think → Plan → Build → Review → Test → Ship → Reflect

For example, instead of starting with:

Build a daily briefing app for my calendar.

start with:

/office-hours

I want to build a daily briefing app for people who manage multiple
Google calendars and need better meeting preparation.

The goal is to validate the problem before committing to implementation.

A typical feature workflow looks like this:

/office-hours
/plan-ceo-review
/plan-eng-review
/plan-design-review
# Implement the approved plan
/review
/qa https://staging.example.com
/ship
/document-release

Each stage produces context for the next one:

/office-hours creates a product-oriented design document.
/plan-ceo-review validates scope.
/plan-eng-review defines architecture, edge cases, and tests.
/review catches code-level issues.
/qa validates user flows in Chromium.
/ship runs tests and opens a pull request.
/document-release updates documentation.

The 28 Skills Explained

Product and Strategy Skills

`/office-hours` — YC Office Hours

Role: YC Partner

Use /office-hours at the beginning of a new feature, product, or major refactor.

It asks forcing questions, challenges your initial framing, and produces alternatives before you write code.

Example:

You said "daily briefing app." But what you actually described is a
personal chief of staff AI.

Here are five capabilities implied by the user problem...

[challenges four assumptions]
[generates three implementation approaches with effort estimates]

RECOMMENDATION: Ship the narrowest wedge tomorrow and learn from real
usage. The complete vision is a three-month project. Start with the
daily briefing that actually works.

Use it when:

Starting a new product idea
Planning a large feature
You have a feature request but unclear user pain
You want alternatives before implementation

`/plan-ceo-review` — CEO / Founder Review

Role: CEO who rethinks the product

Run this after /office-hours and before implementation.

It reviews the plan from first principles and selects one of four directions:

Expansion — Make the idea significantly more ambitious.
Selective Expansion — Expand only the highest-leverage parts.
Hold Scope — Keep the current plan.
Reduction — Cut most of the scope and ship a narrower wedge.

Use it when:

/office-hours
/plan-ceo-review

This is useful when a plan has become too broad, too safe, or too implementation-driven.

`/plan-design-review` — Senior Designer

Role: Senior Product Designer

This skill rates design dimensions from 0 to 10, explains what a 10 would look like, and updates the plan.

It also includes AI-slop detection and uses one AskUserQuestion per design decision.

Use it when:

A feature includes UI or UX changes
You need to review interaction design before coding
You want to catch design debt before it becomes code debt

/plan-design-review

`/design-consultation` — Design Partner

Role: Design Partner

Use this when you need a complete design system or a more comprehensive design exploration than /plan-design-review.

It can:

Research comparable products
Propose creative risks
Define visual direction
Generate realistic product mockups

/design-consultation

Create a design system for a calendar briefing product used by busy
startup founders. Prioritize dense information, calm hierarchy, and
fast scanning before meetings.

Engineering and Architecture Skills

`/plan-eng-review` — Engineering Manager

Role: Engineering Manager

Run /plan-eng-review after product and design reviews, but before coding.

It makes architecture decisions explicit by generating:

Data-flow diagrams
State-machine diagrams
Error paths
Edge cases
Test matrices
Security considerations

Example output:

Architecture Review:

┌─────────────┐     ┌──────────────┐     ┌────────────┐
│   Client    │────▶│  API Gateway │────▶│  Database  │
└─────────────┘     └──────────────┘     └────────────┘
       │                    │
       ▼                    ▼
  [State Cache]      [Rate Limiter]

Test Matrix:
- Happy path: authenticated user, valid data
- Edge case: concurrent modifications
- Failure mode: database connection timeout
- Security: SQL injection, XSS, CSRF

Recommended usage:

/plan-eng-review

Review the approved daily briefing plan. Include:
- calendar synchronization failure modes
- duplicate event handling
- rate limiting
- timezone handling
- test cases for stale event data

`/review` — Staff Engineer

Role: Staff Engineer focused on production bugs

Run /review after implementation and before QA.

It looks for bugs that may pass CI but fail under real production conditions. It can auto-fix obvious issues and ask for approval on riskier changes.

Example:

[AUTO-FIXED] 2 issues:
- Missing null check in getUserById()
- Unhandled promise rejection in API handler

[ASK] Race condition in concurrent update flow

[COMPLETENESS GAP] No retry logic for transient failures

Use it on a branch with changes:

/review

`/investigate` — Root-Cause Debugger

Role: Debugger

Use /investigate for issues that need systematic diagnosis.

Its core rule is:

No fixes without investigation.

It traces data flow, tests hypotheses, and stops after three failed fixes to avoid random patching.

Use it when:

/investigate

The calendar sync job intermittently creates duplicate briefing records.
Trace the job lifecycle, identify the root cause, and propose a fix only
after validating the failure path.

`/codex` — Second Opinion

Role: OpenAI Codex CLI

Use /codex as an independent review pass after /review, especially for critical paths.

Available modes include:

Review pass/fail gate
Adversarial challenge
Open consultation
Cross-model analysis when both /review and /codex have run

/review
/codex review

Use this for authentication, payments, authorization, migrations, or other high-risk code.

Testing and QA Skills

`/qa` — QA Lead

Role: QA Engineer with a real browser

/qa uses headless Chromium to execute real browser flows. It can find bugs, create atomic commits for fixes, re-verify them, and generate regression tests.

Example workflow:

1. Open the staging URL in Chromium
2. Execute the test plan from /plan-eng-review
3. Find a bug: submit button remains enabled while loading
4. Create an atomic fix commit
5. Re-run the flow and verify the fix
6. Generate a regression test

Run it against staging:

/qa https://staging.example.com

For API-backed applications, give QA concrete scenarios:

/qa https://staging.example.com

Test calendar connection, event sync, briefing generation, retry states,
empty-state UX, failed API responses, and logout/login behavior.

`/qa-only` — QA Reporter

Role: QA Reporter

/qa-only uses the same browser-based testing approach as /qa, but does not modify code.

Use it when you need a report for:

QA handoff
Audit trails
Bug triage
A separate engineer responsible for fixes

/qa-only https://staging.example.com

`/benchmark` — Performance Engineer

Role: Performance Engineer

Use /benchmark before and after significant rendering or performance work.

It tracks:

First Contentful Paint (FCP)
Largest Contentful Paint (LCP)
Cumulative Layout Shift (CLS)
Time to Interactive (TTI)
Bundle sizes

/benchmark https://staging.example.com

Run it:

Before a major refactor
After performance changes
On PRs that modify rendering, routing, or bundle composition

`/browse` — Browser Automation

Role: Browser Automation

/browse provides direct Chromium automation. It is used internally by /qa.

Common commands:

goto <url>
click <selector>
type <selector> <text>
screenshot <name>
wait <selector>

Example:

/browse goto https://staging.example.com/login
/browse type input[name="email"] dev@example.com
/browse type input[name="password"] password
/browse click button[type="submit"]
/browse wait [data-testid="dashboard"]
/browse screenshot dashboard-loaded

`/setup-browser-cookies` — Session Manager

Role: Browser Session Manager

Use this before browser QA if staging requires authentication.

It imports cookies from Chrome, Arc, Brave, or Edge into the headless browser session.

/setup-browser-cookies
/qa https://staging.example.com

Security and Compliance Skills

`/cso` — Chief Security Officer

Role: Chief Security Officer

/cso runs an OWASP Top 10 review and STRIDE threat model.

It uses a zero-noise approach:

17 false-positive exclusions
8/10 confidence threshold
Independent finding verification
Concrete exploit scenarios for findings

Example:

[CRITICAL] SQL Injection in /api/users?id= parameter

Exploit:
GET /api/users?id=1' OR '1'='1

Impact:
Full database read access

Fix:
Use parameterized queries

Confidence:
9/10

Run it before releasing features that involve:

Authentication
User data
Payments
File uploads
Admin panels
Public APIs

/cso

Shipping and Deployment Skills

`/ship` — Release Engineer

Role: Release Engineer

/ship moves a tested branch toward a pull request.

It can:

Sync main
Create or update a feature branch
Run tests
Bootstrap a test framework if needed
Audit coverage
Push the branch
Open a pull request

Example workflow:

1. git checkout main && git pull
2. git checkout -b feature/daily-briefing
3. npm test
4. Coverage audit: 42 tests → 51 tests (+9 new)
5. git push origin feature/daily-briefing
6. Open PR

Run it after /qa clears the branch:

/ship

`/land-and-deploy` — Deployment Engineer

Role: Deployment Engineer

Use /land-and-deploy after PR approval.

It can:

Merge the pull request
Wait for CI
Wait for deployment
Run production health checks
Report deployment status

/land-and-deploy

It supports workflows involving platforms such as GitHub Actions, CircleCI, Vercel, Railway, and Fly.io.

`/canary` — SRE

Role: Site Reliability Engineer

Run /canary immediately after deployment for a 5–15 minute monitoring loop.

It monitors:

Browser console errors
API error rates
Page-load regressions
JavaScript exceptions

/canary https://app.example.com

`/document-release` — Technical Writer

Role: Technical Writer

Run /document-release after shipping or deployment to keep docs synchronized with released behavior.

Example:

[UPDATED] README.md — added new /qa command to docs
[UPDATED] CHANGELOG.md — v0.4.2 release notes
[CREATED] docs/qa-guide.md — new QA workflow guide
[FLAGGED] API.md — may need update for new endpoints

/document-release

For API changes, use this after validating endpoint behavior and updating your API reference.

Reflection and Analytics Skills

`/retro` — Engineering Manager

Role: Engineering Manager

Run /retro at the end of the week to review shipping velocity, test health, and project trends.

/retro global can aggregate across projects and AI tools including Claude Code, Codex, and Gemini.

Example:

Week of March 17–23, 2026

Garry:
- 140,751 lines added
- 362 commits
- ~115k net LOC
- Test coverage: 35% (↑2% from last week)

Projects:
- gstack: 89 commits, 45k LOC
- ycombinator.com: 156 commits, 62k LOC
- internal-tools: 117 commits, 33k LOC

Shipping streak: 47 days

Run:

/retro
/retro global

Power Tools

`/careful` — Safety Guardrails

Use /careful before risky operations, including:

rm -rf
DROP TABLE
Force pushes
Production data changes

/careful

I am about to run destructive migration and cleanup commands.
Warn me before any command that could delete data or rewrite history.

`/freeze` — Edit Lock

Restrict edits to a specific directory.

/freeze /src/auth

This is useful while debugging a focused area of the codebase.

`/guard` — Full Safety

/guard combines /careful and /freeze.

Use it for:

Production debugging
Database migrations
High-risk security fixes

/guard /src/payments

`/unfreeze` — Unlock

Remove the edit boundary after the focused task is complete.

/unfreeze

`/setup-deploy` — Deploy Configurator

Run this once for each new project before using /land-and-deploy.

It detects your deployment platform, production URL, and deploy commands.

/setup-deploy

`/autoplan` — Review Pipeline

Run the complete planning pipeline in one command:

/autoplan

It runs CEO, design, and engineering reviews automatically, while surfacing taste decisions for your approval.

`/gstack-upgrade` — Self-Updater

Use this to update gstack.

/gstack-upgrade

Run it monthly or after a new feature announcement.

Installation Guide

gstack installs inside .claude/. It does not modify your PATH or run background services.

Requirements

Claude Code
Git
Bun v1.0+
Node.js on Windows only

On Windows, Node.js is required because Bun has a known bug with Playwright’s pipe transport.

Step 1: Install gstack for Your User Account

Open Claude Code and paste:

Install gstack: run git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup then add a “gstack” section to [CLAUDE.md](http://claude.md/?ref=apidog.com) that says to use the /browse skill from gstack for all web browsing, never use mcp__claude-in-chrome__* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it.

Step 2: Add gstack to a Repository

To commit gstack into a project so teammates receive it after cloning, paste this into Claude Code:

Add gstack to this project: run cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup then add a “gstack” section to this project’s [CLAUDE.md](http://claude.md/?ref=apidog.com) that says to use the /browse skill from gstack for all web browsing, never use mcp__claude-in-chrome__* tools, lists the available skills, and tells Claude that if gstack skills aren’t working, run cd .claude/skills/gstack && ./setup to build the binary and register skills.

Install for Codex, Gemini CLI, or Cursor

gstack works with agents that support the SKILL.md standard. Skills live in .agents/skills/.

Install Into One Repository

git clone https://github.com/garrytan/gstack.git .agents/skills/gstack
cd .agents/skills/gstack && ./setup --host codex

Install for Your User Account

git clone https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup --host codex

Auto-Detect Available Agents

git clone https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack && ./setup --host auto

Troubleshooting

A Skill Is Not Showing Up

Re-run setup:

cd ~/.claude/skills/gstack && ./setup

`/browse` Fails

Install dependencies and rebuild:

cd ~/.claude/skills/gstack
bun install
bun run build

Your Install Is Stale

Run:

/gstack-upgrade

Or enable automatic updates in ~/.gstack/config.yaml:

auto_upgrade: true

Windows Setup

gstack works on Windows 11 through Git Bash or WSL.

Confirm that both bun and node are available:

bun --version
node --version

Claude Cannot See the Skills

Add this to your project’s CLAUDE.md:

## gstack

Use /browse from gstack for all web browsing.
Never use mcp__claude-in-chrome__* tools.

Available skills:
- /office-hours
- /plan-ceo-review
- /plan-eng-review
- /plan-design-review
- /design-consultation
- /review
- /ship
- /land-and-deploy
- /canary
- /benchmark
- /browse
- /qa
- /qa-only
- /design-review
- /setup-browser-cookies
- /setup-deploy
- /retro
- /investigate
- /document-release
- /codex
- /cso
- /autoplan
- /careful
- /freeze
- /guard
- /unfreeze
- /gstack-upgrade

Real-World Example: Build a Daily Briefing App

Here is a practical end-to-end workflow.

1. Start With the User Problem

I want to build a daily briefing app for my calendar.

2. Run Product Discovery

/office-hours

Provide concrete pain points:

I manage multiple Google calendars. Events often have stale information
or wrong locations. Meeting preparation takes too long, and the output
from existing tools is not useful enough.

The agent may respond:

You said "daily briefing app." But what you actually described is a
personal chief of staff AI.

[extracts five implied capabilities]
[challenges four premises]
[generates three implementation approaches with effort estimates]

RECOMMENDATION: Ship the narrowest wedge tomorrow. Start with the daily
briefing that actually works.

3. Challenge Scope

/plan-ceo-review

Use this to decide whether to:

Ship only calendar aggregation first
Include meeting preparation from day one
Add email and CRM context later
Cut features that do not prove user value

4. Lock Architecture and Tests

/plan-eng-review

Ask it to explicitly cover:

Include:
- OAuth token refresh failures
- Calendar API rate limits
- Duplicate events
- Timezone normalization
- Partial sync failures
- Retry behavior
- Test coverage for stale event metadata

5. Implement the Approved Plan

Approve plan. Exit plan mode.

6. Review the Code

/review

Example result:

[AUTO-FIXED] 2 issues.
[ASK] Race condition in concurrent update flow.
[COMPLETENESS GAP] Missing retry logic for transient API failures.

7. Run Browser QA

/qa https://staging.myapp.com

The QA flow can open a real browser, click through the application, find an issue, apply a fix, and verify it.

8. Ship the Pull Request

/ship

Example output:

Tests: 42 → 51 (+9 new)
PR: github.com/you/app/pull/42

The key outcome is not just code generation. The workflow turns a vague request into a scoped, reviewed, tested, and shippable implementation.

Parallel Sprints: Run Multiple Agents at Once

gstack can support multiple Claude Code sessions running in parallel. Conductor runs sessions in isolated workspaces.

Example:

Session 1: /office-hours — refine the product spec
Session 2: /review — review yesterday's feature
Session 3: /qa — test the staging deployment
Session 4: Implementation — build an approved plan

Use parallel work only when each session has a clear boundary.

A practical split:

Session	Responsibility	Output
Product	`/office-hours`	Design doc and scope
Architecture	`/plan-eng-review`	Technical plan and test matrix
Implementation	Build approved tasks	Feature branch changes
QA	`/qa`	Verified flows and regression tests
Release	`/ship`	Pull request

Without a process, multiple agents can create conflicting changes. With a sprint structure, each agent has a defined stage and deliverable.

Privacy and Telemetry

gstack includes opt-in usage telemetry.

Default Behavior

Telemetry is disabled by default. Nothing is sent unless you explicitly opt in.

Data Sent If You Opt In

Skill name
Duration
Success or failure
gstack version
Operating system

Data Not Sent

Source code
File paths
Repository names
Branch names
Prompts
User-generated content

Disable telemetry at any time:

gstack-config set telemetry off

Telemetry data is stored in Supabase. The schema is available in the repository for inspection. The Supabase publishable key is public, while row-level security policies restrict access to insert-only operations.

For local analytics without remote data, run:

gstack-analytics

Who Should Use gstack?

Founders and Technical CEOs

Use gstack to add structure to product planning, engineering review, QA, and release work without building a large internal process from scratch.

First-Time Claude Code Users

The slash-command workflow provides guardrails instead of requiring a perfect open-ended prompt.

Tech Leads and Staff Engineers

Use individual skills such as /review, /qa, /cso, and /document-release to strengthen existing PR workflows.

Solo Builders

gstack provides specialized roles for planning, debugging, review, testing, and release management.

YC Startups

Garry built gstack for YC founders, making it a natural fit for early-stage teams that need to move quickly with limited engineering capacity.

Who Should Skip the Full Workflow?

Teams With Mature Processes

If you already have strong design review, code review, CI/CD, QA, and release processes, use individual skills instead of adopting the full sprint.

For example:

/review
/qa https://staging.example.com
/cso
/document-release

Developers Who Prefer Freeform AI Workflows

gstack is intentionally structured. If you prefer unbounded exploration and loose prompting, the workflow may feel restrictive.

Non-Claude Code Users

gstack supports Codex, Gemini CLI, and Cursor through SKILL.md, but it is optimized for Claude Code.

The Philosophy Behind gstack

Boil the Lake

Do not half-complete a task that requires a full solution. Partial work often creates more follow-up work than completing the important path correctly.

Search Before Building

Before generating new code, check whether the repository or ecosystem already has a solution.

This reduces duplicate implementations and avoids code that does not need to exist.

Three Layers of Knowledge

Explicit knowledge — Documentation, comments, and written rules
Tacit knowledge — Experience, intuition, and engineering judgment
Unknown knowledge — Blind spots you do not know to investigate

gstack attempts to encode tacit knowledge into reusable skills.

For example, /review is not just “look for bugs.” It applies a structured production-review process based on engineering experience.

The Iron Law of Debugging

No fixes without investigation.

After three failed attempts, stop and reassess.

This prevents both humans and AI agents from applying random changes without understanding the root cause.

Conclusion

gstack is Garry Tan’s system for using AI agents as a structured engineering team.

The practical workflow is:

/office-hours        # Reframe the problem
/plan-ceo-review     # Challenge scope
/plan-eng-review     # Lock architecture and test plan
/plan-design-review  # Review UX and design quality
# Build the approved plan
/review              # Find implementation issues
/qa                  # Test real browser flows
/ship                # Push and open a pull request

Start small. You do not need to adopt every skill on day one.

A good first workflow is:

/review
/qa https://staging.example.com
/ship

Then add planning skills when you need more rigor before implementation.

Next Steps

Install gstack:

   git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
   cd ~/.claude/skills/gstack
   ./setup

Run /office-hours on your next feature idea.
Run /review before opening your next pull request.
Run /qa against staging before release.
Use /document-release to keep project and API documentation synchronized with shipped behavior.

FAQ

Is gstack free?

Yes. gstack is free and MIT licensed. There is no premium tier or waitlist.

Do I need Claude Code to use gstack?

gstack is optimized for Claude Code, but it also works with agents that support the SKILL.md standard, including Codex CLI, Gemini CLI, and Cursor.

How long does installation take?

About 30 seconds:

git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack
./setup

Can I use individual skills without the full sprint?

Yes. The sprint is a recommended workflow, not a requirement.

For example:

/review
/qa https://staging.example.com

Does gstack work with private repositories?

Yes. Skills can live in .claude/skills/gstack inside your repository. Commit that directory to share the setup with teammates.

Does gstack work on Windows?

Yes. gstack works on Windows 11 through Git Bash or WSL. Install both Bun and Node.js, and ensure they are available on your PATH.

How does `/browse` work?

/browse uses Playwright to control a headless Chromium browser. Commands execute in approximately 100ms. Use /setup-browser-cookies to test authenticated pages.

Can I customize gstack skills?

Yes. Skills are Markdown files. Edit them to match your repository conventions, team process, and release workflow.

What is the difference between `/qa` and `/qa-only`?

/qa finds bugs and can auto-fix them with atomic commits.
/qa-only finds bugs and reports them without changing code.

Use /qa-only when you need an audit trail or separate ownership for fixes.

How does telemetry work?

Telemetry is opt-in. If enabled, gstack sends skill name, duration, success or failure, version, and OS. It does not send code, file paths, repository names, branch names, or prompts.

Disable it with:

gstack-config set telemetry off

What if I find a bug in gstack?

Run /investigate against gstack’s codebase or open an issue on GitHub.

Can I run gstack skills in parallel?

Yes. With Conductor, you can run multiple Claude Code sessions in isolated workspaces. Assign each session a clear stage, such as planning, implementation, review, or QA.

API Sandbox: Comprehensive Guide to Safe API Testing

Preecha — Tue, 04 Aug 2026 13:01:21 +0000

API development and integration are central to modern software, but testing against live APIs can be risky, expensive, and error-prone. An API sandbox provides an isolated environment where developers and testers can send realistic requests, validate integrations, and simulate failures without affecting production data.

Try Apidog today

What Is an API Sandbox?

An API sandbox is an isolated test environment that simulates a production API. Your application sends requests to sandbox endpoints using test credentials and receives realistic, predefined, or dynamically generated responses.

Use a sandbox to:

Test request payloads and response handling
Build integrations before a production API is available
Simulate failures, timeouts, and invalid input
Validate authentication and authorization flows
Debug client applications without changing real data

Unlike production, a sandbox is intended for experimentation. It should prevent unintended side effects such as corrupted records, real payments, or exposure of sensitive data.

Why Use an API Sandbox?

A sandbox removes common integration bottlenecks and reduces deployment risk.

Reduce production risk: Keep test traffic and test data separate from live users and business operations.
Develop in parallel: Front-end, back-end, QA, and partner teams can work before every production dependency is ready.
Control testing costs: Avoid third-party API charges, quota consumption, or overage fees during development.
Test difficult scenarios: Reproduce rare errors, rate limits, authorization failures, and invalid payloads on demand.
Improve onboarding: Give new developers a safe environment to learn an API and verify their implementation.

Apidog supports API sandboxing with visual API design, mock data generation, and integrated testing workflows.

Key Components of an API Sandbox

A useful sandbox should reproduce the parts of production that clients depend on while remaining isolated from real systems.

1. Production Isolation

Sandbox traffic must use separate infrastructure, databases, credentials, or test tenants. A request sent to the sandbox must not create a real order, transfer funds, or update production customer data.

Use distinct base URLs to make the separation explicit:

Production: https://api.example.com/v1
Sandbox:    https://sandbox.api.example.com/v1

2. Mocked or Virtualized Endpoints

Sandbox endpoints should match the production API contract:

HTTP methods
Paths and query parameters
Request schemas
Response schemas
Status codes
Authentication requirements

For example, if production exposes:

POST /v1/orders

the sandbox should expose the same path and accept the same request shape.

3. Configurable Scenarios

Configure more than a single successful response. Clients need to handle both expected and failing conditions.

Include scenarios for:

Successful responses: 200, 201, 204
Validation errors: 400, 422
Authentication and authorization errors: 401, 403
Missing resources: 404
Server failures: 500, 503
Delayed responses and timeouts
Rate limiting: 429
Invalid or incomplete payloads

4. Authentication and Security

A sandbox should usually reproduce production authentication patterns, such as API keys, OAuth tokens, or bearer tokens. Use test credentials that cannot access production resources.

Example:

Authorization: Bearer test_token

This lets developers verify token handling, scopes, refresh flows, and unauthorized-state behavior before release.

5. Request Logging

Logs should capture enough information to debug integrations:

Request method and URL
Headers, excluding secrets where appropriate
Request body
Response status and body
Timestamp and correlation ID
Scenario or mock rule that matched the request

6. Realistic Test Data

Use synthetic or anonymized data that follows the same schema as production. Avoid copying sensitive production data into the sandbox.

For example, use test customer records such as:

{
  "id": "cust_test_123",
  "email": "test.user@example.com",
  "status": "active"
}

How an API Sandbox Works

A sandbox receives requests from your application and returns responses based on configured rules or simulated backend behavior.

A typical workflow looks like this:

Configure your application with a sandbox base URL.
Authenticate with test credentials.
Send requests exactly as you would in production.
Match requests against sandbox rules, mocks, or virtualized services.
Return a configured response.
Validate client behavior, logs, retries, and error handling.

For example, configure a payment-transfer client to use:

https://sandbox.api-bank.com/v1/

Then send a transfer request:

POST /v1/transfer HTTP/1.1
Host: sandbox.api-bank.com
Content-Type: application/json
Authorization: Bearer test_token

{
  "from_account": "123456",
  "to_account": "654321",
  "amount": 100.00
}

A successful sandbox response might be:

{
  "transaction_id": "test_txn_001",
  "status": "success",
  "message": "Funds transferred successfully in sandbox environment"
}

Configure an error scenario as well:

{
  "transaction_id": null,
  "status": "error",
  "message": "Insufficient funds"
}

Your client can then verify that it displays the correct error, prevents duplicate retries where necessary, and records the failed transaction correctly.

Platforms such as Apidog let teams configure mock endpoints and custom responses for these scenarios without modifying production systems.

Benefits of Using an API Sandbox

Safer Experimentation

Developers can test new features, request formats, and integration logic without exposing production data or interrupting real workflows.

Faster Development and Testing

Teams can start integration work before every backend service is complete. This reduces handoff delays between front-end, backend, QA, and external partners.

Lower Costs

Sandbox requests avoid accidental production usage and can reduce testing-related third-party API charges.

Better API Quality

Testing error paths and edge cases produces more resilient clients. Instead of only validating the happy path, teams can confirm behavior for invalid data, expired credentials, and transient failures.

Easier Developer Onboarding

A documented sandbox gives developers a safe place to explore endpoints, make requests, and understand expected responses.

API Sandbox vs. API Virtualization vs. Mock APIs

These terms overlap, but they describe different parts of an API testing strategy.

Term	Purpose
API sandbox	An isolated environment for safely testing an API integration.
API virtualization	Simulates API behavior when the real service is unavailable, incomplete, or difficult to access.
Mock API	Returns predefined or dynamic responses, typically for specific endpoints and test cases.

In practice, an API sandbox often uses mock APIs and virtualization together. The sandbox provides the environment, while mocks and virtualized services provide the behavior.

Implementing an API Sandbox: Best Practices

1. Match the Production Contract

Keep sandbox request and response formats aligned with production. A sandbox that returns different field names, status codes, or validation behavior can hide integration bugs.

Start with your API specification and ensure the sandbox supports:

Required and optional fields
Response schemas
Status codes
Authentication rules
Pagination and filtering behavior
Versioned paths

2. Create a Scenario Matrix

Document the scenarios clients must support before implementing mocks.

Scenario	Request condition	Expected status
Successful request	Valid payload and credentials	`200` or `201`
Invalid payload	Missing required field	`400` or `422`
Invalid token	Expired or malformed token	`401`
Forbidden action	Token lacks required scope	`403`
Missing resource	Unknown resource ID	`404`
Rate limited	Too many requests	`429`
Service failure	Simulated backend issue	`500` or `503`

This matrix becomes the basis for manual checks and automated tests.

3. Automate Sandbox Tests

Run sandbox tests in CI to detect regressions before deployment.

For example, test a successful request with curl:

curl --request POST "https://sandbox.api-bank.com/v1/transfer" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer test_token" \
  --data '{
    "from_account": "123456",
    "to_account": "654321",
    "amount": 100.00
  }'

Then add tests for invalid credentials, malformed payloads, rate limits, and server errors.

4. Maintain Clear Documentation

Your sandbox documentation should include:

Sandbox base URL
Authentication setup
Test account or credential instructions
Endpoint reference
Request and response examples
Error code definitions
Supported test scenarios
Reset or cleanup behavior

Apidog can automatically generate online API documentation for sandbox endpoints, helping keep implementation details aligned across the team.

5. Secure the Sandbox

A sandbox is not production, but it still needs protection.

Apply controls such as:

Test-only credentials
Authentication for all non-public endpoints
Rate limiting and throttling
Request logging and monitoring
Secret redaction in logs
Synthetic or anonymized test data

6. Reset Test Data Regularly

Test data can become inconsistent over time. Provide a repeatable reset process so developers can start from a known state.

For example, reset test orders, accounts, and inventory records after scheduled test runs. This prevents one test suite from breaking another due to leftover state.

Practical API Sandbox Examples

Example 1: Payment Gateway Integration

A fintech startup integrates with a payment processor's sandbox to test:

Payment creation
Refunds and chargebacks
Declined cards
Expired tokens
Fraud alerts
Webhook handling
Reconciliation logic

The startup can validate its payment workflow without creating real charges or relying on real customer payment details.

Example 2: E-commerce Integration

An e-commerce platform provides a sandbox for third-party developers building integrations for:

Shopping carts
Orders
Inventory
Shipping
Returns

Developers can simulate stock-outs, order cancellations, shipping updates, and returns to ensure their applications handle both normal and unexpected API responses.

Example 3: Healthcare Data Exchange

A healthcare application uses a sandbox to test interactions with a patient-data API. The sandbox can provide synthetic patient records, lab results, authentication failures, and validation errors.

This allows teams to validate authorization and integration behavior without using sensitive patient data.

Example 4: Creating a Sandbox with Apidog

If your team is building a public API, use Apidog to create a sandbox workflow:

Define API endpoints and request schemas.
Create mock responses for successful and error scenarios.
Configure rules that return different responses based on request parameters.
Share the sandbox with front-end teams and integration partners.
Generate and publish sandbox documentation.
Iterate on the API contract without changing production services.

This approach lets teams validate integrations early and reduce production-release risk.

How to Get Started

Follow these steps to introduce a sandbox into an API workflow.

1. Find or Create a Sandbox Environment

Check whether the API provider offers a sandbox URL. If not, create one using mock APIs, API virtualization, or a platform such as Apidog.

2. Obtain Test Credentials

Use test API keys, OAuth clients, tokens, or test accounts. Keep sandbox credentials separate from production credentials.

3. Configure Your Application

Make the base URL environment-specific.

For example:

API_BASE_URL=https://sandbox.api.example.com/v1
API_TOKEN=test_token

In code:

const baseUrl = process.env.API_BASE_URL;

await fetch(`${baseUrl}/orders`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.API_TOKEN}`
  },
  body: JSON.stringify({
    customer_id: "cust_test_123",
    items: [{ sku: "sku_test_001", quantity: 1 }]
  })
});

4. Run Positive and Negative Tests

Test the happy path, but also intentionally send invalid requests.

Verify that your application handles:

Missing fields
Invalid data types
Unauthorized requests
Empty responses
Delayed responses
Rate limits
Server errors

5. Review Logs and Refine the Integration

Use request and response logs to identify payload mismatches, incorrect headers, missing error handling, or retry problems. Repeat until the integration behaves correctly across the full scenario matrix.

Common Challenges and Solutions

Challenge: Sandbox and Production Drift

Sandbox behavior can fall behind production as APIs evolve.

Mitigation:

Treat the API specification as the shared contract.
Update sandbox mocks when endpoints or schemas change.
Add contract tests to detect incompatible changes.
Review sandbox scenarios during release planning.

Challenge: Limited Test Scenarios

A sandbox with only static success responses does not provide enough coverage.

Mitigation:

Add configurable response rules.
Return different responses based on request parameters.
Simulate validation errors, timeouts, rate limits, and server failures.
Use API virtualization when dependent services are unavailable.

Platforms such as Apidog can define custom responses based on request parameters, enabling more flexible test coverage.

Challenge: Security and Abuse

Public or poorly protected sandboxes can be misused.

Mitigation:

Require authentication.
Apply request throttling and rate limits.
Monitor logs for unusual traffic.
Rotate test credentials when needed.
Never use live customer data in sandbox responses.

Conclusion

An API sandbox gives development teams a safe, repeatable way to build, test, and debug integrations before production release. By isolating test traffic, using realistic mock data, simulating failure scenarios, and automating sandbox tests, teams can reduce risk and ship more reliable API clients.

Make the sandbox part of your API lifecycle: define the contract, configure realistic scenarios, automate validation, and keep it aligned with production.

AWS API Gateway Cost: Pricing & Optimization Guide

Preecha — Tue, 04 Aug 2026 01:01:31 +0000

When designing and deploying APIs in the cloud, understanding AWS API Gateway cost is essential for controlling spend, scaling safely, and maintaining reliable services. This guide breaks down the main pricing models, shows practical cost calculations, and provides implementation-focused steps to reduce API Gateway expenses.

Try Apidog today

What Is AWS API Gateway Cost?

AWS API Gateway cost is the total amount you pay to use Amazon API Gateway, including request processing, data transfer, caching, and optional features. Your bill depends primarily on:

The API type: HTTP, REST, or WebSocket.
Request or message volume.
Outbound data transfer.
REST API cache capacity.
Optional services such as custom domains and AWS WAF.
Backend services such as AWS Lambda, DynamoDB, or other AWS integrations.

Estimate these costs before deploying so you can:

Forecast monthly or annual cloud spend.
Prevent billing surprises as traffic grows.
Choose an API type that matches the workload and budget.

Understand AWS API Gateway Pricing Models

API Types and Cost Structures

API Gateway provides three primary API types:

API Type	Cost per Million Requests (First Tier)	Cost per Million Requests (Next Tier)	Best For
HTTP APIs	$1.00 (first 300M)	$0.90 (over 300M)	Simple, low-latency, serverless APIs
REST APIs	$3.50 (first 333M)	Tiered pricing	APIs requiring caching, API keys, request validation, or throttling
WebSocket APIs	$1.00 (first 1B messages)	$0.80 (over 1B messages)	Real-time, bidirectional communication

HTTP APIs are up to 71% cheaper than REST APIs for high-volume workloads. Start with HTTP APIs unless your application specifically requires REST API features such as usage plans, API keys, or API Gateway caching.

AWS API Gateway Free Tier

For new customers, AWS provides a Free Tier that includes:

1 million API calls per month for HTTP APIs, REST APIs, and WebSocket APIs for up to 12 months.
750,000 connection minutes per month for WebSocket APIs.

Use the Free Tier for prototypes and early testing, but configure budget alerts before traffic exceeds those limits.

Data Transfer Fees

Request charges are not the only API Gateway expense. Public APIs can also incur outbound internet data-transfer charges.

Public API outbound transfer: typically $0.09 per GB in many AWS regions.
Private APIs: traffic accessible only within your VPC does not incur outbound data-transfer fees through API Gateway.

Always verify regional pricing before finalizing an estimate.

Optional Features That Affect Cost

Feature	Cost Impact
REST API caching	Hourly cache charge, starting at $0.02/hour for 0.5 GB
Custom domain names	Small monthly charge
AWS WAF	Separate AWS WAF charges
Lambda, DynamoDB, and other integrations	Separate service charges

Break Down Your AWS API Gateway Cost

Use this formula as a starting point:

Total monthly API Gateway cost =
  request or message charges
  + outbound data transfer
  + cache charges
  + custom domain and optional feature charges
  + related backend service costs

1. Calculate Request Charges

Multiply monthly requests by the per-million-request rate for the API type.

HTTP API example

10 million requests × $1.00 per million = $10/month

REST API example

10 million requests × $3.50 per million = $35/month

WebSocket API example

50 million messages × $1.00 per million = $50/month

2. Calculate Data Transfer

Estimate the total response data sent to the public internet.

2 GB outbound data × $0.09 per GB = $0.18/month

Add this amount to request charges.

3. Calculate REST API Cache Charges

REST API caching is billed hourly. For example, a 1 GB cache running for an entire month:

1 GB cache × $0.04/hour × 730 hours = $29.20/month

Before enabling a cache, confirm that its backend savings justify its fixed hourly cost.

4. Include Custom Domains and Certificates

Custom domain name: typically $1.00/month, depending on region.
SSL certificate: free when using AWS Certificate Manager (ACM).

5. Account for Backend Costs

API Gateway may invoke services that have their own pricing, including:

AWS Lambda
Amazon DynamoDB
Amazon RDS
Amazon SQS
Other AWS services or external integrations

Track API Gateway and backend costs together. A low API Gateway bill can still trigger high Lambda invocation or database costs.

Real-World AWS API Gateway Cost Examples

Example 1: Small Startup Prototype

Scenario: A mobile application uses an HTTP API with 1 million requests per month. Each response is 100 KB.

HTTP API requests:
1M requests = $0 under the Free Tier

Outbound data transfer:
100 KB × 1M requests = 100 GB/month
100 GB × $0.09 = $9.00/month

Total estimated cost:
$9.00/month

The request volume fits within the Free Tier, but response payload size still drives data-transfer cost.

Example 2: Growing SaaS Product

Scenario: A SaaS product processes 50 million REST API requests per month, uses a 2 GB cache, and transfers 500 GB of data.

REST API requests:
50M × $3.50 per million = $175.00

Cache:
2 GB × $0.04/hour × 730 hours = $58.40

Outbound data transfer:
500 GB × $0.09 = $45.00

Total estimated cost:
$278.40/month

In this example, request processing is the largest component, followed by caching.

Example 3: Real-Time Chat Application

Scenario: A WebSocket API handles 200 million messages per month and 1 million connection minutes.

WebSocket messages:
200M × $1.00 per million = $200.00

Connection minutes:
1M connection minutes = $0 within the Free Tier

Total estimated cost:
$200.00/month

For WebSocket workloads, monitor both message volume and connection duration.

How to Reduce AWS API Gateway Cost

1. Choose the Right API Type

Use the least expensive API type that satisfies your requirements.

Choose HTTP APIs for stateless APIs, simple Lambda integrations, and standard request-response workloads.
Use REST APIs only when you need features such as API keys, usage plans, request validation, throttling, or API Gateway caching.
Use WebSocket APIs for persistent, bidirectional communication such as chat, notifications, or live dashboards.

2. Reduce Response Payload Size

Outbound data transfer can become significant when APIs return large responses.

Practical options include:

Return only fields required by the client.
Paginate large collections.
Compress responses where appropriate.
Avoid embedding large binary payloads in API responses.
Use object storage or a CDN for large files instead of serving them directly through API Gateway.

For example, paginate a collection endpoint instead of returning all records:

GET /users?limit=50&cursor=next-page-token

3. Cache Only High-Value REST Endpoints

Caching can reduce backend calls, but it creates a fixed hourly cost.

Use caching for endpoints that are:

Read-heavy.
Frequently requested.
Safe to serve with a short-lived response.
Expensive for the backend to compute.

Monitor cache hit rates. If the cache rarely serves hits, remove or resize it.

4. Set Cost and Usage Alerts

Configure alerts before an unexpected traffic increase becomes a billing issue.

Use:

AWS Cost Explorer to review historical spend.
AWS Budgets to alert on monthly thresholds.
Amazon CloudWatch to monitor request counts, latency, errors, and throttling.

A practical workflow:

Set a monthly API budget.
Add alerts at 50%, 80%, and 100% of the budget.
Review request volume by API stage and route.
Investigate sudden increases in 4xx, 5xx, or total request counts.

5. Use Private APIs for Internal Traffic

If consumers are inside your VPC, use private APIs where appropriate. This can avoid public outbound data-transfer charges through API Gateway.

6. Optimize Backend Integrations

API Gateway pricing is only part of total API cost. Reduce downstream work by:

Avoiding unnecessary Lambda invocations.
Batching database reads where possible.
Returning cached data for repeat requests.
Validating requests early to prevent invalid calls from reaching expensive backend services.

7. Design and Test APIs Before Production

Tools like Apidog can help streamline API design, documentation, mocking, and testing. Use them to validate endpoint behavior before production traffic generates AWS charges.

A practical pre-deployment workflow:

Import an OpenAPI or Swagger definition.
Define request and response examples.
Mock endpoint behavior for frontend and integration testing.
Test expected request patterns.
Remove unused endpoints and oversized responses before deployment.

Practical Example: Calculate Your Monthly Cost

Estimate costs for each API independently, then sum them.

Step 1: Estimate Monthly Request Volume

List expected traffic by API type:

HTTP API: 25 million requests/month
REST API: 0 requests/month
WebSocket API: 0 messages/month

Step 2: Apply Request Pricing

25 million HTTP API requests × $1.00 per million = $25.00

Step 3: Estimate Outbound Data Transfer

100 GB outbound data × $0.09 per GB = $9.00

Step 4: Add Cache Costs

HTTP APIs do not support API Gateway caching, so this cost is zero.

Cache cost = $0.00

Step 5: Add Optional Features

Custom domain = $1.00

Step 6: Calculate the Total

Request charges:      $25.00
Data transfer:         $9.00
Cache:                 $0.00
Custom domain:         $1.00
--------------------------------
Estimated monthly cost: $35.00

AWS API Gateway Cost in Multi-Region Deployments

For multi-region APIs, calculate costs separately for each AWS region.

Keep these points in mind:

API Gateway request charges apply per region.
Traffic patterns can vary by region.
Cross-region data transfer has additional costs not included in API Gateway request pricing.
Each region may require separate cache, domain, and backend capacity planning.

Create a cost worksheet per region instead of applying one global estimate.

How Apidog Helps Manage AWS API Gateway Cost

Apidog can support cost-aware API development by helping teams:

Design lean APIs: Define, mock, and test APIs before deployment to avoid unnecessary endpoints and calls.
Maintain documentation: Generate and update API documentation to reduce incorrect integrations and accidental overuse.
Import and test API specifications: Bring in Swagger or OpenAPI definitions and simulate API behavior before production traffic reaches AWS.

Use this workflow to identify inefficient endpoints early:

Define API contract
→ mock responses
→ test request flows
→ measure expected payload sizes
→ remove unnecessary calls
→ deploy to API Gateway

Conclusion: Mastering AWS API Gateway Cost

AWS API Gateway cost is driven by request volume, data transfer, caching, optional features, and connected backend services. Start with the appropriate API type, measure traffic and payload sizes, and continuously monitor usage as your application grows.

Key takeaways:

Use HTTP APIs for simple, stateless workloads whenever possible.
Use REST APIs only when their advanced features are required.
Track data transfer as carefully as request volume.
Enable caching only when cache hit rates justify the hourly charge.
Set AWS Budgets and CloudWatch alerts before deploying at scale.
Test API contracts, payloads, and request patterns before production to avoid unnecessary API calls.

How to Create Claude Code Skills Automatically with Skill Creator

Preecha — Mon, 03 Aug 2026 13:02:25 +0000

TL;DR

Claude Code Skills are custom capabilities that extend Claude’s functionality for specific workflows. Use the Skill Creator workflow to define a skill, write SKILL.md, create realistic test cases, benchmark results with and without the skill, iterate from feedback, optimize triggering, and package the result.

Try Apidog today

Introduction

If you repeatedly ask Claude Code to set up the same project structure, run the same test commands, or format reports the same way, turn that workflow into a Skill.

A Claude Code Skill is a reusable instruction package for a focused workflow. Skill Creator provides a systematic way to build one: define the outcome, write instructions, evaluate the result, improve the instructions, and package the final Skill.

This guide covers:

The structure of a Claude Code Skill
A repeatable Skill Creator workflow
Test cases, assertions, and benchmarks
Trigger-description optimization
Packaging and sharing a Skill

If you are building API-related skills, Apidog fits naturally into the workflow for testing endpoints, validating responses, and generating documentation.

What Are Claude Code Skills?

Claude Code Skills are specialized instruction sets that extend Claude’s capabilities for specific domains or workflows. They are Markdown-based packages that can include instructions, scripts, references, and assets.

Skill system architecture

Skills use three loading levels:

Metadata (~100 words): name and description, always available in context.
SKILL.md body (<500 lines): core instructions, loaded when the Skill triggers.
Bundled resources (unlimited): scripts, references, and assets loaded only when needed.

skill-name/
├── SKILL.md
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources
    ├── scripts/    # Executable code for repeated tasks
    ├── references/ # Documentation loaded as needed
    └── assets/     # Templates, icons, fonts

When Skills trigger

Claude sees Skills through its available_skills list and uses the Skill description to decide whether a Skill applies.

A Skill is most reliable for complex, multi-step tasks. Simple requests such as “read this file” may not trigger a Skill even if its description contains matching words.

Write descriptions around:

The workflow the Skill handles
User phrases that indicate the workflow
Expected inputs and outcomes
Adjacent requests that should not trigger the Skill

Examples from Anthropic’s repository

Skill	Purpose	Key features
`skill-creator`	Create new Skills	Test-case generation, benchmark evaluation, description optimization
`mcp-builder`	Build MCP servers	Python/Node templates, evaluation framework, best practices
`docx`	Generate Word documents	`python-docx` scripts, templates, styling guidance
`pdf`	Extract and manipulate PDFs	Form handling, text extraction, reference documentation
`frontend-design`	Build web interfaces	Component libraries, Tailwind patterns, accessibility checks

The Skill Creation Workflow

Use this loop when creating or improving a Skill:

Capture intent
Draft SKILL.md
Create test cases
Run baseline and Skill-enabled evaluations
Review qualitative output and quantitative metrics
Improve the Skill
Optimize the description for triggering
Package the Skill as a .skill file

Step 1: Capture Intent

Start with a workflow, not a generic topic.

Ask these questions before writing instructions:

What should the Skill enable Claude to do? Define a concrete outcome.
When should it trigger? List user wording, contexts, and inputs.
What should it produce? Define files, code, reports, or other artifacts.
Can you verify the output objectively? If yes, create test cases and assertions.

Example: API testing Skill

Field	Definition
Intent	Help developers test REST APIs systematically
Trigger	API testing, endpoints, REST, GraphQL, response validation
Output	Test reports, pass/fail status, `curl` commands, response comparisons
Test cases	Yes, because the output is objectively verifiable

Keep the scope narrow enough that the Skill has a clear job. A Skill that “works with APIs” is ambiguous; a Skill that “generates a repeatable REST endpoint test plan and executable requests” is actionable.

Step 2: Write `SKILL.md`

Every Skill needs a SKILL.md file with YAML frontmatter followed by Markdown instructions.

Start with a minimal Skill

---
name: api-tester
description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved.
compatibility: Requires curl or HTTP client tools
---

# API Tester Skill

## Core Workflow

When testing an API:

1. **Understand the endpoint**: Read the specification or request the schema.
2. **Design test cases**: Cover happy paths, edge cases, and error conditions.
3. **Execute tests**: Use `curl` or Apidog for requests.
4. **Validate responses**: Check status codes, headers, and body structure.
5. **Report results**: Summarize pass/fail status with evidence.

## Test Case Template

For each endpoint, test:

- Valid authentication with a correct payload
- Missing required fields
- Invalid authentication (`401` expected)
- Rate-limiting behavior
- Response time under load

## Output Format

# API Test Report

## Summary
- Tests run: X
- Passed: Y
- Failed: Z

## Failed Tests

### Test Name
**Expected:** 200 OK  
**Actual:** 400 Bad Request  
**Response:** `{...}`

## Recommendations
...

Keep `SKILL.md` focused

Use progressive disclosure:

api-tester/
├── SKILL.md
└── references/
    ├── authentication.md
    ├── rate-limiting.md
    └── response-codes.md

Keep the reusable workflow in SKILL.md. Move lengthy documentation, protocol details, and large examples to references/.

Write instructions that explain intent

Avoid instructions that only list rules. Explain why the rule exists so the model can adapt it correctly.

Instead of:

Always validate the status code first.

Use:

Validate the status code before analyzing the response body. A failed authentication or authorization response can make happy-path body validation meaningless.

Use imperative language, but avoid overly rigid wording when context may require adaptation.

Include concrete examples

## Commit message format

**Input:** Added user authentication with JWT tokens  
**Output:** `feat(auth): implement JWT-based authentication`

Examples make output expectations easier to follow than abstract instructions alone.

Step 3: Create Test Cases

Create two or three realistic prompts before running evaluations. These should resemble requests developers would actually send.

Save them in evals/evals.json:

{
  "skill_name": "api-tester",
  "evals": [
    {
      "id": 1,
      "prompt": "Test the /users endpoint on api.example.com - it needs a Bearer token and returns a list of users with id, name, email fields",
      "expected_output": "Test report with at least 5 test cases including auth failure, success, and pagination tests",
      "files": []
    },
    {
      "id": 2,
      "prompt": "I need to verify our new POST /orders endpoint handles invalid quantities correctly",
      "expected_output": "Test cases that send negative, zero, and non-numeric quantities with appropriate error responses",
      "files": ["openapi.yaml"]
    }
  ]
}

Write prompts with implementation details

Avoid vague test prompts:

Test this API

Use prompts that include endpoint context, a scenario, and expected behavior:

My team deployed a new payments endpoint at https://api.stripe.com/v1/charges.
I need to verify edge cases: negative amounts and invalid currency codes.
The documentation says both should return 400, but I want to inspect the actual error messages.

A strong evaluation prompt includes:

A specific URL or endpoint
A concrete failure mode or use case
Expected behavior
Realistic context and constraints

Before running the evaluation, share the test scenarios with the user:

Here are the test scenarios I plan to run. Do these match the workflow, or should we add another case?

Step 4: Run Evaluations

Run each test case twice:

With the Skill
Without the Skill, or with the previous version when iterating

This comparison shows whether the Skill improves output quality enough to justify its time and token cost.

Use a predictable workspace structure

Store results in a sibling workspace directory:

api-tester-workspace/
├── iteration-1/
│   ├── eval-0-auth-failure/
│   │   ├── with_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   ├── without_skill/
│   │   │   ├── outputs/
│   │   │   └── timing.json
│   │   └── eval_metadata.json
│   ├── eval-1-pagination/
│   │   └── ...
│   ├── benchmark.json
│   └── benchmark.md
├── iteration-2/
└── feedback.json

Launch parallel runs

For each test case, run Skill-enabled and baseline executions in the same turn.

With-Skill run:

Execute this task:
- Skill path: /path/to/api-tester
- Task: Test the /users endpoint on api.example.com
- Input files: none
- Save outputs to: api-tester-workspace/iteration-1/eval-0/with_skill/outputs/

Baseline run:

Execute this task:
- Skill path: (none)
- Task: Test the /users endpoint on api.example.com
- Input files: none
- Save outputs to: api-tester-workspace/iteration-1/eval-0/without_skill/outputs/

Capture timing and token data

When each run completes, save the execution data immediately:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

Write this to the run’s timing.json. This information is provided through task notifications, so capture it as each notification arrives.

Step 5: Draft Assertions While Evaluations Run

Do not wait for every run to finish before defining your success criteria.

Write assertions that are:

Objective: unambiguous pass/fail criteria
Descriptive: names explain what is checked
Reusable: applicable across later iterations

Example assertions for an API testing Skill:

{
  "assertions": [
    {
      "name": "includes_auth_failure_test",
      "description": "Test report includes at least one authentication failure test case",
      "type": "contains",
      "value": "401"
    },
    {
      "name": "includes_success_test",
      "description": "Test report includes at least one successful request test",
      "type": "contains",
      "value": "200"
    },
    {
      "name": "includes_curl_commands",
      "description": "Each test case includes executable curl commands",
      "type": "regex",
      "value": "curl -"
    },
    {
      "name": "includes_response_validation",
      "description": "Report validates response structure against schema",
      "type": "contains",
      "value": "schema"
    }
  ]
}

Add these assertions to both eval_metadata.json and evals/evals.json.

Step 6: Grade and Aggregate Results

After every run completes, grade outputs against the assertions and aggregate the results.

Grade each run

Use a grader subagent that reads agents/grader.md and evaluates each assertion.

Save the output as grading.json in the run directory:

{
  "eval_id": 0,
  "grading": [
    {
      "text": "includes_auth_failure_test",
      "passed": true,
      "evidence": "Found 401 status code in test case 3"
    },
    {
      "text": "includes_curl_commands",
      "passed": true,
      "evidence": "Found 'curl -X POST' in test case 1"
    }
  ]
}

The grading.json entries must use the exact field names:

text
passed
evidence

The evaluation viewer depends on those names.

Aggregate the benchmark

Run the aggregation script from the skill-creator directory:

python -m scripts.aggregate_benchmark api-tester-workspace/iteration-1 --skill-name api-tester

This produces:

benchmark.json
benchmark.md

The benchmark includes pass rates, timing, token usage, mean ± standard deviation, and deltas between configurations.

Analyze the benchmark

Read the benchmark instead of focusing only on the final outputs.

Look for:

Non-discriminating assertions: checks that always pass with and without the Skill
High-variance evaluations: potentially flaky test cases
Time and token tradeoffs: quality gains that cost too much latency or context

Use agents/analyzer.md for the detailed analysis process.

Step 7: Launch the Eval Viewer

The eval viewer provides a browser interface for qualitative review and quantitative comparison.

Generate the viewer

nohup python /path/to/skill-creator/eval-viewer/generate_review.py \
  api-tester-workspace/iteration-1 \
  --skill-name "api-tester" \
  --benchmark api-tester-workspace/iteration-1/benchmark.json \
  > /dev/null 2>&1 &

VIEWER_PID=$!

For iteration two and later, provide the previous workspace:

--previous-workspace api-tester-workspace/iteration-1

What reviewers see

The Outputs tab provides:

The original prompt
Generated output files rendered inline
Previous output for later iterations
Formal assertion grades
A feedback field that saves automatically
Previous feedback for later iterations

The Benchmark tab provides:

Pass rates for each configuration
Timing comparisons
Token usage
Per-evaluation details
Analyst observations

Tell the reviewer:

I opened the results in your browser. Use the Outputs tab to review each test case and leave feedback. Use the Benchmark tab to compare quality, timing, and token usage. When you are done, return here and let me know.

Headless environments

If webbrowser.open() is unavailable, generate a standalone HTML file:

--static /path/to/output/review.html

When the user selects Submit All Reviews, the viewer downloads feedback.json.

Step 8: Read Feedback and Iterate

After review, read feedback.json:

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "the chart is missing axis labels",
      "timestamp": "2026-03-23T10:30:00Z"
    },
    {
      "run_id": "eval-1-with_skill",
      "feedback": "",
      "timestamp": "2026-03-23T10:31:00Z"
    },
    {
      "run_id": "eval-2-with_skill",
      "feedback": "perfect, love this",
      "timestamp": "2026-03-23T10:32:00Z"
    }
  ],
  "status": "complete"
}

An empty feedback field means the reviewer found no issue. Prioritize test cases with specific complaints.

Improve the Skill without overfitting

Improve patterns, not only individual test prompts.

For example:

If outputs repeatedly create the same helper script, bundle that script in scripts/.
If the Skill wastes time on an unnecessary step, remove or simplify that instruction.
If an instruction requires repeated ALWAYS or NEVER wording, explain the reason behind the behavior instead.
If a fix only works for one test case, generalize the underlying rule before adding it.

Read execution transcripts as well as final outputs. A final response can look correct while the Skill still consumes unnecessary tokens or follows an inefficient process.

Repeat the iteration loop

Update the Skill.
Rerun every test case into iteration-<N+1>/.
Include baseline runs again.
Launch the viewer with --previous-workspace.
Collect feedback.
Repeat until output quality stabilizes.

Stop when:

The user says they are happy
All feedback is empty
New iterations are no longer producing meaningful improvements

When finished, stop the viewer:

kill $VIEWER_PID 2>/dev/null

Step 9: Optimize the Skill Description

The description field in SKILL.md frontmatter is the main trigger mechanism. Optimize it after the core workflow works.

Create trigger evaluation queries

Create 20 queries split between should-trigger and should-not-trigger cases:

[
  {
    "query": "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think",
    "should_trigger": true
  },
  {
    "query": "I need to create a pivot table from this CSV and email it to the team",
    "should_trigger": false
  }
]

For the 8–10 should-trigger queries, include:

Formal and casual phrasing
Requests that do not explicitly name the Skill
Common and uncommon use cases
Edge cases

For the 8–10 should-not-trigger queries, include:

Near-misses with similar keywords
Adjacent tasks better handled by another Skill
Ambiguous requests that naive keyword matching might incorrectly match

Avoid easy negative cases such as “Write a Fibonacci function” for a PDF-related Skill. Useful negatives should be close enough to expose incorrect triggering.

Review the eval set with the user

Use the provided HTML template:

Read assets/eval_review.html.
Replace placeholders with the Skill name, current description, and eval data.
Write the result to a temporary file.
Open it for review.

open /tmp/eval_review_api-tester.html

The user can edit queries, change trigger expectations, and add or remove cases. When they select Export Eval Set, the browser downloads:

~/Downloads/eval_set.json

This review matters because poor evaluation queries lead to poor trigger descriptions.

Run the optimization loop

python -m scripts.run_loop \
  --eval-set /path/to/trigger-eval.json \
  --skill-path /path/to/api-tester \
  --model claude-sonnet-4-6 \
  --max-iterations 5 \
  --verbose

Use the same model ID as the current session so trigger behavior matches what users experience.

The optimization script:

Splits the eval set into 60% training and 40% held-out testing.
Evaluates the current description three times for reliability.
Proposes description improvements from failures.
Re-evaluates training and test sets.
Iterates up to five times.
Returns best_description, selected from held-out test score rather than training score.

Apply the best description

Update the description value in SKILL.md frontmatter and show the user the change.

Before:

description: How to test REST APIs systematically

After:

description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved, even if they don't explicitly mention 'testing'.

Step 10: Package and Distribute

When the Skill is ready, package it:

python -m scripts.package_skill /path/to/api-tester

The command creates a .skill file. Share the generated file path with the user.

Installation

Users can install a Skill by:

Placing the .skill file in their Skills directory, or
Using the Claude Code Skill installation command

Common Skill Creation Mistakes

Mistake 1: Vague descriptions

Too vague:

description: A skill for working with APIs

Actionable:

description: How to test REST APIs systematically. Use when users mention API testing, endpoints, REST, GraphQL, or want to validate API responses. Make sure to suggest this skill whenever testing is involved, even if they don't explicitly mention 'testing'.

The second version describes the task and the trigger conditions.

Mistake 2: Overly restrictive instructions

Avoid:

ALWAYS use this exact format. NEVER deviate. MUST include these sections.

Prefer:

Use this format because it helps stakeholders quickly find test status, evidence, and next steps. Adapt the structure when the audience needs a different presentation.

Explain why the format exists so the Skill can adapt without losing the goal.

Mistake 3: Skipping test cases

Test cases catch issues before users do. Even subjective Skills benefit from two or three sample prompts and qualitative review.

Mistake 4: Ignoring timing data

A Skill that takes 10× longer may not be practical. Track timing and token usage alongside output quality.

Mistake 5: Recreating repeated scripts

If every evaluation independently writes generate_report.py, bundle it:

api-tester/
├── SKILL.md
└── scripts/
    └── generate-report.py

Bundled scripts improve consistency and reduce repeated work.

Real-World Skill Examples

MCP Builder Skill

Anthropic’s MCP Builder Skill supports Model Context Protocol server development.

Key features:

Python and Node.js templates
MCP evaluation framework
Best-practices reference documentation

mcp-builder/
├── SKILL.md
├── reference/
│   ├── mcp_best_practices.md
│   ├── python_mcp_server.md
│   └── node_mcp_server.md
└── evaluation/
    └── evaluation.md

Docx Skill

The Docx Skill generates Word documents programmatically.

Key features:

Bundled python-docx scripts
Templates for common documents
Styling guidance for consistent output

Typical workflow:

Understand document requirements.
Select or create a template.
Generate the document with a python-docx script.
Validate the output structure.

Frontend Design Skill

The Frontend Design Skill builds web interfaces with modern implementation patterns.

Key features:

Component libraries
Tailwind CSS patterns
Accessibility checks

It uses progressive disclosure: the core workflow is in SKILL.md, while component-specific documentation lives in references/.

Testing Your Skill with Apidog

If you are building API-related Skills, Apidog can be part of the workflow.

Example: API testing Skill integration

Add an implementation section to your Skill:

## Running API Tests

Use Apidog for systematic testing:

1. Import the OpenAPI specification into Apidog.
2. Generate test cases from the specification.
3. Run tests and export results as JSON.
4. Validate responses against expected schemas.

For custom assertions, use Apidog's scripting feature.

Bundle Apidog scripts

api-tester/
├── SKILL.md
└── scripts/
    ├── run-apidog-tests.py
    └── generate-report.py

Bundling scripts prevents future invocations from recreating the same implementation.

Once you can build your own Skills, design-focused Claude Code Skills show how the same mechanism can support layout generation, component scaffolding, and accessibility review.

If you work across multiple AI coding agents rather than only Claude Code, OpenClaw's tools and Skills system follows a similar modular philosophy.

Conclusion

Claude Code Skills let you capture repeatable development workflows as reusable capabilities.

Use this implementation process:

Define the Skill’s intent and output.
Write a focused SKILL.md.
Create realistic test prompts.
Run each prompt with and without the Skill.
Grade output with reusable assertions.
Compare pass rate, latency, and token usage.
Iterate from reviewer feedback.
Optimize the frontmatter description for trigger accuracy.
Package the finished Skill as a .skill file.

FAQ

How long does it take to create a Skill?

Simple Skills take 15–30 minutes. Complex Skills with multiple reference files, bundled scripts, and evaluation iterations can take two to three hours.

Do I need test cases for every Skill?

No. Skills with verifiable outputs, such as code generation, file transforms, and data extraction, benefit most from formal test cases. Subjective tasks such as writing style or design quality are often better evaluated qualitatively.

What if my Skill does not trigger reliably?

Improve the description field in SKILL.md. Add specific trigger phrases and relevant contexts, then run the description optimization loop with 20 trigger evaluation queries.

How do I share Skills with my team?

Package the Skill:

python -m scripts.package_skill <path>

Then distribute the generated .skill file. Team members place it in their Skills directory.

Can Skills call external APIs?

Yes. Bundle scripts that call external APIs and document when to run them. Store API keys in environment variables rather than in the Skill package.

What is the file size limit for Skills?

There is no hard limit, but keep SKILL.md under 500 lines. Move detailed documentation to reference files. Scripts and assets load on demand and do not count toward the core instruction limit.

How do I update an existing Skill?

Copy the installed Skill to a writable location, make changes there, and repackage it. Preserve the original name unless you are intentionally creating a separate variant.

What is API Management?

Preecha — Mon, 03 Aug 2026 01:01:31 +0000

APIs are the backbone of modern software: they connect systems, enable digital business, and power the applications users rely on. As an organization adds more APIs, it needs consistent controls for security, reliability, documentation, and change management. API management provides that operating model.

Try Apidog today

What Is API Management?

API management is the process of designing, publishing, securing, monitoring, analyzing, and evolving APIs in a scalable and reliable way.

In practice, it combines tools, policies, and team workflows to help you:

Control who can access an API and which operations they can perform
Monitor traffic, latency, errors, and uptime
Protect APIs from unauthorized access and abuse
Publish accurate documentation for API consumers
Version APIs without unexpectedly breaking clients
Scale API infrastructure as demand grows

The goal is not simply to create endpoints. It is to govern APIs throughout their lifecycle so they remain useful, secure, and maintainable.

Why API Management Matters

Without a management strategy, each new API can add operational and security risk.

Common problems include:

Security risks: Public or partner-facing APIs can become attack vectors without authentication, authorization, rate limits, and encryption.
Version sprawl: Consumers may depend on different versions, making changes difficult to coordinate.
Performance issues: Unmonitored APIs can experience slow responses, elevated error rates, or downtime without timely detection.
Developer friction: Missing or outdated documentation slows integrations and increases support requests.

API management addresses these issues with consistent standards and visibility across internal, customer-facing, and partner APIs.

Core Components of API Management

API management is a set of coordinated practices rather than a single feature.

1. API Gateway

An API gateway is the entry point for API traffic. It can route incoming requests to backend services while applying shared policies before traffic reaches those services.

Typical gateway responsibilities include:

Request routing
Authentication and authorization enforcement
Rate limiting
Request and response transformations
Centralized logging

For example, a gateway can reject requests without a valid token before they reach an internal service:

GET /v1/orders/123
Authorization: Bearer <access-token>

2. Security and Access Control

API security starts with identifying the caller and limiting what that caller can do.

A practical baseline includes:

Authentication: Verify the identity of a user, application, or service.
Authorization: Restrict access to specific resources and operations.
Rate limiting: Limit repeated requests to reduce abuse and protect backend capacity.
Encryption in transit: Use HTTPS to protect data while it moves between clients and services.
Audit logging: Record API activity for troubleshooting and compliance needs.

For example, define access by scope instead of granting every client unrestricted access:

{
  "sub": "partner-service",
  "scope": "orders:read inventory:read"
}

A client with this scope can read orders and inventory but cannot create or cancel orders.

3. Analytics and Monitoring

Monitoring helps teams understand whether APIs are healthy and how consumers use them.

Track metrics such as:

Request volume
Response latency
Error rates
Uptime
Most-used endpoints
Consumer or application usage patterns

Useful alerts might include:

Error rate exceeds a defined threshold
Latency rises above an acceptable limit
A client exceeds its expected request volume
Authentication failures suddenly increase

These signals help teams detect incidents early and prioritize improvements based on real usage.

4. Documentation and Developer Portals

Documentation should be treated as part of the API, not as a separate afterthought.

A useful API reference should include:

Endpoint paths and HTTP methods
Request parameters and request bodies
Authentication requirements
Response schemas
Error response formats
Working request examples

For example:

POST /v1/orders
Content-Type: application/json
Authorization: Bearer <access-token>

{
  "productId": "prod_123",
  "quantity": 2
}

Interactive documentation and developer portals can also let consumers explore endpoints and try requests in the browser.

5. Lifecycle Management

API management covers the full lifecycle:

Design the API contract.
Build and test the implementation.
Publish and deploy the API.
Monitor usage and performance.
Version, update, or retire the API safely.

Managing this lifecycle reduces the chance that an unreviewed change becomes a production-breaking change.

API Management in Practice

Example 1: E-Commerce Platform

An online retailer may expose APIs for inventory, orders, and shipping. When it starts integrating with third-party logistics providers, it needs to:

Authenticate each partner application
Restrict partners to the endpoints they need
Monitor usage by partner
Limit traffic to prevent backend overload
Maintain documentation for integration teams

API management provides the shared security controls, usage visibility, and documentation needed to support those integrations.

Example 2: Mobile App Backend

A mobile application may depend on APIs for user profiles, content, and notifications. The backend team needs to:

Release new API versions without breaking older app versions
Detect traffic spikes after a mobile release
Provide reliable documentation for external integration developers
Monitor latency and errors by endpoint

A managed lifecycle makes it easier to support both existing clients and new features.

For example, instead of silently changing an existing response shape, introduce a versioned endpoint:

GET /v1/users/42
GET /v2/users/42

Then publish a deprecation timeline before retiring the older version.

Example 3: FinTech Compliance

Financial services APIs often handle sensitive information and operate under strict regulatory requirements.

API management can help enforce that:

Only authorized applications access sensitive resources
API calls are logged for audits
Encryption policies are consistently applied
Access rules are centrally managed
Security controls are applied across all relevant endpoints

The key is consistency: each API should follow the same security and audit expectations rather than relying on ad hoc implementation choices.

Key Benefits of API Management

A practical API management program can deliver:

Enhanced security: Apply authentication, authorization, rate limits, and encryption consistently.
Improved performance: Use monitoring, caching, load balancing, and traffic controls to keep APIs responsive.
Developer productivity: Provide self-service documentation and clear onboarding paths.
Business agility: Release, update, version, and retire APIs with repeatable processes.
Usage visibility: Understand which APIs and consumers drive the most traffic.
Monetization support: Track usage when APIs are offered to external consumers under billing or quota models.

How API Management Tools Work

API management platforms combine common API workflow tasks in one place. Typical capabilities include:

Visual API design: Define endpoints, parameters, request bodies, and responses.
Mocking and testing: Simulate expected API behavior before backend services are ready.
Automated documentation: Generate and publish interactive API references from a maintained specification.
Monitoring dashboards: Review API health, traffic, and usage patterns.

These tools can also fit into CI/CD pipelines, version control workflows, and cloud infrastructure.

A practical workflow looks like this:

Define API contract
        ↓
Review and validate the contract
        ↓
Mock and test client integrations
        ↓
Implement backend service
        ↓
Deploy through CI/CD
        ↓
Monitor traffic, errors, and latency
        ↓
Version or retire when needed

API Management Lifecycle: From Creation to Retirement

1. Design

Start with an API contract before implementation.

Define:

Resource names and endpoint paths
HTTP methods
Request and response schemas
Authentication requirements
Error formats
Versioning strategy

For example, establish a consistent error response shape:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Order not found"
  }
}

Use collaborative, spec-driven design tools such as Apidog to review the contract before implementation begins.

2. Development and Testing

Build the API against the agreed contract and validate expected behavior.

Test at least:

Valid requests
Invalid request payloads
Authentication failures
Authorization failures
Not-found responses
Rate-limit behavior
Error response consistency

Mock servers can help frontend and backend teams work in parallel while the production backend is still being built.

3. Deployment and Versioning

Before deployment:

Validate the API contract in CI
Verify authentication and authorization rules
Confirm logs and monitoring are enabled
Test rollback procedures
Document any client-impacting changes

For breaking changes, prefer a clear versioning strategy. Keep older versions available long enough for consumers to migrate, then communicate deprecation dates and migration steps.

4. Monitoring and Analytics

After release, monitor both technical health and consumer behavior.

Track:

Requests per minute
p95 latency
4xx and 5xx error rates
Availability
Top endpoints
Top API consumers

Set alerts for unusual error rates, traffic spikes, and latency regressions so teams can respond before consumers are broadly affected.

5. Maintenance and Retirement

APIs need ongoing maintenance as requirements, dependencies, and security expectations change.

When retiring an API version:

Identify active consumers.
Publish the replacement API and migration guidance.
Communicate a deprecation date.
Monitor remaining traffic to the old version.
Remove the old version after the announced sunset period.

This process reduces disruption for clients that depend on your API.

How Apidog Simplifies API Management

Apidog can support a centralized API workflow with features such as:

Spec-driven design: Create and organize APIs visually from first draft through production.
Instant mocking: Generate mock endpoints so frontend and backend development can proceed in parallel.
Collaborative documentation: Publish live, interactive documentation for internal teams and external partners.
Testing and requests: Debug, test, and monitor APIs from an integrated interface.

Centralizing these activities helps teams reduce inconsistencies, catch issues earlier, and ship integrations with a more repeatable workflow.

Common API Management Challenges and Solutions

Challenge: API Sprawl and Inconsistent Documentation

When APIs are designed and documented independently, consumers may encounter inconsistent naming, error formats, and authentication approaches.

Solution: Use a centralized API management workflow to organize APIs, maintain shared standards, and keep documentation aligned with implementation.

Challenge: Security Vulnerabilities in Public or Partner APIs

Public and partner APIs may be exposed to unauthorized access, excessive traffic, or misuse.

Solution: Enforce authentication, authorization, encryption, rate limiting, and audit logging through shared API management policies.

Challenge: Managing Multiple API Versions

Supporting multiple versions without a plan can create confusion and expensive maintenance work.

Solution: Define versioning rules, document breaking changes, publish migration guidance, and use clear deprecation policies.

Best Practices for Successful API Management

Document every API change. Update the API contract and reference documentation whenever behavior changes.
Automate security checks. Enforce authentication, authorization, and policy validation consistently.
Monitor everything. Track latency, errors, availability, traffic, and consumer behavior.
Use consistent conventions. Standardize naming, status codes, pagination, error responses, and versioning.
Involve stakeholders early. Include developers, QA, operations, security, and API consumers in design and review.
Test before release. Validate both happy paths and failure scenarios in automated pipelines.
Plan deprecations. Give consumers time and guidance to migrate before retiring older API versions.
Use modern platforms. A tool such as Apidog can bring design, documentation, mocking, testing, and collaboration into one workflow.

Conclusion: Mastering API Management

API management is more than handling endpoints. It is the practice of applying the right controls, documentation, security, monitoring, and lifecycle processes to make APIs reliable business assets.

Start with these next steps:

Inventory your current APIs and their consumers.
Identify gaps in security, documentation, versioning, and monitoring.
Define shared API standards for contracts, errors, authentication, and deprecation.
Adopt a centralized workflow or platform such as Apidog to manage API design, testing, and documentation.

Healthcare API: A Complete Guide for Seamless Healthcare Data

Preecha — Sun, 02 Aug 2026 13:01:26 +0000

A healthcare API (Application Programming Interface) lets healthcare software systems exchange data securely and consistently. It acts as a bridge between electronic health records (EHRs), hospital management systems, laboratory information systems, mobile health apps, and wearable devices.

Try Apidog today

Healthcare organizations often depend on disconnected systems. Without interoperability, patient data remains in silos, creating delays, manual work, and opportunities for data-entry errors. A well-designed healthcare API helps deliver the right data to the right authorized system for care delivery, billing, compliance, and analytics.

Why Healthcare APIs Matter

Healthcare APIs are not just integration conveniences. They support core healthcare workflows:

Interoperability: Connect systems built with different technologies and standards.
Patient-centric care: Let patients access, share, and manage health data across providers and devices.
Regulatory compliance: Support secure sharing, access controls, and auditability for requirements such as HIPAA and GDPR.
Innovation: Enable developers to build telemedicine apps, patient portals, diagnostic tools, and other digital-health products.
Operational efficiency: Automate data exchange to reduce administrative work and manual errors.

Core Components of a Healthcare API

When designing a healthcare API, define these components early.

Component	What it does	Example
Endpoints	Expose operations and resources to client applications	`/patients`, `/appointments`, `/medications`
Data models and standards	Define how healthcare information is structured	FHIR, HL7, DICOM
Authentication and authorization	Restrict access to approved users and systems	OAuth 2.0, API keys, JWTs
Documentation	Explains requests, responses, errors, and authentication	OpenAPI-based API docs
Versioning	Supports safe API changes over time	`/v1/patients`, `/v2/patients`

For example, a patient endpoint should define:

Which fields are returned.
Which roles can read or update the resource.
Which standard the payload follows.
Expected success and error responses.
How clients migrate when the endpoint changes.

Tools such as Apidog can help teams create, test, and share API documentation collaboratively.

Healthcare API Standards: FHIR, HL7, and DICOM

Healthcare APIs commonly use established standards to make integrations more consistent.

FHIR (Fast Healthcare Interoperability Resources)

FHIR is a modern standard for exchanging healthcare information electronically. It supports RESTful APIs and commonly uses JSON or XML, which makes it suitable for web-based integrations.

A request to retrieve a patient might look like this:

GET /Patient/12345 HTTP/1.1
Host: api.healthcareprovider.com
Authorization: Bearer {access_token}
Accept: application/fhir+json

The API can return a standardized FHIR JSON representation of the patient resource.

HL7 (Health Level Seven)

HL7 v2 and v3 are widely used standards for structured clinical and administrative data exchange. HL7 v2 integrations often use pipe-separated message formats and are common in established healthcare environments.

DICOM (Digital Imaging and Communications in Medicine)

DICOM is designed for medical imaging, including X-rays, CT scans, and MRIs. DICOM APIs support secure exchange of imaging data between radiology systems, healthcare providers, and other authorized systems.

How Healthcare APIs Work

A typical healthcare API request follows this workflow:

Request: An authorized application requests data, such as a patient’s lab results.
Validation: The API authenticates the requester, verifies permissions, and validates the request.
Processing: The API queries an EHR database, imaging repository, or another underlying system.
Response: The API returns data in a standardized format, such as FHIR JSON.
Logging and auditing: The system records the action for traceability and compliance.

A simplified response could look like this:

{
  "resourceType": "Patient",
  "id": "12345",
  "name": [
    {
      "family": "Smith",
      "given": ["Jordan"]
    }
  ]
}

Modern API platforms such as Apidog can streamline API design, documentation, mocking, and testing during these integration cycles.

Key Benefits of Healthcare APIs

Healthcare APIs provide practical benefits across clinical and operational teams:

Improved data access: Authorized clinicians, patients, and applications can retrieve current health information from multiple systems.
Better patient engagement: Patients can access records, connect wearable devices, and use approved third-party health apps.
Greater efficiency: Automated integrations reduce paperwork and administrative delays.
Scalability: APIs support new systems, services, and digital-health initiatives as an organization grows.
Data security: APIs can enforce access controls, encryption, and auditing for sensitive medical information.

Practical Healthcare API Use Cases

1. Patient Health Records Access

A patient portal can use healthcare APIs to combine records from hospital EHRs, specialty clinics, and wearable devices. This gives patients a unified view of their health information without requiring each source system to be accessed separately.

2. Telemedicine Integration

Telehealth platforms use APIs to schedule appointments, exchange patient notes, and update EHRs. After a virtual consultation, for example, a telemedicine application can post provider notes to the hospital EHR through an authorized API integration.

3. e-Prescribing and Pharmacy Coordination

Clinics and pharmacies use APIs to process e-prescriptions, check drug interactions, and update medication records. This reduces manual re-entry and can improve prescription accuracy.

4. Medical Imaging Exchange

Radiology systems use DICOM APIs to send, receive, and view medical images across healthcare networks. This supports remote consultations and can speed up diagnosis workflows.

5. Healthcare Analytics and Research

Healthcare APIs can provide de-identified, aggregated data to analytics platforms for population-health studies, AI diagnostics, and operational analysis while maintaining appropriate privacy controls.

6. Insurance and Billing Automation

Billing systems can connect to hospital management software through APIs to verify coverage, submit claims, and track payments automatically.

How to Build and Test a Healthcare API

Use the following implementation process when building a healthcare API.

1. Define Requirements and Select Standards

Start by mapping the workflow your API must support.

Choose the relevant data standard: FHIR, HL7, or DICOM.
Identify the resources your clients need, such as patients, appointments, medications, or observations.
Define the users and systems that need access.
Document the minimum data each use case requires.

For example:

Use case: Retrieve a patient's active medications
Resource: MedicationRequest
Method: GET
Endpoint: /patients/{patientId}/medications
Access: Authorized clinician or approved patient application
Response format: FHIR JSON

2. Design the API Specification

Create an API contract before implementing the service.

Define:

Paths and HTTP methods.
Request parameters and body schemas.
Success and error responses.
Authentication requirements.
Versioning strategy.

For example:

GET /v1/patients/12345/medications HTTP/1.1
Authorization: Bearer {access_token}
Accept: application/fhir+json

Use an API design platform such as Apidog to draft endpoints, data models, and authentication flows. Interactive documentation also helps backend, frontend, QA, and integration teams work from the same contract.

3. Implement Security Controls

Security must be part of the design, not a later addition.

Enforce authentication and authorization, such as OAuth 2.0.
Encrypt data in transit with HTTPS.
Protect stored data with appropriate encryption controls.
Apply least-privilege access rules.
Log API activity for auditing and incident investigation.
Validate all input to reduce malformed or unauthorized requests.

A basic authorization check should ensure that a valid token alone is not enough; the authenticated client must also have permission to access the requested patient resource.

4. Mock and Test Endpoints

Before connecting to production healthcare systems, test against predictable mock responses.

Test at least:

Valid requests and expected responses.
Missing or invalid authentication.
Unauthorized resource access.
Invalid request parameters.
Empty result sets.
Error response formats.
Performance under expected load.

For example, define an error response your clients can handle consistently:

{
  "error": {
    "code": "forbidden",
    "message": "The requester is not authorized to access this resource."
  }
}

Apidog’s mocking features can simulate responses for frontend development and QA testing before a live EHR, pharmacy, or imaging system is available.

5. Deploy and Monitor

Deploy the API in a secure, scalable environment and monitor it continuously.

Track:

Availability and uptime.
Response times.
Error rates.
Authentication failures.
Unusual traffic patterns.
Suspicious access attempts.

Monitoring and logs are especially important for healthcare integrations because they support both operational troubleshooting and compliance audits.

6. Maintain and Evolve the API

Healthcare systems and integrations change over time. Plan for that change.

Version APIs to preserve backward compatibility.
Keep documentation synchronized with implementation.
Review permissions and security controls regularly.
Update dependencies and security protocols.
Communicate breaking changes to integration partners before rollout.

Healthcare API Security and Compliance

Healthcare APIs handle sensitive patient information, so security and compliance are mandatory implementation concerns.

Access Controls

Only approved users, services, and applications should access protected healthcare data. Apply authentication, role-based permissions, and least-privilege rules.

Audit Trails

Log each API action with enough context for traceability, including the requester, endpoint, timestamp, outcome, and relevant resource identifiers.

Data Minimization

Return only the data required for the request. Avoid exposing full patient records when a client needs only a specific field or resource.

De-Identification

For research and analytics workflows, support data anonymization or de-identification where required.

Regulatory Alignment

Ensure your API design and operational controls align with HIPAA, GDPR, and other applicable regulations.

Apidog can help teams document and test security requirements as part of their healthcare API projects.

Challenges in Healthcare API Development

Healthcare APIs introduce integration challenges that developers should plan for.

Legacy system integration: Many providers still depend on older systems with limited modern API support.
Inconsistent standard implementations: Vendors may implement FHIR and other standards differently, which can create interoperability gaps.
Data privacy risks: Weak authorization or poor API design can expose sensitive health data.
Change management: New integrations require training, workflow updates, and stakeholder buy-in.

Mitigate these risks by validating integrations early, using realistic test data, documenting assumptions, and introducing changes incrementally.

Best Practices for Healthcare API Implementation

Use these practices as an implementation checklist:

Adopt industry standards: Use FHIR, HL7, or DICOM where appropriate.
Design security from day one: Include authentication, authorization, encryption, and audit logging in the API contract.
Document every endpoint: Include schemas, examples, authentication requirements, and error responses.
Version deliberately: Make backward-compatible changes where possible and communicate updates clearly.
Test integrations, not only endpoints: Verify that real client workflows work across EHRs, pharmacy systems, imaging platforms, and other connected services.
Monitor and audit continuously: Detect unusual behavior and respond quickly to potential incidents.
Expose the minimum necessary data: Apply data minimization to every endpoint and use case.

Conclusion: The Future of Healthcare APIs

Healthcare APIs are becoming a core part of modern digital healthcare. They enable secure, interoperable, and patient-centered data exchange across clinical, operational, and patient-facing systems.

For developers, the practical focus is clear: choose the right standards, define a precise API contract, enforce access controls, test realistic workflows, and maintain strong documentation and monitoring. Platforms such as Apidog can help accelerate the path from API design to deployment while keeping healthcare integrations robust, secure, and maintainable.

How to Use Supabase CLI: The Complete Developer Guide (2026)

Preecha — Sun, 02 Aug 2026 01:01:56 +0000

TL;DR

Supabase CLI runs a full Supabase stack on your machine using Docker: PostgreSQL, Auth, Storage, and Edge Functions. Install it with brew install supabase/tap/supabase, run supabase init and supabase start to create a local environment, then use supabase db push and supabase functions deploy to ship to production.

Try Apidog today

Introduction

73% of backend bugs get caught in production because developers skip local testing. Supabase CLI gives you a production-equivalent environment on your machine in under five minutes.

The usual alternatives are risky or slow:

Testing in production: schema changes can break teammates or live users.
Hand-built local environments: manually configured PostgreSQL instances often drift from the cloud setup.
Hardcoded function tests: Edge Functions may work with mock values but fail with real environment variables.

Supabase CLI uses Docker to run a local stack that mirrors Supabase Cloud, including PostgreSQL, Auth, Storage, Realtime, Studio, and Edge Functions.

If you are building APIs on top of Supabase, use an API client to test endpoints while you build them. Apidog can connect to Supabase REST and GraphQL APIs so you can test local endpoints, validate RLS behavior, and document requests as part of development.

By the end of this guide, you will be able to:

Set up a complete local Supabase environment
Manage schema changes with version-controlled migrations
Build and test Edge Functions locally
Generate TypeScript types from your schema
Deploy database changes and functions to production

Why local Supabase development breaks without the CLI

Without the CLI, local development usually fails in predictable ways.

The “test in production” trap

You add a column in the Supabase dashboard, verify it works, and deploy your frontend. A teammate pulls the repository later, but their database does not contain that column.

The fix: create a migration for every schema change and commit it to Git.

The environment mismatch

You create a local PostgreSQL database and manually recreate your schema. Then Row Level Security behavior appears different from production.

In practice, the RLS engine is not the issue—you likely missed a policy, extension, trigger, or configuration setting.

The fix: run the Supabase stack locally instead of recreating pieces manually.

The “works on my machine” Edge Function

An Edge Function works with hardcoded test data but fails after deployment because production secrets or environment variables are missing.

The fix: serve functions locally and test them with real requests and local environment variables.

Supabase CLI addresses these issues with:

Version-controlled SQL migrations
A Docker-based local stack matching Supabase services
Local Edge Function serving
Repeatable resets and seed data

How Supabase CLI works

The local stack

Run the following command:

supabase start

The CLI starts a Docker Compose stack with these services:

Service	Port	Purpose
PostgreSQL	`54322`	Your database
PostgREST	`54321`	Auto-generated REST API
GoTrue	`54321/auth`	Authentication service
Realtime	`54321/realtime`	WebSocket subscriptions
Storage	`54321/storage`	File storage
Studio	`54323`	Visual dashboard
Inbucket	`54324`	Local email testing
Edge Runtime	`54321/functions`	Deno-based function runner

This is the same stack used by Supabase Cloud, running locally.

Install the CLI

macOS

brew install supabase/tap/supabase

Windows with Scoop

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Linux or npm

npm install -g supabase

Verify the installation:

supabase --version
# supabase 1.x.x

Docker Desktop must be running before you run supabase start. Otherwise, the CLI cannot connect to the Docker daemon.

Initialize a project

Create a project directory and initialize Supabase:

mkdir my-project && cd my-project
supabase init

This creates the Supabase project structure:

supabase/
├── config.toml       # Ports, auth settings, storage config
├── seed.sql          # Development data loaded on db reset
└── migrations/       # Version-controlled schema history

Start the local environment

supabase start

The first run downloads Docker images. Later starts are much faster.

The CLI prints local connection details similar to:

API URL: http://localhost:54321
DB URL:  postgresql://postgres:postgres@localhost:54322/postgres
Studio:  http://localhost:54323
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Add the local API URL and anon key to your frontend environment file:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key

Database management with migrations

Migrations are the core CLI workflow. Each schema change becomes a timestamped SQL file that you can review, commit, and apply consistently.

Create a migration

Generate a migration file:

supabase migration new create_posts_table

This creates a file similar to:

supabase/migrations/20260324120000_create_posts_table.sql

Add your schema, policies, and triggers:

-- Create posts table with RLS from the start
CREATE TABLE posts (
  id          UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id     UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title       TEXT NOT NULL,
  content     TEXT,
  published   BOOLEAN DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Anyone can read published posts
CREATE POLICY "Anyone can read published posts"
  ON posts FOR SELECT
  USING (published = true);

-- Users manage their own posts
CREATE POLICY "Users manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

-- Auto-update updated_at on every change
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER posts_updated_at
  BEFORE UPDATE ON posts
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

Apply pending migrations to your local database:

supabase migration up

Generate TypeScript types

Regenerate types after every schema change:

supabase gen types typescript --local > src/types/database.ts

Use the generated types in your app:

import { Database } from '@/types/database'

type Post = Database['public']['Tables']['posts']['Row']
type NewPost = Database['public']['Tables']['posts']['Insert']

const createPost = async (post: NewPost) => {
  const { data, error } = await supabase
    .from('posts')
    .insert(post)
    .select()
    .single()

  return data
}

Your editor can now catch invalid column names, missing required fields, and incorrect types before runtime.

Seed development data

Put repeatable local data in supabase/seed.sql:

-- Test users for local development
INSERT INTO auth.users (id, email) VALUES
  ('00000000-0000-0000-0000-000000000001', 'alice@example.com'),
  ('00000000-0000-0000-0000-000000000002', 'bob@example.com');

-- Test posts
INSERT INTO posts (user_id, title, content, published) VALUES
  (
    '00000000-0000-0000-0000-000000000001',
    'Getting started with Supabase',
    'Here is what I learned...',
    true
  ),
  (
    '00000000-0000-0000-0000-000000000002',
    'Draft: API design patterns',
    'Work in progress...',
    false
  );

Reset the database, rerun all migrations, and reload seed data:

supabase db reset

Run this after pulling migrations from teammates or whenever you need a clean local state.

Testing Supabase APIs with Apidog

Once Supabase is running locally, PostgREST exposes a REST API at:

http://localhost:54321/rest/v1

Every table gets API endpoints automatically. Testing them with curl works for quick checks, but it becomes tedious when you need to verify RLS policies with multiple users and tokens.

Apidog can connect to your local Supabase instance so you can:

Save requests as reusable collections
Switch environments to test as different users
Add assertions to API responses
Run API checks after RLS changes
Share API documentation with your team

Configure Apidog for local Supabase

Create a project in Apidog.
Set the base URL to http://localhost:54321.
Add an environment variable named anon_key.
Set its value to your local Supabase anon key.
Add these request headers:

Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}

Test the posts endpoint

Create a request:

GET http://localhost:54321/rest/v1/posts?published=eq.true
Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}

Save the request and add an assertion that the response contains at least one post. Run it whenever you modify RLS policies to catch broken access rules before deployment.

Edge Functions: build and test locally

Supabase Edge Functions run on Deno. Use them for webhooks, background jobs, or endpoints that require server-side logic.

Create a function

Generate a new function:

supabase functions new send-welcome-email

This creates:

supabase/functions/send-welcome-email/index.ts

Implement the function:

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user_id } = await req.json()

  // Service role bypasses RLS. Use it only in server-side code.
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  const { data: profile } = await supabase
    .from('profiles')
    .select('email, full_name')
    .eq('id', user_id)
    .single()

  // Your email sending logic here
  console.log(`Sending welcome email to ${profile?.email}`)

  return new Response(
    JSON.stringify({ success: true }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

Serve functions locally

Start the local function server:

supabase functions serve

The server watches files and reloads when your code changes.

Test the function:

curl -X POST http://localhost:54321/functions/v1/send-welcome-email \
  -H "Authorization: Bearer YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "00000000-0000-0000-0000-000000000001"}'

Deploy functions

Deploy one function:

supabase functions deploy send-welcome-email

Deploy all functions:

supabase functions deploy

Advanced techniques and proven approaches

Manage secrets

Do not hardcode API keys in Edge Functions. Store production secrets with the CLI:

# Set production secrets
supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx

# List secrets
supabase secrets list

# Remove a secret
supabase secrets unset STRIPE_KEY

Read secrets inside a function:

const resendKey = Deno.env.get('RESEND_API_KEY')

Avoid this:

const resendKey = 're_xxx'

Use database branches

For larger schema work, use an isolated branch:

supabase branches create feature-payments
supabase branches switch feature-payments

# Make changes and test them

supabase branches merge feature-payments

This keeps the main development database clean while you experiment.

Avoid common mistakes

Editing the database directly in Studio

Use migrations for schema changes. Direct Studio edits are not tracked in Git and are easy for teammates to miss.

Committing `.env` files

Keep local environment files out of Git:

.env*

Use supabase secrets set for production secrets.

Skipping `supabase db reset` after pulling

After pulling new migrations, reset your local database:

supabase db reset

This ensures your schema and seed data match the repository.

Forgetting to regenerate types

After adding or changing columns, run:

supabase gen types typescript --local > src/types/database.ts

Deploying functions without local tests

Run supabase functions serve and test real request payloads before deploying.

Using the service role key in frontend code

The service role key bypasses RLS. Keep it in Edge Functions and other server-side code only—never expose it in a browser.

Reduce local resource usage

Exclude services you do not need:

supabase start --exclude-studio --exclude-inbucket

Check Docker resource consumption:

docker stats

Alternatives and comparisons

Feature	Supabase CLI	Firebase CLI	PlanetScale CLI
Local database	Full PostgreSQL	Emulator only	Cloud only
Migrations	SQL files in Git	No native support	Branching
Edge Functions	Deno runtime	Cloud Functions	Not included
Auth locally	Full GoTrue	Emulator	Not included
Open source	Fully open	Proprietary	Proprietary
Type generation	Built-in	Manual	Manual

Firebase’s local emulator is useful for quick prototyping, but it does not provide a full PostgreSQL instance. PlanetScale has a strong branching workflow for schema changes, but development remains cloud-based.

Supabase CLI is a good fit when you need an open-source, PostgreSQL-native local development environment.

Real-world use cases

SaaS applications with multi-tenant data

A fintech startup manages 47 migrations across development, staging, and production. The team tests RLS policies locally with different user roles before deployment, preventing schema-related production incidents.

E-commerce order processing

An e-commerce team uses Edge Functions for Stripe webhook processing. They test webhook payloads locally with supabase functions serve and Stripe test events before deployment.

Mobile app backends

A React Native team generates TypeScript types after every migration and shares them as an internal npm package. Frontend and backend developers stay aligned on field names and API response shapes.

Wrapping up

With Supabase CLI, you can:

Run a complete Supabase stack locally
Version-control schema changes with migrations
Reset and seed local databases reliably
Generate TypeScript types from your database schema
Test Edge Functions with hot reload
Deploy migrations with supabase db push
Deploy functions with supabase functions deploy
Test Supabase APIs before shipping

Next steps

Install the CLI:

   brew install supabase/tap/supabase

Initialize your project:

   supabase init

Start the local stack:

   supabase start

Create your first migration.
Configure Apidog to test local API endpoints.
Deploy after validating migrations, RLS policies, and Edge Functions locally.

FAQ

Do I need Docker to use Supabase CLI?

Yes. Docker Desktop must be running before supabase start. The CLI uses Docker Compose to run the local stack. If Docker is unavailable, you will see an error such as “Cannot connect to Docker daemon.”

How do I sync my local database with production?

Use supabase db pull to generate a migration from your remote schema, then use supabase db push to apply local migrations to production.

supabase db pull
supabase db reset
supabase db push

Run supabase db reset locally after pulling changes so your local environment matches the migration history.

Can I use Supabase CLI without a Supabase Cloud account?

Yes. You can use the CLI entirely locally without a cloud account. You only need supabase login and supabase link when you are ready to connect to or deploy to a Supabase Cloud project.

How do I handle migration conflicts in a team?

Pull the latest Git changes and reset your local database before creating a new migration:

git pull
supabase db reset

Use descriptive migration names and coordinate with teammates when making breaking changes.

What is the difference between `supabase db push` and `supabase migration up`?

supabase migration up applies pending migrations to your local database.

supabase migration up

supabase db push applies local migrations to your linked remote project.

supabase db push

Test locally before running supabase db push.

Can I use Supabase CLI with an existing project?

Yes. Link your local repository to the existing project, then pull its schema:

supabase link --project-ref YOUR_PROJECT_ID
supabase db pull

How do I test RLS policies locally?

Use Supabase Studio at http://localhost:54323 to inspect your local database, or test API requests using different JWT tokens.

For repeatable checks, create multiple API environments with different user tokens in Apidog and run the same request under each role.

Is Supabase CLI free?

Yes. The CLI is free and open source. Local development does not cost anything. Supabase Cloud costs apply only when you deploy and use cloud resources.