Perform Surface Decision
Performs the same actions as an access check and runs surface workflows.
The response includes:
- The same information as an access check
- The results of running a surface workflow and it's component workflows, if applicable
User Identity
You can identify users in three ways (only one should be specified per request):
anonymousIdentifier: For anonymous/unauthenticated usersuserJwt: JWT token for authenticated usersuserIdentifier: Direct user ID (requires secret key)
User Agents
When running decisions from a server-side context with a secret key, the original client user agent
can be specified for use in decisions by setting the x-mos-user-agent header.
API key authentication. Use secret keys (sk_*) for full access or public keys (pk_*) for limited access.
In: header
Properties used to identify the user or session that the request is associated with
Request with direct user identifier
Authenticated user identifier. Can only be used with an organization's secret keys. Use this when you have a direct user ID from your system.
Request with JWT token
JWT token for user authentication. The JWT must be valid according to your configured JWT integrations.
Request with anonymous identifier
Identifier for anonymous/unauthenticated users. Use this for guest sessions or before user login.
Information about the resource being accessed. This helps determine which features and meter limits apply to the request.
Request information specific to requests made from Cloudflare Workers. (requires secret key)
Response Body
curl -X POST "https://api.monetizationos.com/api/v1/surface-decisions" \ -H "Content-Type: application/json" \ -d '{ "identity": { "anonymousIdentifier": "anon_session_789" }, "resource": { "id": "article_xyz" } }'{
"status": "success",
"eventId": "c918c19e-b782-4c2f-93c0-8a5f94c0a1b5",
"identity": {
"authType": "provided",
"isAuthenticated": true,
"identifier": "user_12345"
},
"customer": {
"isCustomer": true,
"hasProducts": true,
"customerIdentifiers": [
"user_12345",
"stripe_cus_abc123"
]
},
"features": {
"article": {
"featureId": "feat_123456",
"featureSlug": "article",
"properties": {
"enabled": {
"type": "meterable",
"counterId": "default:feat_123456.enabled",
"hasAccess": true,
"consumedUnits": 3,
"remainingUnits": 2,
"totalUnits": 5,
"periodStart": "2025-07-01T00:00:00Z",
"uniqueResources": false,
"resourceIdUsed": false,
"consumedInRequest": true,
"isFallback": false
},
"ads": {
"type": "boolean",
"value": false,
"isFallback": true
}
}
}
}
}{
"status": "error",
"statusCode": 400,
"message": "Invalid JSON body"
}{
"status": "error",
"statusCode": 401,
"message": "Invalid API key"
}{
"status": "error",
"statusCode": 404,
"message": "Organization not found"
}{
"status": "error",
"statusCode": 500,
"message": "Internal server error"
}