Skip to content

Varmply Backend API (0.1.0)

Varmply API – MVP backend for campaigns, wallets, authentication, and influencer participation.

Error Messages

Common error codes: - NOT_FOUND - Resource not found (404) - VALIDATION_ERROR - Input validation failed (400) - PERMISSION_DENIED - User lacks permission (403) - CONFLICT - Resource conflict (409) - UNAUTHORIZED - Authentication required (401) - INTERNAL_SERVER_ERROR - Unexpected server error (500)

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://docs-staging.varmply.com/_mock/openapi/
Local development server
http://localhost:3000/
Staging environment
https://api-staging.varmply.com/
Production environment
https://api.varmply.com/

Health

Health check endpoints

Operations

Authentication

User registration, authentication, and email verification

Operations

Onboarding

User onboarding flow for all user types, including role assignment, profile setup (creator and sponsor), and settings configuration

Operations

Connections

Social media platform connection status and management

Operations

OAuth

Social media OAuth connection flows

Operations

Wallet

Wallet balance and operations

Operations

Campaigns

Campaign creation, management, and funding

Operations

Marketplace

Public marketplace for discovering and joining campaigns

Operations

Participation

Campaign participation and content submission (creator-focused)

Operations

Analytics

Analytics and reporting endpoints for campaigns, participations, and submissions

Operations

Metrics

Metrics ingestion and refresh endpoints for participations and campaigns

Operations

Notifications

User notification management endpoints

Operations

Get user notifications

Request

Returns a paginated list of notifications for the authenticated user. Notifications are returned in descending order by creation timestamp (most recent first). Supports cursor-based pagination via the cursor query parameter.

Security
bearerAuth
Query
limitinteger[ 1 .. 100 ]

Maximum number of notifications to return (default: 50, max: 100)

Default 50
Example: limit=50
cursorstring(date-time)

ISO timestamp cursor for pagination (exclusive, returns notifications created before this timestamp)

Example: cursor=2024-01-01T12:00:00Z
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/me/notifications?limit=50&cursor=2024-01-01T12%3A00%3A00Z' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Notifications retrieved successfully

Bodyapplication/json
notificationsArray of objects(NotificationResponse)required

List of notifications (most recent first)

notifications[].​idstringrequired

Unique identifier for the notification

Example: "notification_123"
notifications[].​titlestringrequired

Notification title

Example: "Earnings Blocked"
notifications[].​bodystringrequired

Notification body message

Example: "Your earnings of $10.00 for submission submission_abc were blocked due to insufficient campaign escrow."
notifications[].​severitystringrequired

Notification severity level:

  • NOTIFICATION_SEVERITY_INFO: Informational notification
  • NOTIFICATION_SEVERITY_WARNING: Warning notification requiring attention
  • NOTIFICATION_SEVERITY_ERROR: Error notification indicating a problem
Enum"NOTIFICATION_SEVERITY_INFO""NOTIFICATION_SEVERITY_WARNING""NOTIFICATION_SEVERITY_ERROR"
Example: "NOTIFICATION_SEVERITY_WARNING"
notifications[].​reason_codestring or nullrequired

Machine-readable reason code for the notification (e.g., INSUFFICIENT_ESCROW)

Example: "INSUFFICIENT_ESCROW"
notifications[].​entity_refobject or nullrequired

Reference to the entity that triggered this notification

Example: {"type":"ACCURUAL","id":"accrual_xyz"}
notifications[].​entity_ref.​typestring

Type of entity referenced

Enum"CAMPAIGN""ACCURUAL""PARTICIPATION""SOCIAL_ACCOUNT"
Example: "ACCURUAL"
notifications[].​entity_ref.​idstring

Unique identifier of the referenced entity

Example: "accrual_xyz"
notifications[].​is_readbooleanrequired

Whether the notification has been read by the user

Example: false
notifications[].​read_atstring or null(date-time)required

ISO timestamp when the notification was marked as read (null if unread)

Example: null
notifications[].​created_atstring(date-time)required

ISO timestamp when the notification was created

Example: "2024-01-01T12:00:00Z"
next_cursorstring or null(date-time)required

ISO timestamp cursor for pagination. Use this value as the cursor query parameter in the next request to fetch older notifications. Null if there are no more notifications.

Response
application/json
{
  "notifications": [
    { … }
  ],
  "next_cursor": "2024-01-01T11:00:00Z"
}

Mark notification as read

Request

Marks a specific notification as read for the authenticated user. Returns the updated notification. If the notification is already read or doesn't exist, returns 404.

Security
bearerAuth
Path
idstringrequired

Notification identifier

Example: notification_123
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/me/notifications/notification_123/read \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Notification marked as read successfully

Bodyapplication/json
idstringrequired

Unique identifier for the notification

Example: "notification_123"
titlestringrequired

Notification title

Example: "Earnings Blocked"
bodystringrequired

Notification body message

Example: "Your earnings of $10.00 for submission submission_abc were blocked due to insufficient campaign escrow."
severitystringrequired

Notification severity level:

  • NOTIFICATION_SEVERITY_INFO: Informational notification
  • NOTIFICATION_SEVERITY_WARNING: Warning notification requiring attention
  • NOTIFICATION_SEVERITY_ERROR: Error notification indicating a problem
Enum"NOTIFICATION_SEVERITY_INFO""NOTIFICATION_SEVERITY_WARNING""NOTIFICATION_SEVERITY_ERROR"
Example: "NOTIFICATION_SEVERITY_WARNING"
reason_codestring or nullrequired

Machine-readable reason code for the notification (e.g., INSUFFICIENT_ESCROW)

Example: "INSUFFICIENT_ESCROW"
entity_refobject or nullrequired

Reference to the entity that triggered this notification

Example: {"type":"ACCURUAL","id":"accrual_xyz"}
entity_ref.​typestring

Type of entity referenced

Enum"CAMPAIGN""ACCURUAL""PARTICIPATION""SOCIAL_ACCOUNT"
Example: "ACCURUAL"
entity_ref.​idstring

Unique identifier of the referenced entity

Example: "accrual_xyz"
is_readbooleanrequired

Whether the notification has been read by the user

Example: false
read_atstring or null(date-time)required

ISO timestamp when the notification was marked as read (null if unread)

Example: null
created_atstring(date-time)required

ISO timestamp when the notification was created

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "id": "notification_123",
  "title": "Earnings Blocked",
  "body": "Your earnings of $10.00 for submission submission_abc were blocked due to insufficient campaign escrow.",
  "severity": "NOTIFICATION_SEVERITY_WARNING",
  "reason_code": "INSUFFICIENT_ESCROW",
  "entity_ref": {
    "type": "ACCURUAL",
    "id": "accrual_xyz"
  },
  "is_read": true,
  "read_at": "2024-01-01T12:05:00Z",
  "created_at": "2024-01-01T12:00:00Z"
}

Mark all notifications as read

Request

Marks all unread notifications as read for the authenticated user. Returns the count of notifications that were marked as read.

Security
bearerAuth
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/me/notifications/read-all \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

All notifications marked as read successfully

Bodyapplication/json
successbooleanrequired
Example: true
Response
application/json
{
  "success": true
}

Dev

Development-only endpoints for testing (not available in production)

Operations