Snappr Bookings API

openapi: 3.1.0
info:
  title: Snappr Availability Bookings API
  version: 1.0.0
  summary: The API for visual content.
  description: 'The Snappr API is a universal API for commissioning and handling visual content: on-demand photography with Snappr network photographers, automated and human-augmented photo editing services, and retrieval of the resulting images and videos. The API is available only to Snappr for Enterprise customers. Faithfully generated by the API Evangelist enrichment pipeline from the public documentation at https://docs.snappr.com/ (no fabricated operations or fields).'
  contact:
    name: Snappr for Enterprise
    url: https://www.snappr.com/enterprise
  x-apievangelist-generated: true
servers:
- url: https://api.snappr.com
  description: Production
- url: https://sandbox.snappr.com
  description: Sandbox (returns dummy data; write actions are not persisted)
security:
- bearerAuth: []
tags:
- name: Bookings
  description: Create and retrieve photoshoot bookings.
paths:
  /bookings:
    get:
      operationId: listBookings
      tags:
      - Bookings
      summary: Get All Bookings
      description: Retrieves all bookings, paginated with limit and offset.
      parameters:
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A paginated list of bookings.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedEnvelope'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Error'
    post:
      operationId: createBooking
      tags:
      - Bookings
      summary: Create New Booking
      description: Creates a new photoshoot booking. Provide all shoot details including start_at, or set start_at to null to have Snappr collect the start time from the end-customer (the response then includes a scheduling_url). Always check availability before creating a booking with start_at defined, or a 400 NoCoverage/NotAvailable error may be returned.
      parameters:
      - $ref: '#/components/parameters/AcceptVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '200':
          description: The created booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
  /bookings/{booking_uid}:
    get:
      operationId: getBooking
      tags:
      - Bookings
      summary: Get Single Booking
      description: Retrieves a specific booking by its identifier.
      parameters:
      - $ref: '#/components/parameters/AcceptVersion'
      - $ref: '#/components/parameters/BookingUid'
      responses:
        '200':
          description: The requested booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return.
      schema:
        type: integer
    Offset:
      name: offset
      in: query
      description: Offset used for pagination. Defaults to 0.
      schema:
        type: integer
        default: 0
    BookingUid:
      name: booking_uid
      in: path
      required: true
      description: The identifier of the booking.
      schema:
        type: string
    AcceptVersion:
      name: accept-version
      in: header
      required: false
      description: Requested API version (e.g. "1.0.0").
      schema:
        type: string
        default: 1.0.0
  schemas:
    Booking:
      type: object
      properties:
        uid:
          type: string
        title:
          type: string
        status:
          type: string
          description: e.g. paid, paid_pending_schedule.
        credits:
          type: integer
        latitude:
          type: number
        longitude:
          type: number
        shoottype:
          type: string
        start_at:
          type:
          - string
          - 'null'
          format: date-time
        duration:
          type: integer
        location_notes:
          type: string
        style_notes:
          type: string
        customer_firstname:
          type: string
        customer_surname:
          type:
          - string
          - 'null'
        customer_email:
          type: string
          format: email
        customer_mobilephone:
          type: string
        customer_company:
          type:
          - string
          - 'null'
        internal_id:
          type: string
        creator_name:
          type: string
        creator_id:
          type: string
        creator_profile_image_url:
          type: string
          format: uri
        scheduling_url:
          type: string
          format: uri
          description: Present when start_at was null; the end-customer picks a time here.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
    PaginatedEnvelope:
      type: object
      properties:
        count:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    BookingCreate:
      type: object
      required:
      - shoottype
      - start_at
      - duration
      - customer_firstname
      - customer_email
      - customer_mobilephone
      properties:
        title:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        address:
          type: string
          description: Google Maps valid address; alternative to latitude/longitude.
        shoottype:
          type: string
        start_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Start time in UTC. Set to null to have Snappr collect it from the end-customer.
        duration:
          type: integer
        location_notes:
          type: string
        style_notes:
          type: string
        customer_firstname:
          type: string
        customer_surname:
          type: string
        customer_email:
          type: string
          format: email
        customer_mobilephone:
          type: string
        customer_company:
          type: string
        internal_id:
          type: string
        creator_id:
          type: string
        tags:
          type: array
          items:
            type: string
    Error:
      type: object
      description: Snappr error envelope. Named error in the response body with an optional Problems field on validation errors.
      properties:
        name:
          type: string
        message:
          type: string
        problems:
          type: array
          items:
            type: object
  responses:
    Error:
      description: Error response. See the error catalog for named error codes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as a bearer token in the Authorization header (Authorization: Bearer <api_key>). Each user has a single unique active API key, managed in the Snappr Photography Portal.'
externalDocs:
  description: Snappr API Documentation
  url: https://docs.snappr.com/