openapi: 3.0.3
info:
  title: Spark Hire Account Jobs 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: Jobs
  description: Jobs (requisitions) that interviews are organized under.
paths:
  /jobs:
    get:
      operationId: listJobs
      tags:
      - Jobs
      summary: List jobs
      parameters:
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/StatusFilter'
      responses:
        '200':
          description: A list of jobs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createJob
      tags:
      - Jobs
      summary: Create a job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobInput'
      responses:
        '201':
          description: The created job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
  /jobs/{uuid}:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getJob
      tags:
      - Jobs
      summary: Get a job
      responses:
        '200':
          description: A job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateJob
      tags:
      - Jobs
      summary: Update a job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobInput'
      responses:
        '200':
          description: The updated job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteJob
      tags:
      - Jobs
      summary: Delete a job
      responses:
        '204':
          description: The job was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Job:
      allOf:
      - $ref: '#/components/schemas/JobInput'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
    JobInput:
      type: object
      properties:
        title:
          type: string
        status:
          type: string
          description: e.g. open, closed, draft.
        description:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  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
    StatusFilter:
      name: status[]
      in: query
      required: false
      description: Filter by one or more statuses.
      schema:
        type: array
        items:
          type: string
    OrderBy:
      name: orderby
      in: query
      required: false
      description: Sort order, e.g. title_asc or updated_desc.
      schema:
        type: string
        example: updated_desc
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.