openapi: 3.1.0 info: title: Harbor API description: >- The Harbor API enables programmatic access to the Harbor community platform, allowing brands to manage their superfan community, rewards programs, and engagement features. Harbor is a no-code tool that lets brands build owned community platforms where superfans can engage and earn rewards. The API provides endpoints for managing members, challenges, rewards, redemptions, leaderboards, and community events. Authentication uses bearer tokens obtained via OAuth 2.0 client credentials. version: 'v1' contact: name: Harbor Support url: https://www.harbor.gg/ termsOfService: https://www.harbor.gg/terms externalDocs: description: Harbor API Documentation url: https://api.harbor.gg/ servers: - url: https://api.harbor.gg/v1 description: Harbor API Production Server tags: - name: Challenges description: >- Operations for managing challenges that members complete to earn points and rewards. - name: Communities description: >- Operations for managing community configuration and settings. - name: Leaderboards description: >- Operations for retrieving leaderboard rankings of community members by points or other engagement metrics. - name: Members description: >- Operations for managing community members, their profiles, point balances, and tier status. - name: Redemptions description: >- Operations for managing reward redemption requests from members. - name: Rewards description: >- Operations for managing the rewards catalog that members can redeem with earned points. security: - bearerAuth: [] paths: /communities/{communityId}/members: get: operationId: listMembers summary: Harbor List community members description: >- Returns a paginated list of members belonging to the specified community. Results can be filtered by tier, status, or join date and are sorted by points balance or join date by default. tags: - Members parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/pageParam' - $ref: '#/components/parameters/limitParam' - name: tier in: query description: Filter members by loyalty tier name. schema: type: string - name: status in: query description: Filter by member status. schema: type: string enum: [active, inactive, banned] responses: '200': description: Paginated list of members. content: application/json: schema: $ref: '#/components/schemas/MemberList' '401': description: Unauthorized. Missing or invalid bearer token. '404': description: Community not found. post: operationId: createMember summary: Harbor Create a community member description: >- Registers a new member in the specified community. The member is associated with an external user identifier from the brand's platform. An optional referral code can be provided to credit the referrer. tags: - Members parameters: - $ref: '#/components/parameters/communityIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMemberRequest' responses: '201': description: Member created. content: application/json: schema: $ref: '#/components/schemas/Member' '400': description: Bad request. Invalid member data. '401': description: Unauthorized. '409': description: Member with this external ID already exists. /communities/{communityId}/members/{memberId}: get: operationId: getMember summary: Harbor Get a community member description: >- Returns the profile and engagement data for a specific member, including their point balance, tier, referral code, and challenge completion history. tags: - Members parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/memberIdParam' responses: '200': description: Member details. content: application/json: schema: $ref: '#/components/schemas/Member' '401': description: Unauthorized. '404': description: Member not found. patch: operationId: updateMember summary: Harbor Update a community member description: >- Updates profile fields or status for an existing community member. Supports partial updates — only the fields provided in the request body are modified. tags: - Members parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/memberIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMemberRequest' responses: '200': description: Updated member. content: application/json: schema: $ref: '#/components/schemas/Member' '400': description: Bad request. '401': description: Unauthorized. '404': description: Member not found. /communities/{communityId}/members/{memberId}/points: post: operationId: awardPoints summary: Harbor Award points to a member description: >- Awards a specified number of points to a community member. Used for custom point events outside of standard challenges, such as purchase rewards, anniversary bonuses, or manual adjustments. A description is required to explain the reason for the award. tags: - Members parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/memberIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AwardPointsRequest' responses: '200': description: Points awarded. Updated member balance returned. content: application/json: schema: $ref: '#/components/schemas/PointsBalance' '400': description: Bad request. '401': description: Unauthorized. '404': description: Member not found. /communities/{communityId}/challenges: get: operationId: listChallenges summary: Harbor List challenges description: >- Returns all challenges configured for the community, including their point values, completion criteria, and active status. Challenges can be one-time or repeatable and cover actions like following social accounts, making purchases, or attending events. tags: - Challenges parameters: - $ref: '#/components/parameters/communityIdParam' - name: status in: query description: Filter by challenge status. schema: type: string enum: [active, inactive, draft] responses: '200': description: List of challenges. content: application/json: schema: $ref: '#/components/schemas/ChallengeList' '401': description: Unauthorized. '404': description: Community not found. post: operationId: createChallenge summary: Harbor Create a challenge description: >- Creates a new challenge for community members to complete and earn points. Challenges can be one-time or repeatable, can have optional verification requirements, and support various completion action types. tags: - Challenges parameters: - $ref: '#/components/parameters/communityIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChallengeRequest' responses: '201': description: Challenge created. content: application/json: schema: $ref: '#/components/schemas/Challenge' '400': description: Bad request. '401': description: Unauthorized. /communities/{communityId}/challenges/{challengeId}/complete: post: operationId: completeChallenge summary: Harbor Mark a challenge as completed by a member description: >- Records that a specific member has completed the given challenge and awards the configured points to that member. If the challenge requires verification, proof must be provided. Idempotent for one-time challenges — duplicate completion requests are ignored. tags: - Challenges parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/challengeIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CompleteChallengeRequest' responses: '200': description: Challenge completion recorded. Points awarded. content: application/json: schema: $ref: '#/components/schemas/ChallengeCompletion' '400': description: Bad request or already completed. '401': description: Unauthorized. '404': description: Challenge or member not found. /communities/{communityId}/rewards: get: operationId: listRewards summary: Harbor List rewards description: >- Returns the rewards catalog for the community, including reward names, point costs, availability status, and redemption limits. Members can redeem rewards using their earned points. tags: - Rewards parameters: - $ref: '#/components/parameters/communityIdParam' - name: status in: query description: Filter by reward availability status. schema: type: string enum: [active, inactive, sold_out] responses: '200': description: List of available rewards. content: application/json: schema: $ref: '#/components/schemas/RewardList' '401': description: Unauthorized. '404': description: Community not found. /communities/{communityId}/redemptions: get: operationId: listRedemptions summary: Harbor List redemptions description: >- Returns a paginated list of reward redemption requests from community members. Can be filtered by status (pending, approved, fulfilled, rejected) for fulfillment workflow management. tags: - Redemptions parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/pageParam' - $ref: '#/components/parameters/limitParam' - name: status in: query description: Filter by redemption status. schema: type: string enum: [pending, approved, fulfilled, rejected] responses: '200': description: List of redemptions. content: application/json: schema: $ref: '#/components/schemas/RedemptionList' '401': description: Unauthorized. post: operationId: createRedemption summary: Harbor Create a redemption request description: >- Submits a redemption request on behalf of a member for a specific reward from the catalog. Deducts the reward's point cost from the member's balance if they have sufficient points. tags: - Redemptions parameters: - $ref: '#/components/parameters/communityIdParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRedemptionRequest' responses: '201': description: Redemption created. content: application/json: schema: $ref: '#/components/schemas/Redemption' '400': description: Insufficient points or reward unavailable. '401': description: Unauthorized. /communities/{communityId}/leaderboard: get: operationId: getLeaderboard summary: Harbor Get community leaderboard description: >- Returns the ranked leaderboard of community members sorted by total points earned. Supports optional time-window filtering for weekly or monthly leaderboards. tags: - Leaderboards parameters: - $ref: '#/components/parameters/communityIdParam' - $ref: '#/components/parameters/limitParam' - name: period in: query description: Time period for leaderboard calculation. schema: type: string enum: [all_time, monthly, weekly] default: all_time responses: '200': description: Leaderboard rankings. content: application/json: schema: $ref: '#/components/schemas/Leaderboard' '401': description: Unauthorized. '404': description: Community not found. /communities/{communityId}: get: operationId: getCommunity summary: Harbor Get community details description: >- Returns configuration and metadata for the specified community, including name, branding settings, tier structure, and active feature flags. tags: - Communities parameters: - $ref: '#/components/parameters/communityIdParam' responses: '200': description: Community details. content: application/json: schema: $ref: '#/components/schemas/Community' '401': description: Unauthorized. '404': description: Community not found. components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token obtained via OAuth 2.0 client credentials flow. Contact Harbor to obtain API credentials. parameters: communityIdParam: name: communityId in: path required: true description: The unique identifier of the Harbor community. schema: type: string memberIdParam: name: memberId in: path required: true description: The unique identifier of the community member. schema: type: string challengeIdParam: name: challengeId in: path required: true description: The unique identifier of the challenge. schema: type: string pageParam: name: page in: query description: Page number for pagination (1-based). schema: type: integer minimum: 1 default: 1 limitParam: name: limit in: query description: Number of results per page. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: Member: type: object description: A community member representing a superfan registered on the Harbor platform. properties: id: type: string description: Unique Harbor member identifier. externalId: type: string description: >- The brand's external user identifier used to link the Harbor member to the brand's own user account. communityId: type: string description: Identifier of the community this member belongs to. displayName: type: string description: Member's display name shown in the community. email: type: string format: email description: Member's email address. pointsBalance: type: integer description: Current point balance available for redemption. minimum: 0 totalPointsEarned: type: integer description: Total lifetime points earned by the member. minimum: 0 tier: $ref: '#/components/schemas/Tier' referralCode: type: string description: Unique referral code this member can share to earn referral rewards. status: type: string description: Current membership status. enum: [active, inactive, banned] joinedAt: type: string format: date-time description: Timestamp when the member joined the community. lastActiveAt: type: string format: date-time description: Timestamp of the member's last activity. MemberList: type: object description: Paginated list of community members. properties: data: type: array description: Array of member objects. items: $ref: '#/components/schemas/Member' total: type: integer description: Total number of members matching the query. page: type: integer description: Current page number. limit: type: integer description: Results per page. CreateMemberRequest: type: object description: Request body for registering a new community member. required: [externalId] properties: externalId: type: string description: The brand's unique identifier for this user. displayName: type: string description: Member's display name. maxLength: 100 email: type: string format: email description: Member's email address. referralCode: type: string description: Referral code provided by an existing member. metadata: type: object description: Optional additional metadata to store with the member. additionalProperties: true UpdateMemberRequest: type: object description: Request body for updating a community member's profile. properties: displayName: type: string description: Updated display name. maxLength: 100 email: type: string format: email description: Updated email address. status: type: string description: Updated membership status. enum: [active, inactive, banned] metadata: type: object description: Updated metadata key-value pairs. additionalProperties: true AwardPointsRequest: type: object description: Request body for awarding points to a community member. required: [points, description] properties: points: type: integer description: Number of points to award. Must be a positive integer. minimum: 1 description: type: string description: Human-readable reason for the point award. maxLength: 500 metadata: type: object description: Optional metadata about this point transaction. additionalProperties: true PointsBalance: type: object description: Updated points balance after a transaction. properties: memberId: type: string description: Member identifier. pointsAwarded: type: integer description: Points awarded in this transaction. newBalance: type: integer description: Member's new point balance after the award. totalPointsEarned: type: integer description: Updated lifetime points total. Tier: type: object description: Loyalty tier a member has achieved. properties: id: type: string description: Tier identifier. name: type: string description: Tier display name (e.g., Bronze, Silver, Gold). pointsRequired: type: integer description: Minimum lifetime points required to reach this tier. benefits: type: array description: List of benefits associated with this tier. items: type: string Challenge: type: object description: >- A challenge that community members can complete to earn points and rewards. properties: id: type: string description: Unique challenge identifier. communityId: type: string description: Community this challenge belongs to. title: type: string description: Challenge display title. description: type: string description: Detailed description of what members must do to complete the challenge. points: type: integer description: Points awarded upon successful completion. minimum: 0 actionType: type: string description: Type of action required to complete the challenge. enum: - social_follow - social_share - purchase - referral - event_attendance - content_submission - custom repeatable: type: boolean description: Whether members can complete this challenge multiple times. maxCompletions: type: integer description: Maximum number of times a member can complete this challenge. Null for unlimited. status: type: string description: Current challenge status. enum: [active, inactive, draft] startsAt: type: string format: date-time description: When the challenge becomes available. endsAt: type: string format: date-time description: When the challenge expires. Null for no expiry. ChallengeList: type: object description: List of community challenges. properties: data: type: array description: Array of challenge objects. items: $ref: '#/components/schemas/Challenge' total: type: integer description: Total number of challenges. CreateChallengeRequest: type: object description: Request body for creating a new community challenge. required: [title, points, actionType] properties: title: type: string description: Challenge title shown to members. maxLength: 200 description: type: string description: Detailed challenge description. maxLength: 2000 points: type: integer description: Points to award upon completion. minimum: 1 actionType: type: string description: Type of action required. enum: - social_follow - social_share - purchase - referral - event_attendance - content_submission - custom repeatable: type: boolean description: Whether the challenge can be completed multiple times. default: false startsAt: type: string format: date-time description: Challenge start time. endsAt: type: string format: date-time description: Challenge end time. CompleteChallengeRequest: type: object description: Request body for recording a challenge completion. required: [memberId] properties: memberId: type: string description: Identifier of the member who completed the challenge. proof: type: object description: Verification proof for challenges that require it. additionalProperties: true metadata: type: object description: Optional metadata about the completion. additionalProperties: true ChallengeCompletion: type: object description: Result of a challenge completion recording. properties: challengeId: type: string description: Challenge that was completed. memberId: type: string description: Member who completed the challenge. pointsAwarded: type: integer description: Points awarded for this completion. newBalance: type: integer description: Member's updated point balance. completedAt: type: string format: date-time description: Timestamp of completion. Reward: type: object description: A reward available for redemption in the community catalog. properties: id: type: string description: Unique reward identifier. communityId: type: string description: Community this reward belongs to. title: type: string description: Reward display title. description: type: string description: Detailed reward description. pointCost: type: integer description: Number of points required to redeem this reward. minimum: 1 type: type: string description: Reward type. enum: - discount_code - physical_item - digital_download - experience - custom status: type: string description: Availability status. enum: [active, inactive, sold_out] quantity: type: integer description: Total quantity available. Null for unlimited. remainingQuantity: type: integer description: Current remaining quantity. imageUrl: type: string format: uri description: URL of the reward image. RewardList: type: object description: List of community rewards. properties: data: type: array description: Array of reward objects. items: $ref: '#/components/schemas/Reward' total: type: integer description: Total number of rewards. Redemption: type: object description: A reward redemption request from a community member. properties: id: type: string description: Unique redemption identifier. communityId: type: string description: Community this redemption belongs to. memberId: type: string description: Member who requested the redemption. rewardId: type: string description: Reward being redeemed. reward: $ref: '#/components/schemas/Reward' pointsSpent: type: integer description: Points deducted for this redemption. status: type: string description: Current redemption status. enum: [pending, approved, fulfilled, rejected] fulfillmentData: type: object description: Fulfillment data such as discount codes or shipping information. additionalProperties: true createdAt: type: string format: date-time description: When the redemption was requested. updatedAt: type: string format: date-time description: When the redemption was last updated. RedemptionList: type: object description: Paginated list of redemptions. properties: data: type: array description: Array of redemption objects. items: $ref: '#/components/schemas/Redemption' total: type: integer description: Total number of redemptions. page: type: integer description: Current page number. limit: type: integer description: Results per page. CreateRedemptionRequest: type: object description: Request body for creating a reward redemption. required: [memberId, rewardId] properties: memberId: type: string description: Identifier of the member redeeming the reward. rewardId: type: string description: Identifier of the reward to redeem. shippingAddress: type: object description: Shipping address for physical reward redemptions. properties: name: type: string description: Recipient name. line1: type: string description: Address line 1. line2: type: string description: Address line 2. city: type: string description: City. state: type: string description: State or province. postalCode: type: string description: Postal code. country: type: string description: ISO 3166-1 alpha-2 country code. pattern: '^[A-Z]{2}$' LeaderboardEntry: type: object description: A single entry in the community leaderboard. properties: rank: type: integer description: Member's current rank position on the leaderboard. minimum: 1 memberId: type: string description: Member identifier. displayName: type: string description: Member's display name. points: type: integer description: Points total used for ranking. minimum: 0 tier: $ref: '#/components/schemas/Tier' Leaderboard: type: object description: Community leaderboard with ranked member entries. properties: communityId: type: string description: Community identifier. period: type: string description: Time period this leaderboard covers. enum: [all_time, monthly, weekly] entries: type: array description: Ranked list of member entries. items: $ref: '#/components/schemas/LeaderboardEntry' generatedAt: type: string format: date-time description: Timestamp when the leaderboard was last calculated. Community: type: object description: A Harbor community platform configuration. properties: id: type: string description: Unique community identifier. name: type: string description: Community display name. slug: type: string description: URL-friendly community slug. description: type: string description: Community description shown to members. logoUrl: type: string format: uri description: URL of the community logo image. primaryColor: type: string description: Brand primary color in hexadecimal format. pattern: '^#[0-9A-Fa-f]{6}$' tiers: type: array description: Loyalty tier structure configured for this community. items: $ref: '#/components/schemas/Tier' memberCount: type: integer description: Total number of registered members. minimum: 0 createdAt: type: string format: date-time description: When the community was created.