openapi: 3.1.0
info:
  title: Harbor Challenges Members 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
servers:
- url: https://api.harbor.gg/v1
  description: Harbor API Production Server
security:
- bearerAuth: []
tags:
- name: Members
  description: Operations for managing community members, their profiles, point balances, and tier status.
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.
components:
  parameters:
    limitParam:
      name: limit
      in: query
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    pageParam:
      name: page
      in: query
      description: Page number for pagination (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
    memberIdParam:
      name: memberId
      in: path
      required: true
      description: The unique identifier of the community member.
      schema:
        type: string
    communityIdParam:
      name: communityId
      in: path
      required: true
      description: The unique identifier of the Harbor community.
      schema:
        type: string
  schemas:
    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
    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.
    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.
    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.
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained via OAuth 2.0 client credentials flow. Contact Harbor to obtain API credentials.
externalDocs:
  description: Harbor API Documentation
  url: https://api.harbor.gg/