Prep Questions API

Manages AI-powered interview preparation questions that are asked during the booking process.

Base Path: /api/prep-questions

Authentication: All endpoints require Bearer token.

Endpoints

Method	Path	Auth	Description
GET	/	Yes	List prep questions for podcast
POST	/	Yes	Create prep question
PUT	/:id	Yes	Update prep question
DELETE	/:id	Yes	Delete prep question

List Prep Questions

Retrieves all preparation questions for a podcast.

GET /api/prep-questions?podcast_id={id}

Query Parameters:

Parameter	Type	Required	Description
podcast_id	UUID	Yes	Podcast to list questions for
is_active	boolean	No	Filter by active status

Response:

{
	"questions": [
		{
			"id": "uuid",
			"podcast_id": "uuid",
			"question": "What specific topics or expertise would you like to discuss?",
			"description": "Help us prepare relevant questions for our conversation",
			"question_type": "textarea",
			"is_required": true,
			"is_active": true,
			"display_order": 0,
			"ai_context": "Use this to generate interview questions about the guest's expertise",
			"created_at": "2025-01-07T10:00:00Z",
			"updated_at": "2025-01-07T10:00:00Z"
		},
		{
			"id": "uuid",
			"podcast_id": "uuid",
			"question": "Do you have any upcoming projects or announcements?",
			"description": "We can highlight these during the episode",
			"question_type": "textarea",
			"is_required": false,
			"is_active": true,
			"display_order": 1,
			"ai_context": "Include in show notes and social media promotion",
			"created_at": "2025-01-07T10:00:00Z",
			"updated_at": "2025-01-07T10:00:00Z"
		}
	],
	"total": 2
}

Create Prep Question

Creates a new preparation question. Requires owner or admin role.

POST /api/prep-questions

Request Body:

{
	"podcast_id": "uuid",
	"question": "What specific topics would you like to discuss?",
	"description": "Help us prepare relevant questions",
	"question_type": "textarea",
	"is_required": true,
	"is_active": true,
	"display_order": 0,
	"ai_context": "Use to generate interview talking points"
}

Fields:

Field	Type	Required	Description
podcast_id	UUID	Yes	Podcast this question belongs to
question	string	Yes	The question text
description	string	No	Helper text for guests
question_type	enum	Yes	Input type: text, textarea, dropdown
is_required	boolean	No	Whether answer is mandatory (default: false)
is_active	boolean	No	Whether to show on booking form (default: true)
display_order	number	No	Sort order (default: 0)
ai_context	string	No	Instructions for AI processing
options	string[]	No	Options for dropdown type

Response 201 Created:

{
  "question": {
    "id": "uuid",
    "podcast_id": "uuid",
    "question": "What specific topics would you like to discuss?",
    ...
  }
}

Update Prep Question

Updates an existing preparation question. Requires owner or admin role.

PUT /api/prep-questions/:id

Request Body: Same as create (all fields optional).

Response:

{
  "question": {
    "id": "uuid",
    ...updated fields...
  }
}

Delete Prep Question

Deletes a preparation question. Requires owner or admin role.

DELETE /api/prep-questions/:id

Response:

{
	"success": true
}

Question Types

Type	Description	Use Case
text	Single-line text input	Short answers, names, links
textarea	Multi-line text area	Long-form responses, expertise details
dropdown	Select from options	Predefined choices, categories

Dropdown Options

For dropdown type, provide options array:

{
	"question": "What is your podcast experience level?",
	"question_type": "dropdown",
	"options": ["First time", "Some experience", "Regular podcaster"]
}

AI Integration

The ai_context field provides instructions for AI processing of guest responses:

{
	"question": "Tell us about your background and expertise",
	"ai_context": "Extract key topics for interview questions. Identify areas of expertise to probe deeper. Note any unique perspectives or experiences."
}

AI Processing Flow

Data Model

interface PrepQuestion {
	id: string;
	podcast_id: string;
	question: string;
	description: string | null;
	question_type: 'text' | 'textarea' | 'dropdown';
	options: string[] | null; // For dropdown type
	is_required: boolean;
	is_active: boolean;
	display_order: number;
	ai_context: string | null;
	created_at: string;
	updated_at: string;
}

Booking Form Integration

Active prep questions are included in the booking form:

// Get questions for booking form
const { data: questions } = await supabase
	.from('prep_questions')
	.select('*')
	.eq('podcast_id', podcastId)
	.eq('is_active', true)
	.order('display_order');

// Guest responses stored in booking
const booking = {
	...bookingData,
	custom_responses: {
		[question.id]: guestAnswer
		// ... more responses
	}
};

TypeScript Client Usage

import { createApiClient } from '$api/client';

const client = createApiClient(fetch);

// List questions
const listRes = await client.api['prep-questions'].$get(
	{ query: { podcast_id: 'uuid' } },
	{ headers: { Authorization: `Bearer ${token}` } }
);

// Create question
const createRes = await client.api['prep-questions'].$post(
	{
		json: {
			podcast_id: 'uuid',
			question: 'What topics would you like to discuss?',
			question_type: 'textarea',
			is_required: true,
			ai_context: 'Generate interview talking points'
		}
	},
	{
		headers: { Authorization: `Bearer ${token}` }
	}
);

// Update question
const updateRes = await client.api['prep-questions'][':id'].$put(
	{
		param: { id: 'question-uuid' },
		json: { is_active: false }
	},
	{
		headers: { Authorization: `Bearer ${token}` }
	}
);

// Delete question
const deleteRes = await client.api['prep-questions'][':id'].$delete(
	{ param: { id: 'question-uuid' } },
	{ headers: { Authorization: `Bearer ${token}` } }
);

Related

• Booking Links API - Custom fields on booking links
• Bookings API - Where responses are stored
• Automation Engine - AI-powered workflows