Skip to main content
POST
/
snippet
Create a new snippet
curl --request POST \
  --url https://www.getsnippets.ai/api/prompts/snippet \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "My API Snippet",
  "content": {
    "type": "plaintext",
    "content": "Hello, world!"
  },
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "note": "<string>",
  "shortcut": "<string>",
  "folderId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "tagIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "additionalVariations": [
    {
      "content": {
        "type": "plaintext",
        "content": "Hello, world!"
      },
      "variationName": "Spanish Version"
    }
  ]
}'
{
  "success": true,
  "data": {
    "snippetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "usage": {
    "remainingRequests": 123
  },
  "metadata": {
    "totalVariations": 123,
    "tagsAttached": 123
  }
}

​
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.

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 length: 200
Example:

"My API Snippet"

​
content
object
required
​
teamId
string<uuid>
required

ID of the team this snippet belongs to

​
note
string

Optional note for the snippet

Maximum length: 5000
​
shortcut
string

Optional keyboard shortcut

Maximum 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

Response

Snippet created successfully

​
success
boolean
Example:

true

​
data
object
​
usage
object
​
metadata
object