Documentation | Codiris

InterviewClient

The main client class for interacting with the Codiris Interview API.

import { InterviewClient } from '@codiris/interview-sdk';

const client = new InterviewClient({
  apiKey: 'your-api-key',           // Required
  baseUrl: 'https://...',           // Optional, defaults to production
  workspaceId: 'workspace-id',      // Optional
  timeout: 30000,                   // Optional, defaults to 30s
});

Projects

getProject

Get a project by ID

getProject(projectId: string): Promise<APIResponse<InterviewProject>>

const { data: project } = await client.getProject('proj_123');
console.log(project.name, project.useCase);

listProjects

List all projects with optional filters

listProjects(options?: { status?: string; page?: number; pageSize?: number }): Promise<APIResponse<PaginatedResponse<InterviewProject>>>

const { data } = await client.listProjects({
  status: 'active',
  page: 1,
  pageSize: 20,
});
console.log(`Found ${data.total} projects`);

createProject

Create a new interview project

createProject(data: CreateProjectInput): Promise<APIResponse<InterviewProject>>

const { data: project } = await client.createProject({
  name: 'Engineering Interviews',
  useCase: 'recruitment',
  goal: 'Assess technical skills',
  audience: 'Software engineers',
});

updateProject

Update an existing project

updateProject(projectId: string, data: Partial<InterviewProject>): Promise<APIResponse<InterviewProject>>

await client.updateProject('proj_123', {
  name: 'Updated Name',
  status: 'published',
});

deleteProject

Delete a project

deleteProject(projectId: string): Promise<APIResponse<void>>

Interviews

getInterview

Get an interview by ID

getInterview(interviewId: string): Promise<APIResponse<Interview>>

const { data: interview } = await client.getInterview('int_456');
console.log(interview.candidateName, interview.status);

listInterviews

List interviews for a project with optional filters

listInterviews(projectId: string, filters?: InterviewFilters): Promise<APIResponse<PaginatedResponse<Interview>>>

const { data } = await client.listInterviews('proj_123', {
  status: ['completed', 'published'],
  dateRange: {
    from: '2024-01-01',
    to: '2024-12-31',
  },
  page: 1,
  pageSize: 50,
});

createInterview

Create a new interview session

createInterview(projectId: string, data?: CreateInterviewInput): Promise<APIResponse<Interview>>

const { data: interview } = await client.createInterview('proj_123', {
  candidateName: 'John Doe',
  candidateEmail: 'john@example.com',
});

saveInterview

Save/update interview data (transcript, answers, etc.)

saveInterview(data: SaveInterviewInput): Promise<APIResponse<{ interviewId: string }>>

await client.saveInterview({
  interviewId: 'int_456',
  projectId: 'proj_123',
  transcript: messages,
  status: 'in_progress',
});

completeInterview

Mark an interview as completed

completeInterview(interviewId: string, data: CompleteInterviewInput): Promise<APIResponse<Interview>>

await client.completeInterview('int_456', {
  transcript: messages,
  summary: 'AI-generated summary...',
  rating: 4,
  duration: 1800, // seconds
});

Transcripts & Recordings

getTranscript

Get the transcript for an interview

getTranscript(interviewId: string): Promise<APIResponse<ChatMessage[]>>

const { data: transcript } = await client.getTranscript('int_456');
transcript.forEach(msg => {
  console.log(`[${msg.role}]: ${msg.content}`);
});

getVoiceTranscript

Get voice-specific transcript with timestamps

getVoiceTranscript(interviewId: string): Promise<APIResponse<VoiceTranscript>>

getAudioUrl

Get the audio recording URL

getAudioUrl(interviewId: string): Promise<APIResponse<string | null>>

getVideoUrl

Get the video recording URL

getVideoUrl(interviewId: string): Promise<APIResponse<string | null>>

uploadRecording

Upload an audio or video recording

uploadRecording(interviewId: string, blob: Blob, type?: 'audio' | 'video'): Promise<APIResponse<{ url: string }>>

Results & Analysis

getResults

Get AI-generated analysis results

getResults(interviewId: string): Promise<APIResponse<InterviewResult>>

const { data: results } = await client.getResults('int_456');
console.log('Score:', results.overallScore);
console.log('Strengths:', results.strengths);
console.log('Recommendation:', results.recommendation);

generateResults

Generate or regenerate AI analysis

generateResults(interviewId: string, mode?: string): Promise<APIResponse<InterviewResult>>

// Generate results for a completed interview
const { data: results } = await client.generateResults('int_456', 'recruitment');

exportResults

Export results in various formats

exportResults(interviewId: string, format?: 'json' | 'pdf' | 'csv'): Promise<APIResponse<{ url: string }>>

Tokens & Invitations

createToken

Create an interview invitation token

createToken(projectId: string, data: CreateTokenInput): Promise<APIResponse<InterviewToken>>

const { data: token } = await client.createToken('proj_123', {
  inviteeEmail: 'candidate@example.com',
  inviteeName: 'Jane Smith',
  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
});

const interviewUrl = client.getInterviewUrl('proj_123', { token: token.token });
// Send interviewUrl to candidate

validateToken

Validate a token before starting interview

validateToken(token: string): Promise<APIResponse<TokenValidation>>

listTokens

List all tokens for a project

listTokens(projectId: string, filters?: TokenFilters): Promise<APIResponse<PaginatedResponse<InterviewToken>>>

renewToken

Renew an expired token

renewToken(tokenId: string): Promise<APIResponse<InterviewToken>>

Questions

listQuestions

List questions for a project

listQuestions(projectId: string): Promise<APIResponse<Question[]>>

const { data: questions } = await client.listQuestions('proj_123');
questions.forEach(q => {
  console.log(`[${q.type}] ${q.text}`);
});

createQuestion

Create a question

createQuestion(projectId: string, data: CreateQuestionInput): Promise<APIResponse<Question>>

await client.createQuestion('proj_123', {
  text: 'What is your experience with React?',
  type: 'open_ended',
  section: 'Technical',
  order: 1,
});

reorderQuestions

Reorder questions

reorderQuestions(projectId: string, questionIds: string[]): Promise<APIResponse<void>>

Agents (Multi-Agent)

listAgents

List agents for a multi-agent project

listAgents(projectId: string): Promise<APIResponse<Agent[]>>

createAgent

Create an AI agent

createAgent(projectId: string, data: CreateAgentInput): Promise<APIResponse<Agent>>

await client.createAgent('proj_123', {
  name: 'Technical Interviewer',
  role: 'interviewer',
  personality: 'Professional and thorough',
  systemInstruction: 'Focus on system design questions...',
});

React Components

Components and hooks reference

Examples

Code examples and recipes

API Reference