Skip to content

API Overview

Complete API reference for Vows Social AI platform.

Base URL

Production: https://api.vows.social Staging: https://staging-api.vows.social Local: http://localhost:8787

Authentication

All API requests require authentication using JWT tokens.

Getting a Token

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response: 

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user-123",
    "email": "user@example.com"
  }
}

Using the Token

Include the token in the Authorization header:

GET /api/feed/user-123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Core Endpoints

Feed API

Generate and retrieve personalized content feeds.

Full Documentation →

GET    /api/feed/:userId          - Get personalized feed
POST   /api/feed/interaction      - Record user interaction
GET    /api/feed/refresh/:userId  - Force refresh feed

Foundation Model API

Generate embeddings and user representations.

Full Documentation →

POST   /api/embed/content         - Embed content
POST   /api/embed/user            - Get user embedding
GET    /api/embed/user/:id        - Retrieve cached embedding

Vector Store API

Search and manage vector embeddings.

Full Documentation →

POST   /api/vector/search         - Semantic search
POST   /api/vector/upsert         - Upload embeddings
GET    /api/vector/similar/:id    - Find similar content

Discovery API

Discover and search wedding vendors.

POST   /api/discovery/vendors     - Discover new vendors
GET    /api/discovery/search      - Search vendors
GET    /api/discovery/vendor/:id  - Get vendor details

Quality API

Evaluate content and vendor quality.

POST   /api/quality/evaluate      - Evaluate single vendor
POST   /api/quality/batch         - Batch evaluation
GET    /api/quality/score/:id     - Get cached score

Request/Response Format

Standard Request

interface APIRequest {
  // Path parameters
  params?: Record<string, string>;

  // Query parameters
  query?: Record<string, string | number>;

  // Request body
  body?: Record<string, any>;

  // Headers
  headers?: Record<string, string>;
}

Standard Response

interface APIResponse<T> {
  // Response data
  data?: T;

  // Error information
  error?: {
    code: string;
    message: string;
    details?: any;
  };

  // Metadata
  metadata?: {
    latency_ms: number;
    version: string;
    timestamp: string;
  };
}

Success Response

{
  "data": {
    "feed": [...]
  },
  "metadata": {
    "latency_ms": 450,
    "version": "1.0.0",
    "timestamp": "2025-10-11T10:30:00Z"
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid user ID format",
    "details": {
      "field": "userId",
      "expected": "UUID",
      "received": "123"
    }
  },
  "metadata": {
    "timestamp": "2025-10-11T10:30:00Z"
  }
}

Error Codes

Client Errors (4xx)

Code HTTP Status Description
INVALID_REQUEST 400 Malformed request body
UNAUTHORIZED 401 Missing or invalid token
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
VALIDATION_ERROR 422 Invalid input data
RATE_LIMIT_EXCEEDED 429 Too many requests

Server Errors (5xx)

Code HTTP Status Description
INTERNAL_ERROR 500 Unexpected server error
SERVICE_UNAVAILABLE 503 Service temporarily unavailable
TIMEOUT 504 Request timeout

Rate Limiting

Limits

  • Free tier: 100 requests/hour
  • Pro tier: 1000 requests/hour
  • Enterprise: Unlimited

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1634567890

Exceeded Limit

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 15 minutes.",
    "details": {
      "limit": 1000,
      "reset": "2025-10-11T11:00:00Z"
    }
  }
}

Pagination

For endpoints returning lists, use cursor-based pagination:

Request

GET /api/feed/user-123?limit=20&cursor=abc123

Parameters: - limit - Number of items (max 100, default 20) - cursor - Pagination cursor from previous response

Response

{
  "data": {
    "items": [...],
    "pagination": {
      "nextCursor": "def456",
      "hasMore": true,
      "total": 150
    }
  }
}

Filtering & Sorting

Filtering

GET /api/discovery/search?region=Melbourne&style=modern&minQuality=0.8

Common filters: - region - Geographic region - style - Style category - vendorType - Vendor category - minQuality - Minimum quality score - dateRange - Date range filter

Sorting

GET /api/feed/user-123?sortBy=quality&sortOrder=desc

Sort options: - sortBy - Field to sort by (quality, recency, relevance) - sortOrder - asc or desc

Batch Operations

Batch Requests

POST /api/batch

Request: 

{
  "requests": [
    {
      "method": "GET",
      "path": "/api/feed/user-123"
    },
    {
      "method": "POST",
      "path": "/api/quality/evaluate",
      "body": { "vendorId": "vendor-456" }
    }
  ]
}

Response: 

{
  "responses": [
    {
      "status": 200,
      "data": { "feed": [...] }
    },
    {
      "status": 200,
      "data": { "qualityScore": 0.87 }
    }
  ]
}

Webhooks

Subscribe to real-time events.

Available Events

  • feed.generated - New feed created
  • interaction.recorded - User interaction logged
  • quality.evaluated - Quality score computed
  • vendor.discovered - New vendor found

Subscribe

POST /api/webhooks

Request: 

{
  "url": "https://your-app.com/webhook",
  "events": ["feed.generated", "interaction.recorded"],
  "secret": "your-webhook-secret"
}

Webhook Payload

{
  "event": "feed.generated",
  "timestamp": "2025-10-11T10:30:00Z",
  "data": {
    "userId": "user-123",
    "feedSize": 20,
    "latency_ms": 450
  },
  "signature": "sha256=..."
}

Verify Signature

import crypto from 'crypto';

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

Versioning

API versions are specified in the URL:

  • /v1/... - Current stable version
  • /v2/... - Next version (beta)

Version Header: 

API-Version: 2025-10-11

Deprecation

Deprecated endpoints include a warning header:

Deprecation: true
Sunset: Fri, 11 Oct 2025 23:59:59 GMT
Link: <https://docs.vows.social/migration>; rel="alternate"

SDK Libraries

JavaScript/TypeScript

npm install @vows/sdk

import { VowsClient } from '@vows/sdk';

const client = new VowsClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.vows.social'
});

const feed = await client.feed.get('user-123');

Python

pip install vows-sdk

from vows import VowsClient

client = VowsClient(api_key='your-api-key')

feed = client.feed.get(user_id='user-123')

GraphQL API (Future)

GraphQL endpoint for flexible queries:

POST /graphql

Query: 

query GetUserFeed($userId: ID!, $limit: Int!) {
  user(id: $userId) {
    feed(limit: $limit) {
      id
      vendor {
        name
        qualityScore
      }
      agentScores {
        discovery
        quality
        archivist
      }
    }
  }
}

Testing

Sandbox Environment

Use the sandbox for testing:

Base URL: https://sandbox-api.vows.social

Test Credentials: 

Email: test@vows.social
Password: testpassword123

Mock Responses

Enable mock mode with header:

X-Mock-Response: true

Support

Resources

Contact