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 four ways (only one should be specified per request):
anonymousIdentifier: For anonymous/unauthenticated userscreateAnonymousIdentifier: For generating a new anonymous identifieruserJwt: 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.
Authorization
ApiKeyAuth API key authentication. Use secret keys (sk_*) for full access or public keys (pk_*) for limited access.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request payload for surface decisions.
User Identity: If provided, one of the following must be provided:
userIdentifier: Direct user ID (requires secret key)userJwt: JWT token for authenticated usersanonymousIdentifier: Anonymous session identifier
If not provided, user identity must be resolved by middleware.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.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"}