Skip to content

Getting Started

This guide walks you through onboarding as a 3PI partner, generating your API key, and making your first capability call — all in under 10 minutes.

Prerequisites

  • A Vellocity team account with Owner access
  • A target integration platform (your application that will call the Vellocity API)

Step 1: Create a 3PI partner

Partners can be created through the Vellocity dashboard or via the API.

  1. Log in to your Vellocity dashboard
  2. Navigate to Team > 3PI Partners
  3. Click Add Partner
  4. Enter the partner organization name and select capabilities
  5. The partner is created in sandbox mode by default
curl -X POST https://api.vell.ai/api/v1/3pi-partners \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "Acme Marketplace",
    "capabilities": [
      "mcp_access",
      "manage_partner_keys",
      "view_usage_metrics",
      "manage_webhooks",
      "sandbox_access"
    ],
    "sandbox": true
  }'

Response:

{
  "data": {
    "id": 42,
    "organization": "Acme Marketplace",
    "role": "partner_3pi",
    "status": "active",
    "sandbox_mode": true,
    "capabilities": ["mcp_access", "manage_partner_keys", "view_usage_metrics", "manage_webhooks", "sandbox_access"],
    "active_keys_count": 1,
    "created_at": "2026-03-15T10:30:00Z"
  },
  "api_key": {
    "id": 1,
    "name": "Default Key",
    "prefix": "vp3_a1b2c3d4",
    "plaintext": "vp3_a1b2c3d4e5f6...full_key_here",
    "warning": "Store this key securely. It will not be shown again."
  }
}

Save your API key

The plaintext API key is only shown once at creation time. Store it securely in your secrets manager or environment variables. If lost, you'll need to create a new key.

Step 2: Store your API key

Store the key in your application's environment:

# .env
VELLOCITY_API_KEY=vp3_a1b2c3d4e5f6...
VELLOCITY_BASE_URL=https://api.vell.ai/api/v1

Never commit API keys to source control. Use your platform's secrets management (AWS Secrets Manager, HashiCorp Vault, etc.).

Step 3: Make your first call

Verify your key works by fetching your partner profile:

curl -s https://api.vell.ai/api/v1/3pi-partners/42 \
  -H "Authorization: Bearer $VELLOCITY_API_KEY" \
  -H "Accept: application/json" | python3 -m json.tool

import os
import requests

API_KEY = os.environ["VELLOCITY_API_KEY"]
BASE_URL = "https://api.vell.ai/api/v1"

resp = requests.get(
    f"{BASE_URL}/3pi-partners/42",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(resp.json())

const API_KEY = process.env.VELLOCITY_API_KEY;
const BASE_URL = "https://api.vell.ai/api/v1";

const resp = await fetch(`${BASE_URL}/3pi-partners/42`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
console.log(await resp.json());

Step 4: Call a capability

Now make a real GTM capability call. Here's an example generating a marketplace listing optimization:

curl -X POST https://api.vell.ai/api/v1/marketplace/seo-score/analyze \
  -H "Authorization: Bearer $VELLOCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "listing_url": "https://aws.amazon.com/marketplace/pp/prodview-xxxxxxxxxxxxx",
    "category_code": "security",
    "brand_keyword": "Acme"
  }'

The endpoint scores a live AWS Marketplace listing, so listing_url must be a valid AWS Marketplace product URL. It returns a job id and status; poll GET /api/v1/marketplace/seo-score/status/{id} for the result. See Marketplace SEO API for the full parameter and response reference.

Sandbox mode

While in sandbox mode, capability calls execute normally but consume zero credits. This lets you build and test your full integration before going live. See the Sandbox Guide for details.

Step 5: Monitor usage

Check your usage to see how credits are being consumed:

curl -s "https://api.vell.ai/api/v1/3pi-partners/42/usage?period=daily" \
  -H "Authorization: Bearer $VELLOCITY_API_KEY" | python3 -m json.tool

{
  "data": {
    "date": "2026-03-15",
    "total_requests": 47,
    "successful_requests": 45,
    "failed_requests": 2,
    "rate_limited_requests": 0,
    "total_credits": 0,
    "total_input_tokens": 15420,
    "total_output_tokens": 8930,
    "avg_response_time_ms": 1240,
    "by_capability": {
      "marketplace_seo": { "requests": 12, "credits": 0 },
      "generate_text": { "requests": 35, "credits": 0 }
    }
  }
}

Credits show as 0 while in sandbox mode.

Step 6: Go live

When your integration is tested and ready:

  1. Go to Team > 3PI Partners
  2. Click the partner name
  3. Click Promote to Production
  4. Confirm the toggle
curl -X POST https://api.vell.ai/api/v1/3pi-partners/42/toggle-sandbox \
  -H "Authorization: Bearer $VELLOCITY_API_KEY"

After toggling, all subsequent API calls consume real credits.

What's next?