openapi: 3.0.3
info:
  title: TaskRabbit Partner Delivery Home Services Booking API
  description: 'TaskRabbit''s Partner API program, documented at developer.taskrabbit.com, spans two live surfaces: the Home Services Partner Platform (versioned 2025-12) covering the Estimate, Availability, Bid, Book project workflow plus catalog and cancellation/reschedule management, and the Delivery API inherited from Dolly (acquired by TaskRabbit in November 2024 and rebranded TaskRabbit Delivery). Both surfaces require partner approval and Auth0 OAuth2 client-credentials (machine-to-machine) tokens; there is no public self-serve signup. Endpoint shapes below are modeled from TaskRabbit''s public developer documentation (method, path, and the parameters/fields the docs describe); exact request/response schemas are partially withheld behind the gated Postman collection and reference pages given to approved partners, so object schemas here are best-effort and marked accordingly rather than fabricated in full detail.'
  version: 2025-12
  contact:
    name: TaskRabbit Developer Hub
    url: https://developer.taskrabbit.com
  x-endpointsModeled: true
  x-accessModel: Partner-approval gated; no public self-serve signup.
servers:
- url: https://{api_subdomain}.partner-platform.taskrabbit.com/2025-12
  description: TaskRabbit Home Services Partner Platform (partner-specific subdomain, Sandbox and Production)
  variables:
    api_subdomain:
      default: your-subdomain
      description: Subdomain issued to the partner during onboarding.
- url: https://papi.dolly.com/v1
  description: TaskRabbit Delivery (Dolly) Partner API - Production
- url: https://papi.sandbox.dolly.com/v1
  description: TaskRabbit Delivery (Dolly) Partner API - Sandbox
security:
- oauth2: []
tags:
- name: Home Services Booking
  description: Bid, book, retrieve, cancel, and reschedule Home Services projects.
paths:
  /projects/bid:
    post:
      operationId: bidProjectAgreement
      tags:
      - Home Services Booking
      summary: Bid Project Agreement
      description: Creates a formal price agreement for the customer's chosen date/time window and returns the most accurate pricing plus the Project UUID needed to complete the booking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BidRequest'
      responses:
        '201':
          description: Formal price quote and Project UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BidResponse'
        '400':
          description: Invalid bid request.
  /projects/book:
    post:
      operationId: bookProjectAgreement
      tags:
      - Home Services Booking
      summary: Book a Project Agreement
      description: Completes the booking created by projects/bid and confirms payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookRequest'
      responses:
        '201':
          description: Project booked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid booking request.
  /projects/list:
    post:
      operationId: listProjects
      tags:
      - Home Services Booking
      summary: List Projects
      description: Lists projects for the authenticated partner brand, per TaskRabbit's documented endpoint index.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Documented filter/pagination fields are not published; see the Postman collection provided at partner onboarding.
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
  /projects/{project_uuid}:
    get:
      operationId: getProjectByUuid
      tags:
      - Home Services Booking
      summary: Retrieve a Project by UUID
      description: Retrieves detailed information about a specific project.
      parameters:
      - name: project_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Project successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Project not found.
  /projects/{project_uuid}/cancel:
    post:
      operationId: cancelBookedProject
      tags:
      - Home Services Booking
      summary: Cancel Booked Project
      description: Cancels a booked project using an enumerated cancellation reason.
      parameters:
      - name: project_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cancellation_reason
              properties:
                cancellation_reason:
                  type: string
                  enum:
                  - order_canceled
                  - delivery_delayed
                  - changed_mind
                  - cancelled_by_cs
      responses:
        '201':
          description: Successfully cancelled Project.
        '400':
          description: Invalid cancellation_reason param.
  /projects/{project_uuid}/reschedule-availability:
    get:
      operationId: getRescheduleAvailability
      tags:
      - Home Services Booking
      summary: Check Reschedule Availability
      description: Returns available time windows a booked project can be rescheduled into.
      parameters:
      - name: project_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Available reschedule windows.
  /projects/{project_uuid}/reschedule:
    post:
      operationId: rescheduleProject
      tags:
      - Home Services Booking
      summary: Reschedule Project
      description: Reschedules a booked project to a new available time window.
      parameters:
      - name: project_uuid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Documented to require a selected reschedule window; exact field names are not published outside partner onboarding materials.
      responses:
        '201':
          description: Project rescheduled.
components:
  schemas:
    Location:
      type: object
      properties:
        postal_code:
          type: string
        address:
          type: string
    BidResponse:
      type: object
      properties:
        project_uuid:
          type: string
          format: uuid
        price_cents:
          type: integer
    BookRequest:
      type: object
      required:
      - client
      - project_uuid
      - client_amount_charged_cents
      - client_accepted_taskrabbit_policy
      - agreement_external_reference
      properties:
        client:
          type: object
          description: Client (service recipient) information.
        project_uuid:
          type: string
          format: uuid
        client_amount_charged_cents:
          type: integer
        client_accepted_taskrabbit_policy:
          type: boolean
        agreement_external_reference:
          type: string
        agreement_accounting_reference:
          type: string
    BidRequest:
      type: object
      required:
      - locale
      - currency
      - location
      - service_item_terms
      - target_start_time
      properties:
        locale:
          type: string
          enum:
          - en-US
        currency:
          type: string
          enum:
          - USD
        location:
          $ref: '#/components/schemas/Location'
        service_item_terms:
          type: array
          items:
            $ref: '#/components/schemas/ServiceItemRequest'
        target_start_time:
          type: string
          format: date-time
    Project:
      type: object
      properties:
        project_uuid:
          type: string
          format: uuid
        status:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceItemRequest'
    ServiceItemRequest:
      type: object
      description: A requested service line item; exact field list beyond category/quantity is not published outside partner materials.
      properties:
        service_id:
          type: string
        quantity:
          type: integer
  securitySchemes:
    oauth2:
      type: oauth2
      description: Auth0 machine-to-machine (M2M) OAuth2 client-credentials grant. Credentials are issued during partner onboarding.
      flows:
        clientCredentials:
          tokenUrl: https://taskrabbit.auth0.com/oauth/token
          scopes: {}