Create Snippet

Overview

Creates a new snippet with optional variations, folder assignment, and tags. This endpoint allows you to create structured snippets programmatically. API Cost: 1 request

Code Examples

const axios = require('axios');

const API_KEY = process.env.SNIPPETS_AI_API_KEY;
const BASE_URL = 'https://www.getsnippets.ai/api/prompts';

async function createSnippet(snippetData) {
	try {
		const response = await axios.post(`${BASE_URL}/snippet`, snippetData, {
			headers: {
				Authorization: `Bearer ${API_KEY}`,
				'Content-Type': 'application/json',
			},
		});

		console.log('Created snippet ID:', response.data.data.snippetId);
		console.log('Remaining requests:', response.data.usage.remainingRequests);

		return response.data;
	} catch (error) {
		console.error('Error:', error.response?.data || error.message);
		throw error;
	}
}

// Basic snippet
const basicSnippet = {
	title: 'My API Snippet',
	content: {
		type: 'plaintext',
		content: "console.log('Hello, World!');",
	},
	teamId: 'your-team-id',
};

createSnippet(basicSnippet);

Real-World Use Case: Voice AI Integration

Here’s a complete example of creating prompts for a voice AI system (like VAPI):

async function createVoiceAgentPrompts(clientData) {
	const { clientName, industry, teamId, folderId } = clientData;

	// Create a snippet with multiple language variations
	const snippet = {
		title: `${clientName} - ${industry} Agent`,
		content: {
			type: 'plaintext',
			content: `You are a professional ${industry} assistant for ${clientName}. 
Your role is to help customers with inquiries, schedule appointments, 
and provide information about services. Be polite, professional, and helpful.`,
		},
		teamId: teamId,
		folderId: folderId,
		note: `Voice agent prompt for ${clientName}`,
		shortcut: `${clientName.toLowerCase()}_agent`,
		tagIds: [industryTagId, voiceAgentTagId],
		additionalVariations: [
			{
				content: {
					type: 'plaintext',
					content: `Eres un asistente profesional de ${industry} para ${clientName}.
Tu función es ayudar a los clientes con consultas, programar citas
y proporcionar información sobre servicios. Sé cortés, profesional y servicial.`,
				},
				variationName: 'Spanish Version',
			},
			{
				content: {
					type: 'plaintext',
					content: `You are handling after-hours calls for ${clientName}.
Inform customers of business hours and offer to schedule a callback
during office hours. Be understanding and helpful.`,
				},
				variationName: 'After Hours',
			},
		],
	};

	try {
		const response = await createSnippet(snippet);
		console.log(`✅ Created voice agent prompt: ${response.data.snippetId}`);
		console.log(`   Variations: ${response.data.metadata.totalVariations}`);

		return response.data.snippetId;
	} catch (error) {
		console.error(
			`❌ Failed to create prompt for ${clientName}:`,
			error.message
		);
		throw error;
	}
}

// Usage
createVoiceAgentPrompts({
	clientName: 'Dental Clinic ABC',
	industry: 'Healthcare',
	teamId: 'healthcare-team-id',
	folderId: 'dental-clients-folder-id',
});

Response Example

{
	"success": true,
	"data": {
		"snippetId": "550e8400-e29b-41d4-a716-446655440000"
	},
	"usage": {
		"remainingRequests": 99999
	},
	"metadata": {
		"totalVariations": 3,
		"tagsAttached": 2
	}
}

Validation Rules

title

string

required

Length: 1-200 characters Cannot be empty or exceed 200 characters.

content

object

required

Must include type and content fields.

{
  "type": "plaintext",
  "content": "Your content here"
}

teamId

string

required

Must be a valid team ID that your API key has access to.

note

string

Length: 0-5000 characters (optional)

shortcut

string

Length: 0-100 characters (optional)

folderId

string

Must be a valid folder ID in the same team (optional)

tagIds

array

Array of valid tag IDs from the same team (optional)

Batch Creation

To create multiple snippets, use the batch endpoint instead:

// Instead of this (inefficient):
for (const snippetData of snippets) {
	await createSnippet(snippetData); // N API calls + N * rate limit issues
}

// Do this (efficient):
await createSnippets({ snippets }); // 1 API call, N request cost

Error Handling

async function createSnippetSafe(snippetData) {
	// Pre-validate before API call
	if (!snippetData.title || snippetData.title.length === 0) {
		throw new Error('Title is required');
	}

	if (snippetData.title.length > 200) {
		throw new Error('Title cannot exceed 200 characters');
	}

	if (!snippetData.content) {
		throw new Error('Content is required');
	}

	if (!snippetData.teamId) {
		throw new Error('Team ID is required');
	}

	if (snippetData.note && snippetData.note.length > 5000) {
		throw new Error('Note cannot exceed 5000 characters');
	}

	try {
		return await createSnippet(snippetData);
	} catch (error) {
		const status = error.response?.status;
		const message = error.response?.data?.message;

		if (status === 400) {
			throw new Error(`Validation error: ${message}`);
		} else if (status === 403) {
			if (message?.includes('team')) {
				throw new Error('API key does not have access to this team');
			} else if (message?.includes('folder')) {
				throw new Error('Folder not found or not accessible');
			} else if (message?.includes('tag')) {
				throw new Error('One or more tags not found');
			}
		}

		throw error;
	}
}

Best Practices

Validate data before API calls to catch errors early and save on API costs

Use meaningful titles that make snippets easy to identify

Add notes to provide context for team members

Organize with folders and tags for better management

Create variations for different use cases (languages, contexts, etc.)

Always verify that folder IDs and tag IDs exist and belong to the correct team before creating snippets.

Update Snippet - Update an existing snippet
Create Multiple Snippets - Batch create snippets
Get Snippet - Retrieve a snippet
Create Folder - Create a folder first

Authorizations

Authorization

string

header

required

API key authentication using Bearer token. Include your API key in the Authorization header.

Body

application/json

title

string

required

Title of the snippet

Maximum string length: 200

Example:

"My API Snippet"

content

object

required

Show child attributes

teamId

string<uuid>

required

ID of the team this snippet belongs to

note

string

Optional note for the snippet

Maximum string length: 5000

shortcut

string

Optional keyboard shortcut

Maximum string length: 100

folderId

string<uuid>

Optional folder ID to organize the snippet

tagIds

string<uuid>[]

Optional array of tag IDs

additionalVariations

object[]

Optional additional variations of this snippet

Show child attributes

Response

Snippet created successfully

success

boolean

Example:

true

data

object

Show child attributes

usage

object

Show child attributes

metadata

object

Show child attributes

Getting Started

Snippets

Variations

Folders

Tags

Overview

Code Examples

Real-World Use Case: Voice AI Integration

Response Example

Validation Rules

Batch Creation

Error Handling

Best Practices

Authorizations

Body

Response

Getting Started

Snippets

Variations

Folders

Tags

Documentation Index

​Overview

​Code Examples

​Real-World Use Case: Voice AI Integration

​Response Example

​Validation Rules

​Batch Creation

​Error Handling

​Best Practices

​Related Endpoints

Authorizations

Body

Response

Overview

Code Examples

Real-World Use Case: Voice AI Integration

Response Example

Validation Rules

Batch Creation

Error Handling

Best Practices

Related Endpoints