openapi: 3.0.3
info:
  title: Uplisting Public and Partner Account Webhooks API
  description: 'Uplisting is short-term / vacation rental management software and a channel manager. This OpenAPI describes Uplisting''s invite-only Public and Partner REST API, which lets partners read properties, bookings, availability, and calendar data (prices and restrictions), create confirmed bookings, and register webhooks that push booking changes.


    Base URL: https://connect.uplisting.io (production). Staging uses the same paths on a different base domain; accounts and API keys are environment-specific.


    Authentication is HTTP Basic: send `Authorization: Basic <base64(api_key)>`. API keys are generated on the Connect page in the Uplisting app. V2 endpoints additionally require a Client ID (partner identifier). API access is invite-only - request access from support@uplisting.io.


    Grounding note: the Users, Properties, Bookings, Availability, and Calendar surfaces and the webhook behavior are confirmed from Uplisting''s public documentation. The exact request/response schemas and the Rates, Guests, and Messages resources are MODELED from Uplisting''s documented product behavior because the full reference is behind an invite-only Postman collection. Operations that are modeled are marked with `x-modeled: true`.'
  version: '1.0'
  contact:
    name: Uplisting Support
    url: https://support.uplisting.io/docs/api
    email: support@uplisting.io
servers:
- url: https://connect.uplisting.io
  description: Production
security:
- basicAuth: []
tags:
- name: Webhooks
  description: Endpoints that receive booking change events.
paths:
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List webhook endpoints
      description: Lists the registered webhook endpoints for the account. Confirmed webhook mechanism; shape modeled.
      responses:
        '200':
          description: A list of webhook endpoints.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Register a webhook endpoint
      description: Registers an endpoint to receive booking created, updated, and removed events. The endpoint must return a 2xx within 5 seconds; after 5 consecutive delivery failures it is auto-disabled. Confirmed behavior; request/response fields modeled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: The registered webhook endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /webhooks/{webhookId}:
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook endpoint
      description: Removes a registered webhook endpoint. Confirmed webhook mechanism; shape modeled.
      parameters:
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '204':
          description: The webhook endpoint was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded. Back off and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Webhook:
      type: object
      description: A registered webhook endpoint. Fields modeled.
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
            - booking.created
            - booking.updated
            - booking.removed
        enabled:
          type: boolean
    WebhookCreate:
      type: object
      description: Payload to register a webhook endpoint. Fields modeled.
      required:
      - url
      properties:
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
            - booking.created
            - booking.updated
            - booking.removed
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  parameters:
    WebhookId:
      name: webhookId
      in: path
      required: true
      schema:
        type: string
      description: The webhook endpoint identifier.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic auth. Send `Authorization: Basic <base64(api_key)>`, where api_key is generated on the Uplisting Connect page. V2 endpoints also require a Client ID partner identifier.'