Check Verb Access
POST
/api/openverb/checkDescription
Check if a user has access to perform a specific verb action.
Request Body
{
"verbId": "export_data",
"actor": { "type": "user", "id": "user_123" },
"context": { "tenantId": "app_456", "planId": "pro" }
}Response (allowed)
{
"ok": true,
"receipt": {
"executionId": "...",
"verbId": "export_data",
"status": "ok",
"actorId": "user_123",
"tenantId": "app_456"
}
}Response (denied)
{
"denied": true,
"reason": {
"code": "tier_required",
"message": "Upgrade to Pro"
},
"upsell": {
"suggestedPlanId": "pro",
"cta": "Upgrade Now"
}
}Get Verb Library
GET
/api/openverb/libraryDescription
Retrieve the complete OpenVerb library for your app.
Query Parameters
?appId=app_456
Response
{
"namespace": "myapp.core",
"version": "1.0.0",
"verbs": [
{
"id": "verb_789",
"name": "export_data",
"category": "file_system",
"description": "Export user data to CSV"
}
]
}Get User Entitlements
GET
/api/openverb/entitlementsDescription
Get all verbs a user is entitled to access based on their tier.
Query Parameters
?userId=user_123&appId=app_456
Response
{
"userId": "user_123",
"tier": "pro",
"entitlements": [
{
"verbId": "export_data",
"verbName": "export_data",
"usageLimit": {
"limit": 100,
"used": 45,
"period": "monthly"
}
}
]
}Authentication
All API requests require authentication using your API key in the Authorization header:
Authorization: Bearer pk_live_...
Rate Limits
Free tier:1,000 requests/month
Pro tier:100,000 requests/month
Enterprise tier:Unlimited
Client SDK
Copy lib/paywall-sdk.ts from the PaywallOS repo. It provides initPaywallOS and usePaywallOS:
import { initPaywallOS, usePaywallOS } from '@/lib/paywall-sdk'
// One-time init (scans DOM for verb= attributes)
initPaywallOS(apiKey, appId, userId, userTier)
// Or use the hook for programmatic checks
const { checkVerb } = usePaywallOS(apiKey, appId, userId, userTier)
const response = await checkVerb('export_data')
if (response.ok) { /* allowed */ }
else if (response.denied) { /* response.reason?.message */ }