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

Get TikTok connection status

Request

Returns the current TikTok connection status and capabilities for the authenticated user. Returns 404 if no connection exists. The response includes verification status, available capabilities, and any error codes.

Security
bearerAuth
curl -i -X GET \
  https://docs-staging.varmply.com/_mock/openapi/me/tiktok-connection \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

TikTok connection status retrieved successfully

Bodyapplication/json
tiktok_open_idstring or nullrequired

TikTok open ID for the connected account

Example: "open_id_12345"
statusstringrequired

Current verification status of the TikTok connection:

  • PENDING: Connection created but not yet verified
  • VALID: Connection verified with full capabilities
  • LIMITED: Connection verified but with limited capabilities
  • ERROR: Connection verification failed
Enum"PENDING""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 current status

Example: "VERIFICATION_OK"
reason_messagestring or nullrequired

Human-readable reason message

Example: "Connection verified successfully"
last_verified_atstring or null(date-time)required

ISO 8601 timestamp of the last verification attempt

Example: "2024-01-01T12:00:00Z"
last_error_codestring or nullrequired

Error code from the last verification attempt (if any)

Example: null
last_error_messagestring or nullrequired

Error message from the last verification attempt (if any)

Example: null
created_atstring(date-time)required

ISO 8601 timestamp when the connection was created

Example: "2024-01-01T10:00:00Z"
updated_atstring(date-time)required

ISO 8601 timestamp when the connection was last updated

Example: "2024-01-01T12:00:00Z"
Response
application/json
{
  "tiktok_open_id": "open_id_12345",
  "status": "VALID",
  "capabilities": {
    "can_read_profile": true,
    "can_list_videos": true,
    "can_read_video_metrics": true
  },
  "reason_code": "VERIFICATION_OK",
  "reason_message": "Connection verified successfully",
  "last_verified_at": "2024-01-01T12:00:00Z",
  "last_error_code": null,
  "last_error_message": null,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Get Instagram connection status

Request

Returns the current Instagram connection status and capabilities for the authenticated user. Returns null if no connection exists. The response includes verification status, available capabilities (profile, media, insights, comments access), and any error codes.

Security
bearerAuth
curl -i -X GET \
  https://docs-staging.varmply.com/_mock/openapi/me/instagram-connection \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Instagram connection status retrieved successfully (or null if no connection)

Bodyapplication/json
One of:
statusstringrequired

Current verification status of the Instagram connection:

  • PENDING: Connection created but not yet verified
  • VALID: Connection verified with full capabilities
  • LIMITED: Connection verified but with limited capabilities
  • ERROR: Connection verification failed
Enum"PENDING""VALID""LIMITED""ERROR"
Example: "VALID"
capabilitiesobjectrequired
capabilities.​canReadProfilebooleanrequired

Whether the connection can read Instagram profile data

Example: true
capabilities.​canReadMediabooleanrequired

Whether the connection can read Instagram media posts

Example: true
capabilities.​canReadInsightsbooleanrequired

Whether the connection can read Instagram insights/analytics

Example: true
capabilities.​canReadCommentsbooleanrequired

Whether the connection can read Instagram comments

Example: true
pageIdstring or nullrequired

Facebook Page ID associated with the Instagram account

Example: "123456789"
instagramBusinessIdstring or nullrequired

Instagram Business/Creator account ID

Example: "987654321"
lastVerifiedAtstring or null(date-time)required

ISO 8601 timestamp of the last verification attempt

Example: "2024-01-01T12:00:00Z"
lastErrorCodestring or nullrequired

Error code from the last verification attempt (if any):

  • ME_CALL_FAILED: Failed to verify token with /me endpoint
  • NO_IG_BUSINESS_ACCOUNT: No Instagram Business Account linked
  • PROFILE_ACCESS_FAILED: Cannot access Instagram profile
  • MEDIA_ACCESS_FAILED: Cannot access Instagram media
  • INSIGHTS_ACCESS_FAILED: Cannot access Instagram insights
  • COMMENTS_ACCESS_FAILED: Cannot access Instagram comments
  • NO_CAPABILITIES: No capabilities available
  • UNKNOWN_ERROR: An unexpected error occurred
Enum"ME_CALL_FAILED""NO_IG_BUSINESS_ACCOUNT""PROFILE_ACCESS_FAILED""MEDIA_ACCESS_FAILED""INSIGHTS_ACCESS_FAILED""COMMENTS_ACCESS_FAILED""NO_CAPABILITIES""UNKNOWN_ERROR"null
Example: null
Response
application/json
{
  "status": "VALID",
  "capabilities": {
    "canReadProfile": true,
    "canReadMedia": true,
    "canReadInsights": true,
    "canReadComments": true
  },
  "pageId": "123456789",
  "instagramBusinessId": "987654321",
  "lastVerifiedAt": "2024-01-01T12:00:00Z",
  "lastErrorCode": null
}

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

Dev

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

Operations