# Varmply Backend API Varmply API – MVP backend for campaigns, wallets, authentication, and influencer participation. Version: 0.1.0 ## Servers Local development server ``` http://localhost:3000 ``` Staging environment ``` https://api-staging.varmply.com ``` Production environment ``` https://api.varmply.com ``` ## Security ### bearerAuth JWT access token obtained from /auth/register or /auth/login Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [Varmply Backend API](https://docs-staging.varmply.com/_bundle/openapi.yaml) ## Health Health check endpoints ### Health check - [GET /health](https://docs-staging.varmply.com/openapi/health/gethealthstatus.md): Returns the health status of the API service ### Readiness probe - [GET /health/ready](https://docs-staging.varmply.com/openapi/health/getreadinessstatus.md): Checks if the API service is ready to serve traffic by verifying database connectivity. Returns 200 if healthy, 503 if the database is unavailable. ## Authentication User registration and authentication ### Register a new user - [POST /auth/register](https://docs-staging.varmply.com/openapi/authentication/registeruserwithemailandpassword.md): Register a new user account with email and password. Returns JWT tokens upon successful registration. ### Login with email and password - [POST /auth/login](https://docs-staging.varmply.com/openapi/authentication/loginuserwithemailandpassword.md): Authenticate an existing user and receive JWT tokens ## Wallet Wallet balance and operations ### Get wallet balance - [GET /wallet/balance](https://docs-staging.varmply.com/openapi/wallet/getwalletbalanceforauthenticateduser.md): Retrieve the authenticated user's wallet balance for a specific currency. Returns 404 if the wallet does not exist. Requires a valid JWT access token. ### Create a new wallet - [POST /wallet](https://docs-staging.varmply.com/openapi/wallet/createwalletforauthenticateduser.md): Create a new wallet for the authenticated user in a specific currency. Returns 201 Created on success, 409 Conflict if wallet already exists. Requires a valid JWT access token. ## Dev Development-only endpoints for testing (not available in production) ### Fund wallet (dev-only) - [POST /dev/wallets/fund](https://docs-staging.varmply.com/openapi/dev/fundwalletfordev.md): Fund a wallet for the authenticated user. This endpoint is only available in non-production environments. Returns 403 if called in production. Requires a valid JWT access token. The wallet must already exist for the user and currency (no auto-create). Creates a ledger-backed transaction to record the funding. ## Campaigns Campaign creation, management, and funding ### Create a new campaign - [POST /campaigns](https://docs-staging.varmply.com/openapi/campaigns/createcampaignforauthenticateduser.md): Create a new campaign for the authenticated user. Returns 201 Created on success. Requires a valid JWT access token. ### Get campaign details - [GET /campaigns/{campaignId}](https://docs-staging.varmply.com/openapi/campaigns/getcampaignsummaryforauthenticateduser.md): Retrieve a campaign summary for the authenticated user. Only the campaign owner can access the campaign. Returns 200 OK on success, 404 if not found, 403 if not owned by user. Requires a valid JWT access token. ### Get campaign analytics summary - [GET /campaigns/{campaignId}/summary](https://docs-staging.varmply.com/openapi/campaigns/getcampaignanalyticssummary.md): Retrieve a comprehensive analytics summary for a campaign including escrow, participation, submission, and payout metrics. Returns 200 OK on success, 404 if campaign not found. Requires a valid JWT access token. ### Get campaign ledger activity feed - [GET /campaigns/{campaignId}/ledger](https://docs-staging.varmply.com/openapi/campaigns/getcampaignledgerevents.md): Retrieve campaign ledger transaction events as an activity feed, showing all financial transactions related to a campaign in chronological order (newest first). Returns 200 OK on success, 404 if campaign not found. Supports optional limit query parameter (default 50). Requires a valid JWT access token. ### Get campaign timeline analytics - [GET /campaigns/{campaignId}/timeline](https://docs-staging.varmply.com/openapi/campaigns/getcampaigntimeline.md): Retrieve time-series timeline data for a campaign with daily buckets showing cumulative payouts, escrow balance, participation counts, and approved submission counts over time. Returns 200 OK on success, 404 if campaign not found. Supports optional limitDays query parameter to limit the number of days returned. Requires a valid JWT access token. ### Fund a campaign - [POST /campaigns/{campaignId}/fund](https://docs-staging.varmply.com/openapi/campaigns/fundcampaignfromauthenticateduserwallet.md): Fund a campaign from the authenticated user's wallet. Only the campaign owner can fund their campaign. Returns 200 OK on success. Requires a valid JWT access token. ### Finalize a campaign - [POST /campaigns/{campaignId}/finalize](https://docs-staging.varmply.com/openapi/campaigns/finalizecampaign.md): Finalize a campaign if completion conditions are met. Only the campaign owner can finalize their campaign. Completion requires either: campaign endDate has passed OR escrow balance is zero. Returns 200 OK with updated campaign on success, 400 if not eligible. Requires a valid JWT access token. ## Participation Campaign participation and content submission ### Join a campaign as an influencer - [POST /campaigns/{campaignId}/participations](https://docs-staging.varmply.com/openapi/participation/joincampaignasinfluencer.md): Join a campaign as an influencer. Creates an auto-accepted participation. Requires a valid JWT access token. ### Submit content for a participation - [POST /participations/{participationId}/content-submissions](https://docs-staging.varmply.com/openapi/participation/submitparticipationcontent.md): Submit content (e.g., Instagram post, TikTok video) for a participation. Requires a valid JWT access token. Only the influencer who owns the participation can submit content. ### Approve participation content - [POST /participations/{participationId}/approve](https://docs-staging.varmply.com/openapi/participation/approveparticipationcontent.md): Approve submitted content for a participation. Only the campaign owner can approve content. Requires a valid JWT access token. ### Mark participation as completed - [POST /participations/{participationId}/complete](https://docs-staging.varmply.com/openapi/participation/markparticipationcompleted.md): Mark a participation as completed. Only the campaign owner can mark participations as completed. Requires a valid JWT access token. ## OAuth Social media OAuth connection flows ### Start Instagram OAuth connect flow - [POST /oauth/instagram/start](https://docs-staging.varmply.com/openapi/oauth/startinstagramoauth.md): 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. ### Handle Instagram OAuth callback - [GET /oauth/instagram/callback](https://docs-staging.varmply.com/openapi/oauth/handleinstagramoauthcallback.md): 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. ## Metrics Content metrics and analytics endpoints ### Refresh metrics for a participation's submitted content - [POST /metrics/participations/{participationId}/refresh](https://docs-staging.varmply.com/openapi/metrics/refreshparticipationmetrics.md): Refreshes metrics (impressions, reach, likes, comments, saves, shares) for a participation's submitted content. Fetches the latest metrics from the social media platform API and creates a snapshot. Requires the participation to have submitted content and the user to have a connected social account with valid OAuth tokens. Returns 200 OK with the created metrics snapshot on success. ### Refresh metrics for all eligible participations in a campaign - [POST /metrics/campaigns/{campaignId}/refresh](https://docs-staging.varmply.com/openapi/metrics/refreshcampaignmetrics.md): Refreshes metrics for all eligible participations in a campaign. Eligible participations are those with Instagram content submissions and status APPROVED or COMPLETED. Processes participations sequentially and returns a summary of successful and failed refreshes. Only the campaign owner can refresh metrics for their campaign. Returns 200 OK with the refresh summary on success. ### Get campaign analytics summary - [GET /analytics/campaigns/{campaignId}/summary](https://docs-staging.varmply.com/openapi/metrics/getcampaignanalyticssummary.md): Returns read-only analytics summary for a campaign, including aggregated metrics totals and participation-level breakdown. Only the campaign owner can view analytics. Returns aggregated metrics from the latest snapshot per participation. ### Get campaign payout preview - [GET /analytics/campaigns/{campaignId}/payout-preview](https://docs-staging.varmply.com/openapi/metrics/getcampaignpayoutpreview.md): Returns a read-only payout preview for a campaign showing calculated payouts per participation based on metrics and a default payout formula, compared against available escrow balance. Only the campaign owner can view payout previews. This endpoint does not execute any payouts.