Partner API v1¶

Programmatic access to Vellocity for AWS partners and co-sell integrations.

Overview¶

The Partner API enables you to integrate Vellocity capabilities into your existing workflows and systems. Use it to:

Manage AWS Marketplace listings programmatically
Create and track co-sell opportunities
Access analytics and reports
Configure webhooks for real-time events

Base URL: https://api.vell.ai/api/v1

Authentication¶

All API requests require authentication via API key.

Getting Your API Key¶

Navigate to Settings > API Keys in your dashboard
Click Generate New Key
Copy and securely store your key (shown only once)

Using Your API Key¶

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.vell.ai/api/v1/partners/profile

Security Best Practices¶

Never expose API keys in client-side code
Rotate keys periodically
Use environment variables for key storage
Set up IP allowlisting for production keys

Rate Limiting¶

API requests are rate-limited to ensure platform stability:

Plan	Requests/Minute	Requests/Day
Starter	60	1,000
Business	300	10,000
Enterprise	1,000	100,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1704672000

When rate limited, you'll receive a 429 Too Many Requests response.

Response Format¶

All responses are JSON with consistent structure:

Success Response¶

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Error Response¶

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The listing_id field is required",
    "details": { ... }
  }
}

Common Error Codes¶

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	422	Invalid request parameters
`RATE_LIMITED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error

Endpoints¶

Partner Profile¶

Get Profile¶

Retrieve your partner profile and account information.

GET /partners/profile

Response:

{
  "success": true,
  "data": {
    "id": "partner_123",
    "company_name": "Acme Corp",
    "email": "admin@acme.com",
    "plan": "business",
    "aws_account_connected": true,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Listings¶

List All Listings¶

Retrieve all your AWS Marketplace listings.

GET /partners/listings

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `active`, `draft`, `archived`

Response:

{
  "success": true,
  "data": [
    {
      "id": "listing_456",
      "title": "Enterprise Security Suite",
      "status": "active",
      "marketplace": "aws",
      "seo_score": 85,
      "last_updated": "2025-01-10T14:20:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

Get Single Listing¶

GET /partners/listings/{id}

Response:

{
  "success": true,
  "data": {
    "id": "listing_456",
    "title": "Enterprise Security Suite",
    "short_description": "...",
    "long_description": "...",
    "highlights": ["...", "..."],
    "categories": ["Security", "Compliance"],
    "pricing_model": "subscription",
    "status": "active",
    "seo_score": 85,
    "created_at": "2024-06-01T00:00:00Z",
    "last_updated": "2025-01-10T14:20:00Z"
  }
}

Update Listing¶

PUT /partners/listings/{id}

Request Body:

{
  "title": "Enterprise Security Suite - Updated",
  "short_description": "Updated description...",
  "highlights": ["New highlight 1", "New highlight 2"]
}

Get SEO Score¶

GET /partners/listings/{id}/seo

Response:

{
  "success": true,
  "data": {
    "overall_score": 85,
    "breakdown": {
      "title": 90,
      "description": 80,
      "highlights": 85,
      "keywords": 75,
      "images": 95
    },
    "grade": "A",
    "analyzed_at": "2025-01-10T14:20:00Z"
  }
}

Get Recommendations¶

GET /partners/listings/{id}/recommendations

Response:

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "category": "keywords",
        "priority": "high",
        "suggestion": "Add 'compliance' keyword to title",
        "impact": "+5 SEO score"
      }
    ],
    "total_potential_improvement": 15
  }
}

Co-Sell Operations¶

List Opportunities¶

GET /partners/cosell/opportunities

Query Parameters:

Parameter	Type	Description
`status`	string	Filter: `open`, `in_progress`, `won`, `lost`
`partner_id`	string	Filter by co-sell partner
`created_after`	datetime	Filter by creation date

Response:

{
  "success": true,
  "data": [
    {
      "id": "opp_789",
      "customer_name": "Global Corp",
      "deal_value": 50000,
      "status": "in_progress",
      "partner": {
        "id": "partner_456",
        "company_name": "Partner Inc"
      },
      "created_at": "2025-01-05T09:00:00Z"
    }
  ]
}

Create Opportunity¶

POST /partners/cosell/opportunities

Request Body:

{
  "customer_name": "New Customer Inc",
  "deal_value": 75000,
  "partner_id": "partner_456",
  "description": "Joint implementation project",
  "expected_close_date": "2025-03-15"
}

Get Opportunity¶

GET /partners/cosell/opportunities/{id}

Update Opportunity¶

PATCH /partners/cosell/opportunities/{id}

Request Body:

{
  "status": "won",
  "deal_value": 80000,
  "notes": "Deal closed successfully"
}

Get Opportunity Timeline¶

GET /partners/cosell/opportunities/{id}/timeline

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "type": "created",
        "timestamp": "2025-01-05T09:00:00Z",
        "actor": "user@acme.com"
      },
      {
        "type": "status_changed",
        "from": "open",
        "to": "in_progress",
        "timestamp": "2025-01-08T14:30:00Z"
      }
    ]
  }
}

Analytics¶

Get Summary¶

GET /partners/analytics/summary

Query Parameters:

Parameter	Type	Description
`period`	string	`7d`, `30d`, `90d`, `1y` (default: `30d`)

Response:

{
  "success": true,
  "data": {
    "period": "30d",
    "listings": {
      "total": 5,
      "avg_seo_score": 82
    },
    "cosell": {
      "opportunities": 12,
      "pipeline_value": 450000,
      "won_value": 125000
    },
    "content": {
      "generated": 45,
      "published": 38
    }
  }
}

List Reports¶

GET /partners/analytics/reports

Get Report¶

GET /partners/analytics/reports/{id}

Webhooks¶

Configure webhooks to receive real-time notifications.

List Webhooks¶

GET /partners/webhooks

Response:

{
  "success": true,
  "data": [
    {
      "id": "webhook_123",
      "url": "https://your-app.com/webhooks/vellocity",
      "events": ["listing.updated", "opportunity.created"],
      "active": true,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Webhook¶

POST /partners/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/vellocity",
  "events": ["listing.updated", "opportunity.created", "opportunity.status_changed"],
  "secret": "your_webhook_secret"
}

Delete Webhook¶

DELETE /partners/webhooks/{id}

List Available Events¶

GET /partners/webhooks/events

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "name": "listing.created",
        "description": "Triggered when a new listing is created"
      },
      {
        "name": "listing.updated",
        "description": "Triggered when a listing is modified"
      },
      {
        "name": "opportunity.created",
        "description": "Triggered when a co-sell opportunity is created"
      },
      {
        "name": "opportunity.status_changed",
        "description": "Triggered when opportunity status changes"
      },
      {
        "name": "seo.score_changed",
        "description": "Triggered when SEO score changes significantly"
      }
    ]
  }
}

Test Webhook¶

POST /partners/webhooks/test

Request Body:

{
  "webhook_id": "webhook_123",
  "event": "listing.updated"
}

Webhook Payload Format¶

When events occur, Vellocity sends POST requests to your webhook URL:

{
  "id": "evt_abc123",
  "type": "listing.updated",
  "timestamp": "2025-01-10T14:20:00Z",
  "data": {
    "listing_id": "listing_456",
    "changes": {
      "title": {
        "old": "Old Title",
        "new": "New Title"
      }
    }
  }
}

Verifying Webhooks¶

Validate webhook signatures using the X-Vellocity-Signature header:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

SDK Support¶

Official SDKs are coming soon:

Python SDK
Node.js SDK
PHP SDK

In the meantime, use any HTTP client library with the REST API.

Support¶

Email: api-support@vell.io
Documentation Issues: GitHub
Status Page: status.vell.ai