Charter Captain Sub Out API

openapi: 3.2.0
info:
  title: Charter Captain Sub Out API
  version: 1.0.0
  description: REST API for the Charter Captain iOS apps
servers:
- url: http://localhost:3002
  description: Development
security:
- bearerAuth: []
tags:
- name: sub-out
paths:
  /api/v1/bookings/{id}/sub-out:
    post:
      operationId: postBookingSubOut
      summary: Request sub-out for a booking
      description: Originating captain requests to sub out a booking they own. Creates a Referral in REQUESTED state.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubOutRequestBody'
      responses:
        '201':
          description: Referral created
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /api/v1/sub-out/{referralId}/shortlist:
    get:
      operationId: getSubOutShortlist
      summary: Get shortlist candidates
      description: Returns the originating captain's preferred shortlist candidates for a referral, with a financial breakdown per candidate.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      responses:
        '200':
          description: List of shortlist candidates
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubOutShortlistCandidate'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/sub-out/{referralId}/offer:
    post:
      operationId: postSubOutOffer
      summary: Offer referral to a candidate
      description: Originating captain offers the sub-out referral to a specific candidate tenant from the shortlist. Per spec §10.9, candidateTenantId is the candidate captain's tenant identity, not their captain id.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferToCandidateBody'
      responses:
        '200':
          description: Offer recorded
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '412':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sub-out/{referralId}/expansion/request:
    post:
      operationId: postSubOutExpansionRequest
      summary: Request shortlist expansion
      description: Originating captain asks the boat owner to approve expanding the shortlist beyond the captain's preferred candidates.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      responses:
        '200':
          description: Expansion requested
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/sub-out/{referralId}/expansion/approve:
    post:
      operationId: postSubOutExpansionApprove
      summary: Approve shortlist expansion
      description: Boat owner approves the captain's request to expand the shortlist. Authorization is on tenantId (per spec §10.9).
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveExpansionBody'
      responses:
        '200':
          description: Expansion approved
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sub-out/{referralId}/expansion/decline:
    post:
      operationId: postSubOutExpansionDecline
      summary: Decline shortlist expansion
      description: Boat owner declines the captain's request to expand the shortlist. Transitions referral to FAILED.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      responses:
        '200':
          description: Expansion declined
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sub-out/opportunities:
    get:
      operationId: getSubOutOpportunities
      summary: List sub-out claim opportunities
      description: Candidate captain lists OWNER_APPROVED sub-out referrals available to claim. Filtered by marketplace opt-in, Stripe Connect onboarding, and source-tenant blacklist. Includes per-row financial breakdown.
      tags:
      - sub-out
      responses:
        '200':
          description: Available opportunities
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubOutOpportunity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/sub-out/{referralId}/accept:
    post:
      operationId: postSubOutAccept
      summary: Accept a sub-out offer
      description: Candidate captain accepts a sub-out referral offered to their tenant. Atomic transition to SHORTLIST_ACCEPTED with booking ownership reassignment. Body is empty `{}`. Per spec §10.9, the actor identity is Tenant, resolved from the authenticated captain id.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyBody'
      responses:
        '200':
          description: Offer accepted
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
  /api/v1/sub-out/{referralId}/decline:
    post:
      operationId: postSubOutDecline
      summary: Decline a sub-out offer
      description: Candidate captain declines a sub-out referral offered to their tenant. Resets the referral to REQUESTED so the originating captain can offer again. Optional `reason` field is accepted but not currently persisted.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: referralId
        in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Offer declined
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/sub-out/bookings/{bookingId}/claim:
    post:
      operationId: postSubOutClaim
      summary: Claim a marketplace-expanded sub-out booking
      description: Candidate captain claims an OWNER_APPROVED sub-out referral that was posted to the marketplace expansion. URL is keyed on bookingId for friendlier iOS UX; the route resolves the corresponding referral. Atomic guard rejects races with 409.
      tags:
      - sub-out
      parameters:
      - schema:
          type: string
        required: true
        name: bookingId
        in: path
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyBody'
      responses:
        '200':
          description: Booking claimed
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SubOutReferral'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
components:
  schemas:
    ApproveExpansionBody:
      type: object
      properties:
        postToMarketplace:
          type: boolean
      required:
      - postToMarketplace
    IdempotencyKeyHeader:
      type: string
      format: uuid
      description: Client-supplied UUID v4. Repeat requests with the same key return the cached response.
    EmptyBody:
      type: object
      properties: {}
      additionalProperties: {}
    OfferToCandidateBody:
      type: object
      properties:
        candidateTenantId:
          type: string
      required:
      - candidateTenantId
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
          required:
          - message
          - code
      required:
      - error
    SubOutReferral:
      type: object
      properties:
        id:
          type: string
        sourceType:
          type: string
        sourceId:
          type: string
        bookingId:
          type:
          - string
          - 'null'
        subOutState:
          type:
          - string
          - 'null'
        subOutReason:
          type:
          - string
          - 'null'
        status:
          type: string
        targetType:
          type: string
        targetId:
          type: string
        currentOfferId:
          type:
          - string
          - 'null'
        offerExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
        ownerApproval:
          type:
          - string
          - 'null'
      required:
      - id
      - sourceType
      - sourceId
      - bookingId
      - subOutState
      - subOutReason
      - status
      - targetType
      - targetId
    SubOutRequestBody:
      type: object
      properties:
        reason:
          type: string
    SubOutOpportunity:
      type: object
      properties:
        referralId:
          type: string
        booking:
          type: object
          properties:
            id:
              type: string
            date:
              type: string
              format: date-time
            startTime:
              type:
              - string
              - 'null'
            endTime:
              type:
              - string
              - 'null'
            harbor: {}
          required:
          - id
          - date
          - startTime
          - endTime
        breakdown:
          type: object
          properties:
            grossEarnings:
              type: number
            platformFee:
              type: number
            platformFeeRate:
              type: number
            netEarnings:
              type: number
          required:
          - grossEarnings
          - platformFee
          - platformFeeRate
          - netEarnings
      required:
      - referralId
      - booking
      - breakdown
    IdempotencyConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
              enum:
              - IDEMPOTENCY_CONFLICT
          required:
          - message
          - code
      required:
      - error
    SubOutShortlistCandidate:
      type: object
      properties:
        tenantId:
          type: string
        displayName:
          type: string
        slug:
          type: string
        captainId:
          type:
          - string
          - 'null'
        relationshipId:
          type: string
        priority:
          type: number
        breakdown:
          type: object
          properties:
            grossEarnings:
              type: number
            referralFee:
              type: number
            referralFeePercent:
              type: number
            platformFee:
              type: number
            platformFeeRate:
              type: number
            netEarnings:
              type: number
          required:
          - grossEarnings
          - referralFee
          - referralFeePercent
          - platformFee
          - platformFeeRate
          - netEarnings
      required:
      - tenantId
      - displayName
      - slug
      - captainId
      - relationshipId
      - priority
      - breakdown
  responses:
    NotFound:
      description: The requested resource does not exist (existence is not leaked).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required, or the bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Authenticated but not permitted to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Request body or query parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyConflict:
      description: Idempotency-Key was reused with a different request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdempotencyConflictError'
  parameters:
    IdempotencyKeyHeader:
      schema:
        $ref: '#/components/schemas/IdempotencyKeyHeader'
      required: false
      description: Client-supplied UUID v4. Repeat requests with the same key return the cached response.
      name: Idempotency-Key
      in: header
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Clerk JWT token