openapi: 3.0.3
info:
  title: Dub Analytics Bounties API
  description: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
  version: 0.0.1
  contact:
    name: Dub Support
    email: support@dub.co
    url: https://dub.co/support
  license:
    name: AGPL-3.0 license
    url: https://github.com/dubinc/dub/blob/main/LICENSE.md
servers:
- url: https://api.dub.co
  description: Production API
tags:
- name: Bounties
paths:
  /bounties/{bountyId}/submissions:
    get:
      operationId: listBountySubmissions
      x-speakeasy-name-override: listSubmissions
      summary: List bounty submissions
      description: List all submissions for a specific bounty in your partner program.
      tags:
      - Bounties
      security:
      - token: []
      parameters:
      - in: path
        name: bountyId
        schema:
          type: string
          description: The unique ID of the bounty on Dub. Can be found in the URL of the bounty page, prefixed with `bnty_`.
        required: true
        description: The unique ID of the bounty on Dub. Can be found in the URL of the bounty page, prefixed with `bnty_`.
      - in: query
        name: status
        schema:
          description: The status of the submissions to list.
          type: string
          enum:
          - draft
          - submitted
          - approved
          - rejected
        description: The status of the submissions to list.
      - in: query
        name: groupId
        schema:
          description: The ID of the group to list submissions for.
          type: string
        description: The ID of the group to list submissions for.
      - in: query
        name: partnerId
        schema:
          description: The ID of the partner to list submissions for.
          type: string
        description: The ID of the partner to list submissions for.
      - in: query
        name: sortBy
        schema:
          default: completedAt
          description: The field to sort the submissions by.
          type: string
          enum:
          - completedAt
          - performanceCount
          - socialMetricCount
        description: The field to sort the submissions by.
      - in: query
        name: sortOrder
        schema:
          default: asc
          description: The order to sort the submissions by.
          type: string
          enum:
          - asc
          - desc
        description: The order to sort the submissions by.
      - in: query
        name: page
        schema:
          description: The page number for pagination.
          example: 1
          deprecated: false
          type: number
          minimum: 0
          exclusiveMinimum: true
        description: The page number for pagination.
      - in: query
        name: pageSize
        schema:
          default: 100
          description: The number of items per page.
          example: 50
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 100
        description: The number of items per page.
      responses:
        '200':
          description: The list of bounty submissions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The ID of the bounty submission
                    bountyId:
                      type: string
                      description: The ID of the bounty
                    partnerId:
                      type: string
                      description: The ID of the partner
                    description:
                      nullable: true
                      description: The description of the submission
                      type: string
                    urls:
                      nullable: true
                      description: The URLs submitted for the submission
                      type: array
                      items:
                        type: string
                    files:
                      nullable: true
                      description: The files uploaded for the submission
                      type: array
                      items:
                        type: object
                        properties:
                          url:
                            type: string
                            format: uri
                            description: The URL of the uploaded file.
                          fileName:
                            type: string
                            description: The original file name.
                          size:
                            type: number
                            description: The file size in bytes.
                        required:
                        - url
                        - fileName
                        - size
                        additionalProperties: false
                    status:
                      type: string
                      enum:
                      - draft
                      - submitted
                      - approved
                      - rejected
                      description: The status of the submission
                    performanceCount:
                      description: The performance count of the submission
                      nullable: true
                      type: number
                    socialMetricCount:
                      nullable: true
                      description: The social metric count (views or likes) for the social content
                      type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    socialMetricsLastSyncedAt:
                      description: The date and time the submission's social metrics were last synced
                      nullable: true
                      type: string
                    createdAt:
                      description: The date and time the submission was created
                      type: string
                    completedAt:
                      nullable: true
                      description: The date and time the submission was completed
                      type: string
                    reviewedAt:
                      nullable: true
                      description: The date and time the submission was reviewed
                      type: string
                    rejectionReason:
                      nullable: true
                      description: The reason for rejecting the submission
                      type: string
                    rejectionNote:
                      nullable: true
                      description: The note for rejecting the submission
                      type: string
                    periodNumber:
                      type: integer
                      minimum: 1
                      maximum: 9007199254740991
                      description: The period number for this submission (1-indexed)
                  required:
                  - id
                  - bountyId
                  - partnerId
                  - description
                  - urls
                  - files
                  - status
                  - performanceCount
                  - socialMetricCount
                  - createdAt
                  - completedAt
                  - reviewedAt
                  - rejectionReason
                  - rejectionNote
                  - periodNumber
                  additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '410':
          $ref: '#/components/responses/410'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /bounties/{bountyId}/submissions/{submissionId}/approve:
    post:
      operationId: approveBountySubmission
      x-speakeasy-name-override: approveSubmission
      summary: Approve a bounty submission
      description: Approve a bounty submission. Optionally specify a custom reward amount.
      tags:
      - Bounties
      security:
      - token: []
      parameters:
      - in: path
        name: bountyId
        schema:
          type: string
          description: The ID of the bounty
        required: true
        description: The ID of the bounty
      - in: path
        name: submissionId
        schema:
          type: string
          description: The ID of the bounty submission
        required: true
        description: The ID of the bounty submission
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rewardAmount:
                  description: The reward amount for the performance-based bounty. Applicable if the bounty reward amount is not set.
                  nullable: true
                  type: number
      responses:
        '200':
          description: The approved bounty submission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the bounty submission
                  bountyId:
                    type: string
                    description: The ID of the bounty
                  partnerId:
                    type: string
                    description: The ID of the partner
                  description:
                    nullable: true
                    description: The description of the submission
                    type: string
                  urls:
                    nullable: true
                    description: The URLs submitted for the submission
                    type: array
                    items:
                      type: string
                  files:
                    nullable: true
                    description: The files uploaded for the submission
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: The URL of the uploaded file.
                        fileName:
                          type: string
                          description: The original file name.
                        size:
                          type: number
                          description: The file size in bytes.
                      required:
                      - url
                      - fileName
                      - size
                      additionalProperties: false
                  status:
                    type: string
                    enum:
                    - draft
                    - submitted
                    - approved
                    - rejected
                    description: The status of the submission
                  performanceCount:
                    description: The performance count of the submission
                    nullable: true
                    type: number
                  socialMetricCount:
                    nullable: true
                    description: The social metric count (views or likes) for the social content
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  socialMetricsLastSyncedAt:
                    description: The date and time the submission's social metrics were last synced
                    nullable: true
                    type: string
                  createdAt:
                    description: The date and time the submission was created
                    type: string
                  completedAt:
                    nullable: true
                    description: The date and time the submission was completed
                    type: string
                  reviewedAt:
                    nullable: true
                    description: The date and time the submission was reviewed
                    type: string
                  rejectionReason:
                    nullable: true
                    description: The reason for rejecting the submission
                    type: string
                  rejectionNote:
                    nullable: true
                    description: The note for rejecting the submission
                    type: string
                  periodNumber:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                    description: The period number for this submission (1-indexed)
                required:
                - id
                - bountyId
                - partnerId
                - description
                - urls
                - files
                - status
                - performanceCount
                - socialMetricCount
                - createdAt
                - completedAt
                - reviewedAt
                - rejectionReason
                - rejectionNote
                - periodNumber
                additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '410':
          $ref: '#/components/responses/410'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /bounties/{bountyId}/submissions/{submissionId}/reject:
    post:
      operationId: rejectBountySubmission
      x-speakeasy-name-override: rejectSubmission
      summary: Reject a bounty submission
      description: Reject a bounty submission with a specified reason and optional note.
      tags:
      - Bounties
      security:
      - token: []
      parameters:
      - in: path
        name: bountyId
        schema:
          type: string
          description: The ID of the bounty
        required: true
        description: The ID of the bounty
      - in: path
        name: submissionId
        schema:
          type: string
          description: The ID of the bounty submission
        required: true
        description: The ID of the bounty submission
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rejectionReason:
                  description: The reason for rejecting the submission.
                  type: string
                  enum:
                  - invalidProof
                  - duplicateSubmission
                  - outOfTimeWindow
                  - didNotMeetCriteria
                  - other
                rejectionNote:
                  description: The note for rejecting the submission.
                  type: string
                  maxLength: 5000
      responses:
        '200':
          description: The rejected bounty submission.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the bounty submission
                  bountyId:
                    type: string
                    description: The ID of the bounty
                  partnerId:
                    type: string
                    description: The ID of the partner
                  description:
                    nullable: true
                    description: The description of the submission
                    type: string
                  urls:
                    nullable: true
                    description: The URLs submitted for the submission
                    type: array
                    items:
                      type: string
                  files:
                    nullable: true
                    description: The files uploaded for the submission
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                          description: The URL of the uploaded file.
                        fileName:
                          type: string
                          description: The original file name.
                        size:
                          type: number
                          description: The file size in bytes.
                      required:
                      - url
                      - fileName
                      - size
                      additionalProperties: false
                  status:
                    type: string
                    enum:
                    - draft
                    - submitted
                    - approved
                    - rejected
                    description: The status of the submission
                  performanceCount:
                    description: The performance count of the submission
                    nullable: true
                    type: number
                  socialMetricCount:
                    nullable: true
                    description: The social metric count (views or likes) for the social content
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  socialMetricsLastSyncedAt:
                    description: The date and time the submission's social metrics were last synced
                    nullable: true
                    type: string
                  createdAt:
                    description: The date and time the submission was created
                    type: string
                  completedAt:
                    nullable: true
                    description: The date and time the submission was completed
                    type: string
                  reviewedAt:
                    nullable: true
                    description: The date and time the submission was reviewed
                    type: string
                  rejectionReason:
                    nullable: true
                    description: The reason for rejecting the submission
                    type: string
                  rejectionNote:
                    nullable: true
                    description: The note for rejecting the submission
                    type: string
                  periodNumber:
                    type: integer
                    minimum: 1
                    maximum: 9007199254740991
                    description: The period number for this submission (1-indexed)
                required:
                - id
                - bountyId
                - partnerId
                - description
                - urls
                - files
                - status
                - performanceCount
                - socialMetricCount
                - createdAt
                - completedAt
                - reviewedAt
                - rejectionReason
                - rejectionNote
                - periodNumber
                additionalProperties: false
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '410':
          $ref: '#/components/responses/410'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '500':
      description: The server has encountered a situation it does not know how to handle.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: InternalServerError
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - internal_server_error
                    description: A short code indicating the error code returned.
                    example: internal_server_error
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#internal-server_error
                required:
                - code
                - message
            required:
            - error
    '429':
      description: The user has sent too many requests in a given amount of time ("rate limiting")
      content:
        application/json:
          schema:
            x-speakeasy-name-override: RateLimitExceeded
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - rate_limit_exceeded
                    description: A short code indicating the error code returned.
                    example: rate_limit_exceeded
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#rate-limit_exceeded
                required:
                - code
                - message
            required:
            - error
    '422':
      description: The request was well-formed but was unable to be followed due to semantic errors.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: UnprocessableEntity
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - unprocessable_entity
                    description: A short code indicating the error code returned.
                    example: unprocessable_entity
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#unprocessable-entity
                required:
                - code
                - message
            required:
            - error
    '403':
      description: The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: Forbidden
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - forbidden
                    description: A short code indicating the error code returned.
                    example: forbidden
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#forbidden
                required:
                - code
                - message
            required:
            - error
    '404':
      description: The server cannot find the requested resource.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: NotFound
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - not_found
                    description: A short code indicating the error code returned.
                    example: not_found
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#not-found
                required:
                - code
                - message
            required:
            - error
    '401':
      description: Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: Unauthorized
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - unauthorized
                    description: A short code indicating the error code returned.
                    example: unauthorized
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#unauthorized
                required:
                - code
                - message
            required:
            - error
    '400':
      description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
      content:
        application/json:
          schema:
            x-speakeasy-name-override: BadRequest
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - bad_request
                    description: A short code indicating the error code returned.
                    example: bad_request
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#bad-request
                required:
                - code
                - message
            required:
            - error
    '409':
      description: This response is sent when a request conflicts with the current state of the server.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: Conflict
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - conflict
                    description: A short code indicating the error code returned.
                    example: conflict
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#conflict
                required:
                - code
                - message
            required:
            - error
    '410':
      description: This response is sent when the requested content has been permanently deleted from server, with no forwarding address.
      content:
        application/json:
          schema:
            x-speakeasy-name-override: InviteExpired
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - invite_expired
                    description: A short code indicating the error code returned.
                    example: invite_expired
                  message:
                    x-speakeasy-error-message: true
                    type: string
                    description: A human readable explanation of what went wrong.
                    example: The requested resource was not found.
                  doc_url:
                    type: string
                    description: A link to our documentation with more details about this error code
                    example: https://dub.co/docs/api-reference/errors#invite-expired
                required:
                - code
                - message
            required:
            - error
  securitySchemes:
    token:
      type: http
      description: Default authentication mechanism
      scheme: bearer
      x-speakeasy-example: DUB_API_KEY