X API Playground

A standalone local HTTP server that simulates the X API v2 for testing and development without consuming API credits.

Features

• Complete API compatibility with X API v2 endpoints
• Stateful operations with in-memory state management
• Optional file-based state persistence across server restarts
• Interactive web UI for exploring and testing endpoints
• Usage tracking - Track API usage
• Request validation against OpenAPI specifications
• Error responses matching real API formats
• Configurable rate limiting simulation
• Streaming support
• CORS support for web applications
• OpenAPI-driven endpoint discovery and handling

Prerequisites

• Go 1.21 or later - Download Go

Installation

Option 1: Install from Source (Recommended)

# Clone the repository
git clone https://github.com/xdevplatform/playground.git
cd playground

# Build the binary
go build -o playground ./cmd/playground

# Make it executable (optional)
chmod +x playground

# Move to PATH (optional, for global access)
sudo mv playground /usr/local/bin/

Option 2: Install via go install

go install github.com/xdevplatform/playground/cmd/playground@latest

This will install the playground binary to $GOPATH/bin (or $HOME/go/bin by default).

Make sure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Option 3: Download Pre-built Binary

Check the Releases page for pre-built binaries for your platform.

Verify Installation

playground --help

You should see the playground command help output.

Quick Start

1. Start the server:

   playground start

2. Access the Web UI: Open http://localhost:8080/playground in your browser

3. Make API requests:

   curl -H "Authorization: Bearer test_token" http://localhost:8080/2/users/me

Usage

Commands

• playground start - Start the playground server
  • Flags:
    • --port / -p (default: 8080) - Port to run the server on
    • --host (default: localhost) - Host to bind the server to
    • --refresh - Force refresh of OpenAPI spec cache
• playground status - Check if a server is running
• playground refresh - Refresh OpenAPI spec cache

Examples

Start on custom port:

playground start --port 3000 --host 0.0.0.0

Start with OpenAPI cache refresh:

playground start --refresh

Configuration

Configuration files are stored in ~/.playground/:

• config.json - Playground configuration (optional, uses embedded defaults if not present)
• state.json - Persistent state (if persistence enabled)
• examples/ - Custom example responses (optional)
• .playground-openapi-cache.json - Cached OpenAPI spec

Management Endpoints

The playground provides several management endpoints (not part of X API):

• GET /health - Server health and statistics
• GET /rate-limits - Rate limit configuration and status
• GET /config - View current configuration
• PUT /config/update - Update configuration (temporary, lost on restart)
• POST /config/save - Save configuration to file
• POST /state/reset - Reset state to initial seed data
• GET /state/export - Export state as JSON
• POST /state/import - Import state from JSON
• POST /state/save - Manually save state (if persistence enabled)
• DELETE /state - Delete all state
• GET /endpoints - List all available endpoints

Usage & Cost Tracking Endpoints

The playground tracks API usage and provides cost estimation endpoints. These endpoints provide the same data shown in the Usage tab of the web UI:

• GET /api/credits/pricing - Get pricing configuration for event types and request types
• GET /api/accounts/{account_id}/usage - Get usage data (query params: interval, groupBy)
• GET /api/accounts/{account_id}/cost - Get detailed cost breakdown with billing cycle data and time series

Getting Usage Data Programmatically:

The account_id is your developer account ID, automatically derived from your authentication token. The default token "test" maps to account "0".

# Get complete cost breakdown (same data as Usage tab)
curl http://localhost:8080/api/accounts/0/cost | jq

# Get event type usage breakdown
curl "http://localhost:8080/api/accounts/0/usage?interval=30days&groupBy=eventType" | jq

# Get request type usage breakdown
curl "http://localhost:8080/api/accounts/0/usage?interval=30days&groupBy=requestType" | jq

# Get pricing configuration
curl http://localhost:8080/api/credits/pricing | jq

Note: The /api/accounts/{account_id}/cost endpoint returns all the data shown in the Usage tab, including:

• Total cost and billing cycle information
• Cost breakdowns by event type and request type
• Daily time series data for charts
• Usage statistics

See DOCUMENTATION.md for detailed API documentation.

Documentation

For detailed documentation, see DOCUMENTATION.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Links

• GitHub: https://github.com/xdevplatform/playground
• Issues: https://github.com/xdevplatform/playground/issues