Skip to main content

​
Base URL

https://api.velatir.com/v1

​
Authentication

All API requests require an API key in the Authorization header: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.velatir.com/v1/review-tasks

​
Core Endpoints

​
Create Review Task

POST /review-tasks Submit an AI request for approval. 
{
  "functionName": "send_marketing_email",
  "args": {
    "recipient": "customer@example.com",
    "template": "monthly_newsletter",
    "personalization": true
  },
  "description": "Send personalized monthly newsletter",
  "llmExplanation": "Using customer preferences to customize content",
  "metadata": {
    "user_id": "123",
    "session_id": "abc-def"
  }
}
Response: 
{
  "id": "task_12345",
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Get Review Task Status

GET /review-tasks/{taskId} Check the current status of a review task. Response: 
{
  "id": "task_12345",
  "status": "approved",
  "functionName": "send_marketing_email",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "assessments": [
    {
      "policyId": "gdpr_policy",
      "compliant": true,
      "riskLevel": "medium",
      "confidence": 0.95,
      "reason": "Processing personal data for marketing with consent",
      "tags": ["#PersonalData", "#Marketing"]
    }
  ],
  "decisions": [
    {
      "type": "approved",
      "reason": "Consent verified, legitimate marketing purpose",
      "reviewer": "marketing_team",
      "timestamp": "2024-01-15T10:35:00Z"
    }
  ]
}

​
List Review Tasks

GET /review-tasks Retrieve tasks with optional filtering. Query Parameters:
  • status - Filter by task status
  • limit - Number of tasks to return (max 100)
  • offset - Pagination offset
  • from - Start date filter
  • to - End date filter

​
Status Values

  • pending - Just created, not processed yet
  • processing - Being evaluated against policies
  • approved - Automatically or manually approved
  • requires_intervention - Waiting for human review
  • rejected - Human reviewer declined request
  • change_requested - Modifications needed

​
Webhooks

​
Setup

POST /webhooks 
{
  "url": "https://your-app.com/velatir-webhook",
  "events": ["task.completed", "task.requires_intervention"]
}

​
Event Types

  • task.created - New review task submitted
  • task.requires_intervention - Human approval needed
  • task.completed - Final decision made
  • task.timeout - Review timeout reached

​
Webhook Payload

{
  "event": "task.completed",
  "taskId": "task_12345", 
  "status": "approved",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "functionName": "send_marketing_email",
    "decision": {
      "type": "approved",
      "reason": "Consent verified"
    }
  }
}

​
Error Handling

​
Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: functionName",
    "details": {
      "field": "functionName",
      "provided": null
    }
  }
}

​
Common Error Codes

  • AUTHENTICATION_FAILED - Invalid or missing API key
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INVALID_REQUEST - Malformed request data
  • TASK_NOT_FOUND - Review task doesn’t exist
  • POLICY_ERROR - Policy evaluation failed

​
Rate Limits

  • Standard Plan: 1000 requests per hour
  • Business Plan: 10,000 requests per hour
  • Enterprise Plan: Custom limits

​
SDKs

TypeScript/JavaScript

npm install @velatir/sdk

Python

pip install velatir-python

n8n Integration

Use Velatir in workflow automation

MCP Server

Integrate with AI agents