Partner API v1¶

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

Two API surfaces — read this first

Vellocity exposes two distinct API surfaces. Pick the right one for your integration:

Surface	Use it when...	Docs
Partner API v1 (this section)	You're building direct integrations for your own AWS Marketplace motion — listing management, co-sell tracking, content workflow, webhooks for your own account	API Quickstart, Authentication, MCP Server
Embedded Partner Pilot API	You're a third-party platform (Clazar, Suger, Labra, etc.) embedding Vellocity capabilities into your product to serve other ISVs	Embedded Partner Pilot, Capabilities Reference

The endpoint surfaces and credit accounting are similar between the two. Differences: the 3PI API has stricter scope-based key gating (mcp_access, manage_partner_keys, etc. as callable scopes), supports per-customer billing breakdowns, and offers a sandbox environment for integration testing.

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/v1 requests are authenticated with an OAuth 2.0 bearer token (Laravel Passport). Include it in the Authorization header:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     https://api.vell.ai/api/v1/user

The MCP Server endpoint additionally accepts a partner key (vp3_…). See Authentication for the full flow, scopes, and how to obtain credentials.

Note

Settings → API Keys in the dashboard stores your own AI-provider credentials (OpenAI/Anthropic/Gemini/Bedrock) — it does not issue a Vellocity API token.

Security Best Practices¶

Never expose tokens or partner keys in client-side code
Rotate credentials periodically
Store credentials in environment variables or a secrets manager
Use IP allowlisting for partner keys where available

Rate Limiting¶

Authenticated /api/v1 requests are limited to 60 requests/minute per user (or IP). Partner endpoints (/api/v1/partners/*) use a dedicated throttle:partner limiter that scales by plan tier:

Plan	Requests/minute	Requests/hour
Starter (default)	60	1,200
Accelerate	100	2,000
Command / Enterprise	1,000	20,000

Partner keys (vp3_…) can additionally carry their own per-minute limit and a daily credit limit set at key creation. 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 access token
`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": "accelerate",
    "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:

{
  "event": "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-Vell-Signature header (a bare hex HMAC-SHA256 of the raw body — no sha256= prefix). See Webhooks for the full header set and language examples:

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.ai
Documentation Issues: GitHub
Status Page: status.vell.ai