Skip to main content

API Overview

MACHUPS provides a REST API for programmatic brand generation and management.

Base URL​

Production: https://api.machups.com
Staging: https://staging-api.machups.com

Authentication​

All API requests require an API key in the header:

curl https://api.machups.com/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Getting an API Key​

  1. Sign up at machups.com
  2. Navigate to Settings → API Keys
  3. Click Generate New Key
  4. Copy and secure your API key

Security:

  • Never commit API keys to version control
  • Use environment variables
  • Rotate keys regularly
  • Restrict by IP if possible

Rate Limits​

TierRequests/HourConcurrent Generations
Free101
Starter1003
Pro1,00010
EnterpriseUnlimited50

Rate Limit Headers​

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Handling Rate Limits​

async function generateBrand(data: BrandInput) {
  try {
    const response = await fetch('/api/v1/brands', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      throw new Error(`Rate limited. Retry after ${retryAfter}s`);
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

API Endpoints​

Brands​

MethodEndpointDescription
POST/v1/brandsGenerate new brand
GET/v1/brands/:idGet brand details
GET/v1/brandsList all brands
DELETE/v1/brands/:idDelete brand

Generation​

MethodEndpointDescription
GET/v1/brands/:id/statusGet generation status
POST/v1/brands/:id/regenerateRegenerate specific assets
GET/v1/brands/:id/downloadDownload brand package

Assets​

MethodEndpointDescription
GET/v1/brands/:id/logosGet logo files
GET/v1/brands/:id/tokensGet design tokens
GET/v1/brands/:id/componentsGet components
GET/v1/brands/:id/guidelinesGet guidelines PDF

NFTs​

MethodEndpointDescription
POST/v1/brands/:id/nft/mintMint NFT certificate
GET/v1/brands/:id/nftGet NFT details
GET/v1/nftsList all NFTs

Request/Response Format​

Standard Response​

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-12-06T00:00:00Z",
    "requestId": "req_abc123"
  }
}

Error Response​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid business idea length",
    "details": {
      "field": "businessIdea",
      "constraint": "Must be between 10-500 characters"
    }
  },
  "meta": {
    "timestamp": "2025-12-06T00:00:00Z",
    "requestId": "req_abc123"
  }
}

Error Codes​

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request data
UNAUTHORIZED401Missing/invalid API key
PAYMENT_REQUIRED402Insufficient credits
FORBIDDEN403Access denied
NOT_FOUND404Resource not found
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error
SERVICE_UNAVAILABLE503Temporary outage

SDKs​

JavaScript/TypeScript​

npm install @machups/sdk
import { MACHUPS } from '@machups/sdk';

const machups = new MACHUPS({
  apiKey: process.env.MACHUPS_API_KEY
});

// Generate brand
const brand = await machups.brands.create({
  businessIdea: 'Sustainable coffee delivery',
  targetAudience: 'Urban millennials',
  style: 'modern'
});

// Get status
const status = await machups.brands.getStatus(brand.id);

// Download assets
const assets = await machups.brands.download(brand.id);

Python​

pip install machups
from machups import MACHUPS

machups = MACHUPS(api_key=os.getenv('MACHUPS_API_KEY'))

# Generate brand
brand = machups.brands.create(
    business_idea='Sustainable coffee delivery',
    target_audience='Urban millennials',
    style='modern'
)

# Get status
status = machups.brands.get_status(brand.id)

# Download assets
assets = machups.brands.download(brand.id)

cURL​

# Generate brand
curl -X POST https://api.machups.com/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessIdea": "Sustainable coffee delivery",
    "targetAudience": "Urban millennials",
    "style": "modern",
    "monadAddress": "0x..."
  }'

# Get status
curl https://api.machups.com/v1/brands/brand_abc123/status \
  -H "Authorization: Bearer YOUR_API_KEY"

# Download assets
curl https://api.machups.com/v1/brands/brand_abc123/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o brand-package.zip

Webhooks​

Subscribe to events:

{
  "url": "https://your-app.com/webhooks/machups",
  "events": [
    "brand.created",
    "brand.completed",
    "brand.failed",
    "nft.minted"
  ],
  "secret": "your_webhook_secret"
}

Webhook Events​

{
  "event": "brand.completed",
  "data": {
    "brandId": "brand_abc123",
    "name": "YourBrand",
    "generationTime": 142,
    "assetsReady": true
  },
  "timestamp": "2025-12-06T00:00:00Z"
}

Verifying Webhooks​

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Pagination​

For list endpoints:

GET /v1/brands?page=2&limit=20

Response:

{
  "success": true,
  "data": [
    // Brand objects
  ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 145,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": true
  }
}

Filtering & Sorting​

# Filter by style
GET /v1/brands?style=modern

# Sort by creation date
GET /v1/brands?sort=-createdAt

# Combine filters
GET /v1/brands?style=modern&sort=-createdAt&limit=50

Idempotency​

Use idempotency keys to prevent duplicate requests:

curl -X POST https://api.machups.com/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_key_123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Versioning​

API versions are specified in the URL:

  • v1: Current stable version
  • v2: Beta features (opt-in)

Breaking changes will be introduced in new versions. v1 will be supported for at least 12 months after v2 release.

Status Page​

Check API status: https://status.machups.com

Support​

Next Steps​