openapi: 3.0.3
info:
  title: Spark Hire Account Share Links API
  description: 'The Spark Hire API embeds video interviewing and talent assessment into an applicant tracking system or custom hiring application. It is a RESTful API with JSON responses served under https://api.sparkhire.com/v1.0. It manages jobs, one-way and live video interviews, interview questions and reusable question sets, company users (evaluators) and their integration API keys, candidate share links, and webhook subscriptions for interview and job lifecycle events.


    Authentication uses HTTP Basic: the username is your API key and the password is ignored. API keys are tied to an individual user and respect that user''s permission level. API access is not self-serve - it must be enabled on your account by Spark Hire - but the API reference is fully public. Timestamps are RFC3339. Rate limit is 400 requests per minute; exceeding it returns 429 with an X-Rate-Limit-Try-Again-Seconds header.


    Endpoint paths and behavior below are transcribed from the public Spark Hire API reference at https://docs.sparkhire.com/. Request and response schemas are honestly modeled from the documented resources; exercising them live requires API access enabled by Spark Hire.'
  version: '1.0'
  contact:
    name: Spark Hire
    url: https://www.sparkhire.com
servers:
- url: https://api.sparkhire.com/v1.0
  description: Spark Hire API
security:
- basicAuth: []
tags:
- name: Share Links
  description: Basic and advanced share links for reviewing interviews.
paths:
  /interviews/{uuid}/share_link:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getBasicShareLink
      tags:
      - Share Links
      summary: Get the basic share link for an interview
      responses:
        '200':
          description: A share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
    post:
      operationId: createBasicShareLink
      tags:
      - Share Links
      summary: Create a basic share link for an interview
      responses:
        '201':
          description: The created share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
  /interviews/{uuid}/share_link/{linkUuid}:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    - name: linkUuid
      in: path
      required: true
      description: The UUID of the share link.
      schema:
        type: string
        format: uuid
    put:
      operationId: updateBasicShareLink
      tags:
      - Share Links
      summary: Update a basic share link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareLinkInput'
      responses:
        '200':
          description: The updated share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
  /share_links:
    get:
      operationId: listShareLinks
      tags:
      - Share Links
      summary: List advanced share links
      parameters:
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: A list of share links.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShareLink'
    post:
      operationId: createShareLink
      tags:
      - Share Links
      summary: Create an advanced share link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareLinkInput'
      responses:
        '201':
          description: The created share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
  /share_links/{uuid}:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getShareLink
      tags:
      - Share Links
      summary: Get an advanced share link
      responses:
        '200':
          description: A share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateShareLink
      tags:
      - Share Links
      summary: Update an advanced share link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareLinkInput'
      responses:
        '200':
          description: The updated share link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
    delete:
      operationId: deleteShareLink
      tags:
      - Share Links
      summary: Delete an advanced share link
      responses:
        '204':
          description: The share link was deleted.
components:
  parameters:
    Uuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
    Range:
      name: range
      in: query
      required: false
      description: Pagination range, e.g. 1-20 or 10-30.
      schema:
        type: string
        example: 1-20
    OrderBy:
      name: orderby
      in: query
      required: false
      description: Sort order, e.g. title_asc or updated_desc.
      schema:
        type: string
        example: updated_desc
  responses:
    NotFound:
      description: The resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ShareLink:
      allOf:
      - $ref: '#/components/schemas/ShareLinkInput'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
          url:
            type: string
            format: uri
          created_at:
            type: string
            format: date-time
    ShareLinkInput:
      type: object
      properties:
        interview_uuid:
          type: string
          format: uuid
        expires_at:
          type: string
          format: date-time
          nullable: true
        password_protected:
          type: boolean
        allow_ratings:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. The username is your Spark Hire API key; the password is ignored. Keys are scoped to a user and respect that user's permission level.