> ## Documentation Index > Fetch the complete documentation index at: https://docs.sparkserv.com/llms.txt > Use this file to discover all available pages before exploring further. # Find available appointment times > Returned slots are observations, not reservations. ## OpenAPI ````yaml https://api.sparkserv.com/public/api/swagger.json post /availability/search openapi: 3.1.0 info: title: Spark Public API description: >- Dealership discovery and vehicle-specific appointment scheduling. Obtain a token with POST https://auth.sparkserv.com/oauth/token, Content-Type: application/json, and a body containing grant_type: client_credentials, client_id, client_secret, audience: https://api.sparkserv.com/public, and the requested scope string. Send Authorization: Bearer on API requests. Keep client secrets on your server, not in browser applications. Required scopes must be granted both in the token and on the active Spark API client. Dealership access follows its acting-user team memberships. Availability is not a reservation. Booking has no durable idempotency guarantee. Do not blindly retry mutations after timeouts or unknown outcomes; Spark appointment reads are local snapshots, not proof of the current upstream state. Unknown outcomes require reconciliation with the dealership or scheduler. version: '1' contact: {} servers: - url: https://api.sparkserv.com/public/v1 description: Current API environment security: [] tags: [] paths: /availability/search: post: tags: - Scheduling summary: Find available appointment times description: Returned slots are observations, not reservations. operationId: findPublicAvailabilityV1 parameters: - name: Dealership-Id in: header required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicSchedulingAvailabilityV1Dto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicAvailabilityV1ResponseDto' '400': description: >- Invalid request. Inspect code and details and correct the input before retrying. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: invalidInput: summary: Correct the request fields value: statusCode: 400 code: INVALID_INPUT message: Request validation failed '401': description: >- Missing, invalid or expired client-credentials token, or an inactive client. Obtain a valid token for an active client. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: unauthorized: summary: Authenticate with an active client value: statusCode: 401 code: UNAUTHORIZED message: The request could not be completed '403': description: The token or active API client lacks a required action scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: forbidden: summary: Grant the required scope and obtain a new token value: statusCode: 403 code: FORBIDDEN message: The request could not be completed '404': description: >- The resource does not exist or is outside the client's dealership access. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: notFound: summary: Check the resource and dealership access value: statusCode: 404 code: NOT_FOUND message: Resource not found '409': description: >- Exactly one scheduling integration must be configured for the dealership. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: schedulerConfiguration: summary: Configure one supported scheduler value: statusCode: 409 code: SCHEDULER_CONFIGURATION message: Exactly one scheduling integration is required '422': description: >- The configured scheduler is unsupported or a required selection or customer/vehicle detail cannot be resolved. Inspect code and details. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: schedulerUnsupported: summary: Use a supported scheduler value: statusCode: 422 code: SCHEDULER_UNSUPPORTED message: This scheduler is not supported by this API '500': description: An unexpected server error prevented the request from completing. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: requestFailed: summary: Report the unexpected failure value: statusCode: 500 code: REQUEST_FAILED message: The request could not be completed '502': description: >- The scheduler or an upstream dependency could not complete this discovery request. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: schedulerUnavailable: summary: Retry discovery after the scheduler recovers value: statusCode: 502 code: SCHEDULER_UNAVAILABLE message: The scheduler could not complete the request security: - oauth2: - scheduling:read components: schemas: PublicSchedulingAvailabilityV1Dto: type: object properties: departmentId: type: string description: An opaque department ID from department discovery customer: description: >- Required during discovery only when the scheduler needs customer identity allOf: - $ref: '#/components/schemas/PublicCustomerDetailsV1Dto' vehicle: $ref: '#/components/schemas/PublicSchedulingVehicleV1Dto' serviceIds: type: array items: type: string format: uuid minItems: 1 uniqueItems: true description: Spark service UUIDs from service discovery startDate: type: string format: date description: First inclusive dealership-local date; defaults to today endDate: type: string format: date description: >- Last inclusive dealership-local date; at most seven dates per request advisorId: type: string description: Opaque advisor ID, or any; omitted means any eligible advisor transportId: type: string description: >- Opaque transport ID from transport discovery; omitted selects a safe drop-off default required: - vehicle - serviceIds additionalProperties: false PublicAvailabilityV1ResponseDto: type: object properties: timezone: type: string example: America/New_York vehicle: $ref: '#/components/schemas/PublicResolvedVehicleV1ResponseDto' department: oneOf: - $ref: '#/components/schemas/PublicDepartmentV1ResponseDto' - type: 'null' transport: $ref: '#/components/schemas/PublicTransportV1ResponseDto' items: type: array items: $ref: '#/components/schemas/PublicAppointmentSlotV1ResponseDto' required: - timezone - vehicle - department - transport - items PublicApiErrorResponseDto: type: object properties: statusCode: type: integer code: type: string description: Stable machine-readable error code message: type: string details: description: >- Validation messages or contextual fields/choices; never raw scheduler error data oneOf: - type: object additionalProperties: true - type: array items: type: string required: - statusCode - code - message PublicCustomerDetailsV1Dto: type: object properties: firstName: type: string description: Omit for a business customer lastName: type: string description: Customer surname or business name phoneNumber: type: string example: '2125550101' email: type: string format: email required: - lastName - phoneNumber additionalProperties: false PublicSchedulingVehicleV1Dto: type: object properties: vin: type: string description: VIN to decode; otherwise supply year, make and model example: 1HGCM82633A004352 year: type: integer minimum: 1886 maximum: 2200 example: 2024 make: type: string example: Honda model: type: string example: Civic trim: type: string mileage: type: integer minimum: 0 description: >- Identify the vehicle by VIN or by year, make and model. VIN may be enriched with partial details. additionalProperties: false PublicResolvedVehicleV1ResponseDto: type: object properties: year: type: number make: type: string model: type: string vin: type: string mileage: type: number trim: type: string required: - year - make - model PublicDepartmentV1ResponseDto: type: object properties: id: type: string name: type: string isDefault: type: boolean required: - id - name PublicTransportV1ResponseDto: type: object properties: id: type: string name: type: string required: - id - name PublicAppointmentSlotV1ResponseDto: type: object properties: appointmentAt: type: string format: date-time description: UTC instant; an availability observation, not a reservation appointmentAtLocal: type: string format: date-time description: Dealership-local timestamp with explicit offset advisorId: type: string required: - appointmentAt - appointmentAtLocal - advisorId securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.sparkserv.com/oauth/token scopes: appointments:update: appointments:update appointments:cancel: appointments:cancel dealerships:read: dealerships:read scheduling:read: scheduling:read customers:read: customers:read appointments:read: appointments:read appointments:create: appointments:create ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.