openapi: 3.1.0
info:
  title: Harbor Challenges 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: Challenges
  description: Operations for managing challenges that members complete to earn points and rewards.
paths:
  /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.
components:
  parameters:
    challengeIdParam:
      name: challengeId
      in: path
      required: true
      description: The unique identifier of the challenge.
      schema:
        type: string
    communityIdParam:
      name: communityId
      in: path
      required: true
      description: The unique identifier of the Harbor community.
      schema:
        type: string
  schemas:
    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.
    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.
    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.
  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/