API Documentation
Integrate Build Emotion with your tools and workflows. List projects, read project details, manage marketing activities, and manage promotional texts programmatically.
Quick Start
1. Get Your API Key
Go to your Settings page and generate an API key.
2. List Your Projects
Fetch all projects for your account to get project IDs and context (focus, target customer, emotions):
curl https://buildemotion.com/api/projects/ \ -H "Authorization: Bearer sk_live_your_api_key"
3. Get Your Project ID
The project ID is returned by GET /api/projects/ or found in your project URL:
https://buildemotion.com/user/projects/your-project-id-hereUse the project id field in all project-scoped API requests.
4. Authenticate Requests
Include your API key in the Authorization header (recommended) or X-API-Key header:
Authorization: Bearer sk_live_your_api_key_here— or —
X-API-Key: sk_live_your_api_key_here5. Make Your First Request
Create a marketing activity:
curl -X POST https://buildemotion.com/api/projects/{project_id}/marketing-activities/ \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature launch",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost"
}'Authentication
All API requests require authentication using an API key. You can authenticate using any of the following methods:
Method 1: Authorization Header (Recommended)
Authorization: Bearer sk_live_your_api_key_hereMethod 2: X-API-Key Header
X-API-Key: sk_live_your_api_key_hereMethod 3: Query Parameter (Fallback)
?api_key=sk_live_your_api_key_hereGet Your API Key
Visit your Settings page to generate an API key. Keep it secure and never share it publicly.
Base URL
https://buildemotion.comAll API endpoints are relative to this base URL.
Endpoints
GET
/api/projects/List all projects for the authenticated user. Returns project metadata including emotions, focus, service description, and target customer profile.
Example Request:
GET https://buildemotion.com/api/projects/ Authorization: Bearer sk_live_your_api_key
Example Response:
{
"projects": [
{
"id": "abc123",
"name": "My SaaS",
"emotions": ["trust", "excitement"],
"focusDescription": "Help founders track marketing consistently",
"category": "Technology",
"projectUrl": "https://example.com",
"serviceDescription": "A marketing activity tracker for indie hackers.",
"faviconUrl": "https://example.com/favicon.ico",
"orderNumber": 1,
"isPublic": false,
"targetCustomer": {
"demographics": "Solo founders, indie hackers",
"painPoints": "Inconsistent marketing, no visibility",
"desires": "Stay consistent and see progress",
"behaviors": "Build in public, post on X",
"channels": "Twitter/X, directories, email",
"searchTiming": "When launching or struggling with marketing",
"currentSolution": "Spreadsheets, memory",
"purchaseBlockers": "Budget, time to set up"
},
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
]
}GET
/api/projects/{project_id}/Get full details for a single project, including focus description, service description, emotions, category, and target customer fields.
Example Request:
GET https://buildemotion.com/api/projects/abc123/ Authorization: Bearer sk_live_your_api_key
Example Response:
{
"project": {
"id": "abc123",
"name": "My SaaS",
"emotions": ["trust", "excitement"],
"focusDescription": "Help founders track marketing consistently",
"category": "Technology",
"projectUrl": "https://example.com",
"serviceDescription": "A marketing activity tracker for indie hackers.",
"faviconUrl": "https://example.com/favicon.ico",
"orderNumber": 1,
"isPublic": false,
"targetCustomer": {
"demographics": "Solo founders, indie hackers",
"painPoints": "Inconsistent marketing, no visibility",
"desires": "Stay consistent and see progress",
"behaviors": "Build in public, post on X",
"channels": "Twitter/X, directories, email",
"searchTiming": "When launching or struggling with marketing",
"currentSolution": "Spreadsheets, memory",
"purchaseBlockers": "Budget, time to set up"
},
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
}POST
/api/projects/Create a new project.
Request Body Fields:
name(required) - Project nameemotions(optional) - Array of up to 3 emotion slugsfocusDescription(optional) - Short focus statement (5-10 words)category(optional) - Business categoryprojectUrl(optional) - Public URL of the projectserviceDescription(optional) - One-paragraph descriptiontargetCustomer(optional) - Object with demographics, painPoints, desires, behaviors, channels, searchTiming, currentSolution, purchaseBlockers
Example Request:
POST https://buildemotion.com/api/projects/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"name": "My SaaS",
"emotions": ["trust", "excitement"],
"focusDescription": "Help founders track marketing consistently",
"category": "Technology",
"projectUrl": "https://example.com",
"serviceDescription": "A marketing activity tracker for indie hackers.",
"targetCustomer": {
"demographics": "Solo founders, indie hackers",
"painPoints": "Inconsistent marketing, no visibility"
}
}Example Response (201 Created):
{
"project": {
"id": "abc123",
"name": "My SaaS",
"emotions": ["trust", "excitement"],
"focusDescription": "Help founders track marketing consistently",
"category": "Technology",
"projectUrl": "https://example.com",
"serviceDescription": "A marketing activity tracker for indie hackers.",
"targetCustomer": { "demographics": "Solo founders, indie hackers", "painPoints": "Inconsistent marketing, no visibility" },
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
}PATCHPUT
/api/projects/{project_id}/Update a project. PATCH supports partial updates, PUT requires all fields.
Example Request:
PATCH https://buildemotion.com/api/projects/abc123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"focusDescription": "Updated focus statement",
"emotions": ["trust", "confidence"]
}Example Response:
{
"project": { /* updated project object */ }
}DELETE
/api/projects/{project_id}/Delete a project and all of its nested data.
Example Response:
{
"status": "deleted"
}GET
/api/projects/{project_id}/marketing-activities/List all marketing activities for a project. Supports optional date filtering.
Query Parameters:
from_date(optional) - Filter activities from this date (YYYY-MM-DD)to_date(optional) - Filter activities until this date (YYYY-MM-DD)
Example Request:
GET https://buildemotion.com/api/projects/abc123/marketing-activities/?from_date=2026-01-01&to_date=2026-01-31 Authorization: Bearer sk_live_your_api_key
Example Response:
{
"marketingActivities": [
{
"id": "activity_123",
"projectId": "abc123",
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost",
"created": "2026-01-15T14:30:00Z",
"modified": "2026-01-15T14:30:00Z"
}
]
}POST
/api/projects/{project_id}/marketing-activities/Create a new marketing activity.
Request Body (Required Fields):
category(required) - One of: email, directory, social, seo, influencers, paid, offline, othersubcategory(required) - Subcategory string (see categories below)description(required) - Description of the marketing activitydate(required) - Date in YYYY-MM-DD format
Request Body (Optional Fields):
time(optional) - Time in HH:MM format (24-hour)link(optional) - URL related to the activity
Example Request:
POST https://buildemotion.com/api/projects/abc123/marketing-activities/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature launch",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost"
}Example Response (201 Created):
{
"marketingActivity": {
"id": "activity_123",
"projectId": "abc123",
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature launch",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost",
"created": "2026-01-15T14:30:00Z",
"modified": "2026-01-15T14:30:00Z"
}
}GET
/api/projects/{project_id}/marketing-activities/{activity_id}/Get a specific marketing activity by ID.
Example Response:
{
"marketingActivity": {
"id": "activity_123",
"projectId": "abc123",
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost",
"created": "2026-01-15T14:30:00Z",
"modified": "2026-01-15T14:30:00Z"
}
}PATCHPUT
/api/projects/{project_id}/marketing-activities/{activity_id}/Update a marketing activity. PATCH supports partial updates, PUT requires all fields.
Example Request:
PATCH https://buildemotion.com/api/projects/abc123/marketing-activities/activity_123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"description": "Updated description",
"link": "https://twitter.com/updatedpost"
}DELETE
/api/projects/{project_id}/marketing-activities/{activity_id}/Delete a marketing activity.
Example Response:
{
"status": "deleted"
}GET
/api/projects/{project_id}/promotional-texts/List all promotional texts for a project (headlines, content, and target platform).
Example Request:
GET https://buildemotion.com/api/projects/abc123/promotional-texts/ Authorization: Bearer sk_live_your_api_key
Example Response:
{
"promotionalTexts": [
{
"id": "text_123",
"projectId": "abc123",
"headline": "Launch on Product Hunt",
"content": "We help indie hackers track every marketing action...",
"targetPlatform": "Directory",
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
]
}POST
/api/projects/{project_id}/promotional-texts/Create a new promotional text for a project.
Request Body (Required Fields):
headline(required) - Short title for the promotional textcontent(required) - Full promotional copytargetPlatform(required) - Platform label (see Target Platforms below)
Example Request:
POST https://buildemotion.com/api/projects/abc123/promotional-texts/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"headline": "Launch on Product Hunt",
"content": "We help indie hackers track every marketing action...",
"targetPlatform": "Directory"
}Example Response (201 Created):
{
"promotionalText": {
"id": "text_123",
"projectId": "abc123",
"headline": "Launch on Product Hunt",
"content": "We help indie hackers track every marketing action...",
"targetPlatform": "Directory",
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
}GET
/api/projects/{project_id}/promotional-texts/{promotional_text_id}/Get a specific promotional text by ID.
Example Response:
{
"promotionalText": {
"id": "text_123",
"projectId": "abc123",
"headline": "Launch on Product Hunt",
"content": "We help indie hackers track every marketing action...",
"targetPlatform": "Directory",
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-15T10:00:00Z"
}
}PATCHPUT
/api/projects/{project_id}/promotional-texts/{promotional_text_id}/Update a promotional text. PATCH supports partial updates, PUT requires all fields.
Request Body Fields:
headline— Short title for the promotional textcontent— Full promotional copytargetPlatform— Platform label (see Target Platforms below)
Example Request:
PATCH https://buildemotion.com/api/projects/abc123/promotional-texts/text_123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
{
"headline": "Updated launch headline",
"content": "Updated promotional copy for directories."
}Example Response:
{
"promotionalText": {
"id": "text_123",
"projectId": "abc123",
"headline": "Updated launch headline",
"content": "Updated promotional copy for directories.",
"targetPlatform": "Directory",
"created": "2026-01-15T10:00:00Z",
"modified": "2026-01-16T09:00:00Z"
}
}DELETE
/api/projects/{project_id}/promotional-texts/{promotional_text_id}/Delete a promotional text.
Example Response:
{
"status": "deleted"
}Target Platforms
Use these values for targetPlatform when updating promotional texts. Custom platform names are also accepted.
DirectoryEmailSocial MediaAdvertisementCommentReleaseStoresOther
Categories & Subcategories
Use these category and subcategory values when creating marketing activities:
📧Emailemail
Subcategories:
Cold EmailNewsletterEmail CampaignFollow-upOther Email
📁Directoriesdirectory
Subcategories:
BetaListProduct HuntIndie HackersHacker NewsRedditOther Directory
📱Social Postsocial
Subcategories:
Twitter/XRedditLinkedInFacebookInstagramTikTokYouTubeOther Social
🔍SEOseo
Subcategories:
Blog ArticlepSEOGuest PostBacklinksContent UpdateComparison PageUse-case PageFAQ PageFree Tool PageFree Course PageOther SEO
⭐Influencersinfluencers
Subcategories:
Micro-influencerMacro-influencerCelebrityIndustry ExpertBrand AmbassadorSponsored PostProduct ReviewUnboxingPodcastOther Influencer
💰Paid Adspaid
Subcategories:
Google AdsFacebook AdsInstagram AdsLinkedIn AdsTwitter/X AdsYouTube AdsTikTok AdsDisplay AdsSearch AdsRetargetingOther Paid AdsSponsorshipOther Paid
🌍Offlineoffline
Subcategories:
BillboardsPrint AdsTrade ShowsNetworking EventsDirect MailOther Offline
🤝Partnershippartnership
Subcategories:
Affiliate ProgramPartner ProgramReseller ProgramCo-marketingOther Partnership
✨Otherother
Subcategories:
PartnershipEventPRInternal Cross PromotionOther
Error Handling
The API uses standard HTTP status codes. Error responses include a message in the response body:
401 Unauthorized
{
"error": "Authentication required. Provide valid API key in Authorization header (Bearer sk_live_...) or user session."
}400 Bad Request
{
"error": "Category is required"
}404 Not Found
{
"error": "Project not found"
}Code Examples
JavaScript / Node.js
const createMarketingActivity = async (projectId, activityData) => {
const response = await fetch(
`https://buildemotion.com/api/projects/${projectId}/marketing-activities/`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
category: 'social',
subcategory: 'Twitter/X',
description: 'Posted about new feature',
date: '2026-01-15',
time: '14:30',
link: 'https://twitter.com/yourpost'
})
}
);
return await response.json();
};Python
import requests
API_KEY = "sk_live_your_api_key"
BASE_URL = "https://buildemotion.com"
def create_marketing_activity(project_id, activity_data):
url = f"{BASE_URL}/api/projects/{project_id}/marketing-activities/"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(url, json=activity_data, headers=headers)
return response.json()
# Example usage
activity = {
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost"
}
result = create_marketing_activity("your-project-id", activity)cURL
curl -X POST https://buildemotion.com/api/projects/abc123/marketing-activities/ \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"category": "social",
"subcategory": "Twitter/X",
"description": "Posted about new feature",
"date": "2026-01-15",
"time": "14:30",
"link": "https://twitter.com/yourpost"
}'Best Practices
Keep Your API Key Secure
Never commit your API key to version control or expose it in client-side code.
Use Date Filtering
When listing activities, use
from_date and to_date parameters to reduce response size and improve performance.Handle Errors Gracefully
Always check response status codes and handle errors appropriately in your application.
Validate Data Before Sending
Ensure dates are in YYYY-MM-DD format and times are in HH:MM format (24-hour) before making requests.
Ready to Get Started?
Get your API key and start integrating Build Emotion into your workflow.