Build Emotion logo

Build Emotion

not featurefeel the difference
DirectoriesMarketing ChannelsTipsInspirationPricing
Get Started
LoginorRegister
DirectoriesMarketing ChannelsTipsInspirationPricingGet Started

API Documentation

Integrate Build Emotion with your tools and workflows. List projects, read project details, manage marketing activities, manage promotional texts, and manage project images programmatically.

  • On this page
  • Quick Start
  • Authentication
  • Base URL
  • Endpoints
    • Projects
      • GET List all
      • POST Create
      • GET Get one
      • PATCH Update
      • DEL Delete
    • Marketing Activities
      • GET List all
      • POST Create
      • GET Get one
      • PATCH Update
      • DEL Delete
    • Promotional Texts
      • GET List all
      • POST Create
      • GET Get one
      • PATCH Update
      • DEL Delete
    • Project Images
      • GET List all
      • POST Upload
      • GET Get one
      • PATCH Update
      • DEL Delete
  • Target Platforms
  • Categories
  • Error Handling
  • Code Examples
  • Best Practices

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-here

Use 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_here

5. 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_here
Method 2: X-API-Key Header
X-API-Key: sk_live_your_api_key_here
Method 3: Query Parameter (Fallback)
?api_key=sk_live_your_api_key_here
Get Your API Key
Visit your Settings page to generate an API key. Keep it secure and never share it publicly.

Base URL

https://buildemotion.com

All 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 name
  • emotions (optional) - Array of up to 3 emotion slugs
  • focusDescription (optional) - Short focus statement (5-10 words)
  • category (optional) - Business category
  • projectUrl (optional) - Public URL of the project
  • serviceDescription (optional) - One-paragraph description
  • targetCustomer (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, other
  • subcategory (required) - Subcategory string (see categories below)
  • description (required) - Description of the marketing activity
  • date (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 text
  • content (required) - Full promotional copy
  • targetPlatform (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 text
  • content — Full promotional copy
  • targetPlatform — 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"
}
GET/api/projects/{project_id}/images/

List all images for a project (up to 50 per project), ordered by display order.

Example Request:
GET https://buildemotion.com/api/projects/abc123/images/
Authorization: Bearer sk_live_your_api_key
Example Response:
{
  "projectImages": [
    {
      "id": "image_123",
      "projectId": "abc123",
      "imageUrl": "https://buildemotion.com/media/.../image.jpg",
      "thumbnailUrl": "https://buildemotion.com/media/.../thumb_image.jpg",
      "originalFilename": "screenshot.png",
      "fileSize": 245678,
      "order": 1,
      "created": "2026-01-15T10:00:00Z",
      "modified": "2026-01-15T10:00:00Z"
    }
  ],
  "totalCount": 1,
  "maxAllowed": 50
}
POST/api/projects/{project_id}/images/

Upload a new image for a project. Sent as multipart/form-data. Max 10MB per image, max 50 images per project. A 100x100 thumbnail is generated automatically.

Form Fields:
  • image (required) - The image file (max 10MB)
  • order (optional) - Display order; auto-assigned to the end if omitted
Example Request:
curl -X POST https://buildemotion.com/api/projects/abc123/images/ \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "[email protected]"
Example Response (201 Created):
{
  "projectImage": {
    "id": "image_123",
    "projectId": "abc123",
    "imageUrl": "https://buildemotion.com/media/.../image.jpg",
    "thumbnailUrl": "https://buildemotion.com/media/.../thumb_image.jpg",
    "originalFilename": "screenshot.png",
    "fileSize": 245678,
    "order": 1,
    "created": "2026-01-15T10:00:00Z",
    "modified": "2026-01-15T10:00:00Z"
  }
}
GET/api/projects/{project_id}/images/{image_id}/

Get details for a single project image. Use /download/ or /thumbnail/ suffixes on this path to fetch the raw image bytes.

Example Response:
{
  "projectImage": {
    "id": "image_123",
    "projectId": "abc123",
    "imageUrl": "https://buildemotion.com/media/.../image.jpg",
    "thumbnailUrl": "https://buildemotion.com/media/.../thumb_image.jpg",
    "originalFilename": "screenshot.png",
    "fileSize": 245678,
    "order": 1,
    "created": "2026-01-15T10:00:00Z",
    "modified": "2026-01-15T10:00:00Z"
  }
}
PATCHPUT/api/projects/{project_id}/images/{image_id}/

Update an image's display order. To replace the image file itself, delete it and upload a new one.

Request Body Fields:
  • order (required for PUT) - New display order (integer). Must be unique within the project.
Example Request:
PATCH https://buildemotion.com/api/projects/abc123/images/image_123/
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

{
  "order": 2
}
Example Response:
{
  "projectImage": { /* updated project image object */ }
}
DELETE/api/projects/{project_id}/images/{image_id}/

Delete a project image and its thumbnail.

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.

Get API KeyGo to Dashboard
Contact Us|Blog|Website Health Check|API Docs|Terms of Use|Privacy Policy|Customer Portal (Stripe)
Follow me on X
© 2026 - 2026 Build Emotion. All rights reserved.