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

Start Instagram OAuth connect flow

Request

Initiates the Instagram OAuth connect flow for an authenticated user. Returns an authorization URL that the client should redirect the user to. The user will authorize the app on Instagram and be redirected back to the callback endpoint.

Security
bearerAuth
Bodyapplication/jsonrequired
redirectPathstring^/required

Relative path (e.g., "/dashboard") where the user should be redirected after OAuth completion

Example: "/dashboard"
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/oauth/instagram/start \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectPath": "/dashboard"
  }'

Responses

Authorization URL generated successfully

Bodyapplication/json
authorizationUrlstring(uri)required

URL to redirect the user to for Instagram authorization

Example: "https://api.instagram.com/oauth/authorize?client_id=xxx&redirect_uri=xxx&scope=xxx&response_type=code&state=xxx"
Response
application/json
{
  "authorizationUrl": "https://api.instagram.com/oauth/authorize?client_id=xxx&redirect_uri=xxx&scope=xxx&response_type=code&state=xxx"
}

Handle Instagram OAuth callback

Request

Handles the OAuth callback from Instagram after user authorization. Exchanges the authorization code for access tokens, fetches user profile, and creates/updates the social account. Redirects to the redirect URI specified in the original request with a status query parameter.

Query
codestringrequired

Authorization code returned by Instagram

Example: code=AQBx...
statestringrequired

State token for CSRF protection and context

Example: state=eyJhbGc...
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/oauth/instagram/callback?code=AQBx...&state=eyJhbGc...'

Responses

Redirect to the redirect URI with status query parameter

Headers
Locationstring(uri)

Redirect URI with status=success or status=error

Example: "https://app.example.com/dashboard?status=success"
Response
No content

Start TikTok OAuth connect flow

Request

Initiates the TikTok OAuth connect flow for an authenticated user. Returns an authorization URL that the client should redirect the user to. The user will authorize the app on TikTok and be redirected back to the callback endpoint. Requests the following TikTok scopes: user.info.basic, video.list

Security
bearerAuth
Bodyapplication/jsonrequired
redirectUristring(uri)required

Full URL where the user should be redirected after OAuth completion

Example: "https://app.varmply.com/integrations/callback"
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/oauth/tiktok/start \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectUri": "https://app.varmply.com/integrations/callback"
  }'

Responses

Authorization URL generated successfully

Bodyapplication/json
authorization_urlstring(uri)required

URL to redirect the user to for TikTok authorization

Example: "https://www.tiktok.com/v2/auth/authorize/?client_key=xxx&redirect_uri=xxx&scope=user.info.basic,video.list&response_type=code&state=xxx"
expires_at_timestampstring(date-time)required

ISO timestamp when the authorization URL expires

Example: "2024-01-01T00:10:00Z"
Response
application/json
{
  "authorization_url": "https://www.tiktok.com/v2/auth/authorize/?client_key=xxx&redirect_uri=xxx&scope=user.info.basic,video.list&response_type=code&state=xxx",
  "expires_at_timestamp": "2024-01-01T00:10:00Z"
}

Handle TikTok OAuth callback

Request

Handles the OAuth callback from TikTok after user authorization. Exchanges the authorization code for access tokens, fetches user profile, and creates/updates the social account. Redirects to the redirect URI specified in the original request with platform=tiktok and status=connected query parameters.

Query
codestring

Authorization code returned by TikTok (required if no error)

Example: code=act.xxx...
statestring

State token for CSRF protection and context (required if no error)

Example: state=eyJhbGc...
errorstring

Error code returned by TikTok if authorization was denied

Example: error=access_denied
error_descriptionstring

Human-readable error description

Example: error_description=User denied access
curl -i -X GET \
  'https://docs-staging.varmply.com/_mock/openapi/oauth/tiktok/callback?code=act.xxx...&state=eyJhbGc...&error=access_denied&error_description=User+denied+access'

Responses

Redirect to the redirect URI with platform and status query parameters

Headers
Locationstring(uri)

Redirect URI with platform=tiktok&status=connected

Example: "https://app.varmply.com/integrations/callback?platform=tiktok&status=connected"
Response
No content

Verify TikTok connection

Request

Triggers verification of the current user's TikTok connection. This endpoint is primarily for dev/admin use to manually verify connections. It tests the TikTok API access and updates the connection's capability status.

Verification steps:

  1. Fetch profile - verifies token validity
  2. List videos - verifies video.list scope
  3. Get video metrics - verifies metrics access
Security
bearerAuth
curl -i -X POST \
  https://docs-staging.varmply.com/_mock/openapi/oauth/tiktok/verify \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Verification completed successfully

Bodyapplication/json
statusstringrequired

Result of verification:

  • VALID: All capabilities verified successfully
  • LIMITED: Some capabilities available but not all
  • ERROR: Verification failed
Enum"VALID""LIMITED""ERROR"
Example: "VALID"
capabilitiesobject(TikTokConnectionCapabilities)required
capabilities.​can_read_profilebooleanrequired

Whether the connection can read TikTok profile data

Example: true
capabilities.​can_list_videosbooleanrequired

Whether the connection can list TikTok videos

Example: true
capabilities.​can_read_video_metricsbooleanrequired

Whether the connection can read TikTok video metrics

Example: true
reason_codestring or nullrequired

Machine-readable reason code for the verification result

Enum"VERIFICATION_OK""TOKEN_INVALID_OR_EXPIRED""TOKEN_REVOKED""MISSING_PROFILE_SCOPE""MISSING_VIDEO_LIST_SCOPE""MISSING_VIDEO_METRICS_SCOPE""ACCOUNT_NOT_ELIGIBLE_FOR_METRICS""TEMPORARY_API_FAILURE""CONNECTION_NOT_FOUND""UNKNOWN_ERROR"
Example: null
reason_messagestring or nullrequired

Human-readable reason message

Example: null
last_verified_atstring(date-time)required

ISO 8601 timestamp of when verification was completed

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "status": "VALID",
  "capabilities": {
    "can_read_profile": true,
    "can_list_videos": true,
    "can_read_video_metrics": true
  },
  "reason_code": null,
  "reason_message": null,
  "last_verified_at": "2024-01-01T12:00:00Z"
}

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

Dev

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

Operations