API Endpoints

Individual endpoints for fine-grained control over the message generation workflow.

Required Headers

All endpoints require the following headers:

Header	Type	Description
`x-access-key`	UUID	Your API key
`x-idempotency-key`	UUID	Unique key to prevent duplicate processing
`x-user-id`	UUID	The connected user’s ID

API Workflow

The Warm AI message generation pipeline follows this sequence:

User Research — Retrieve the user’s profile, products, and ICPs
Prospect Research — Analyse the prospect’s LinkedIn profile
Research Summary — Generate strategic messaging insights
Message Generation — Create the personalised outreach message
Send Message — Deliver or schedule the message

You can use the End-to-End Endpoint to execute steps 1–4 in a single call. Use these individual endpoints when you need more control over the workflow.

User Research

Retrieve the authenticated user’s profile data, including products and ICPs.

Method: POST Path: /api-user-research

Request Body:


// No body required

Response Fields:

Field	Type	Description
`user_data`	object	The user’s full profile data
`user_data.profile`	object	User profile details
`user_data.product_ids`	array	List of product UUIDs associated with the user
`user_data.icp_ids`	array	List of ICP UUIDs associated with the user

Example Response:


{
  "user_data": {
    "profile": {
      "id": "user-uuid",
      "full_name": "Jane Smith",
      "headline": "VP of Sales at Acme Corp",
      "messaging_style": "relationship_builder"
    },
    "product_ids": [
      "product-uuid-1",
      "product-uuid-2"
    ],
    "icp_ids": [
      "icp-uuid-1"
    ]
  }
}

Prospect Research

Analyse a prospect’s LinkedIn profile to gather context for message generation.

Method: POST Path: /api-prospect-research

Request Body:


{
  "prospect_url": "https://www.linkedin.com/in/johndoe"
}

Field	Type	Required	Description
`prospect_url`	string	Yes	LinkedIn profile URL of the prospect

Response Fields:

Field	Type	Description
`research_id`	string	Unique identifier for this research session
`prospect_research`	object	Parsed profile data and insights
`network_distance`	number	Degree of connection (1st, 2nd, 3rd)

Example Response:


{
  "research_id": "research-uuid",
  "prospect_research": {
    "name": "John Doe",
    "headline": "CTO at TechStartup",
    "company": "TechStartup",
    "industry": "Software Development",
    "recent_posts": [
      "Excited to announce our Series B..."
    ],
    "mutual_connections": 12
  },
  "network_distance": 2
}

Research Summary

Generate a strategic research summary with messaging recommendations based on the prospect research.

Method: POST Path: /api-research-summary

Request Body:


{
  "research_id": "research-uuid"
}

Field	Type	Required	Description
`research_id`	string	Yes	The research ID returned from Prospect Research

Response Fields:

Field	Type	Description
`message_id`	string	Unique identifier for the message pipeline
`research_summary`	object	Strategic messaging insights
`research_summary.recommended_focus`	string	Suggested topic to lead with
`research_summary.prospect_insights`	array	Key observations about the prospect
`research_summary.messaging_strategy`	string	Recommended approach for the message
`research_summary.product_alignment`	string	How your product fits the prospect’s needs
`research_summary.should_send_message`	boolean	Whether Warm AI recommends sending a message

Example Response:


{
  "message_id": "msg-uuid",
  "research_summary": {
    "recommended_focus": "Their recent Series B and scaling challenges",
    "prospect_insights": [
      "CTO at a fast-growing startup",
      "Recently raised Series B funding",
      "Hiring aggressively for engineering roles"
    ],
    "messaging_strategy": "Reference their growth trajectory and position your product as a scaling solution",
    "product_alignment": "Strong fit — they are scaling the exact function your tool automates",
    "should_send_message": true
  }
}

If should_send_message is false, Warm AI has determined the prospect is not a strong fit. You can still proceed with message generation, but results may be less effective.

Message Generation

Generate a personalised outreach message using the research summary and user profile.

Method: POST Path: /api-message-generate

Request Body:


{
  "message_id": "msg-uuid",
  "product_id": "product-uuid",
  "template": {
    "message_length": "short",
    "message_tone": "casual",
    "reference_posts": true,
    "lead_with_question": false,
    "mention_free_trial": true,
    "additional_instructions": "Mention their recent Series B announcement"
  }
}

Field	Type	Required	Description
`message_id`	string	Yes	The message ID returned from Research Summary
`product_id`	string	No	Specific product to reference
`template`	object	No	Override default message generation settings
`template.message_length`	string	No	`"short"`, `"medium"`, or `"long"`
`template.message_tone`	string	No	`"casual"`, `"professional"`, or `"formal"`
`template.reference_posts`	boolean	No	Whether to reference the prospect’s recent posts
`template.lead_with_question`	boolean	No	Whether to open with a question
`template.mention_free_trial`	boolean	No	Whether to mention a free trial offer
`template.additional_instructions`	string	No	Free-text instructions for the AI

Response Fields:

Field	Type	Description
`generated_message`	string	The full generated message text
`message_type`	string	Type of message (e.g. `connection_request`, `inmail`)
`message_metadata`	object	Metadata about the generated message

Example Response:


{
  "generated_message": "Hi John, congrats on the Series B — scaling from 20 to 80 engineers is no small feat. Curious how you're thinking about automating outbound as the team grows?",
  "message_type": "connection_request",
  "message_metadata": {
    "word_count": 32,
    "character_count": 198,
    "tone": "casual",
    "references_posts": true
  }
}

Send Message

Deliver or schedule a generated message to the prospect.

Method: POST Path: /api-send

Request Body:


{
  "message_id": "msg-uuid",
  "edited_message": "Hi John, congrats on the Series B! Would love to chat about how we help teams scale outbound."
}

Field	Type	Required	Description
`message_id`	string	Yes	The message ID from the generation step
`edited_message`	string	No	An edited version of the message to send instead of the generated one

Response Fields:

Field	Type	Description
`status`	string	`"scheduled"` or `"sent"`
`scheduled_at`	string	ISO 8601 timestamp if scheduled
`sent_at`	string	ISO 8601 timestamp if sent immediately

Example Response:


{
  "status": "scheduled",
  "scheduled_at": "2026-03-20T09:00:00Z"
}

Knowledge Action

Manage entries in the user’s knowledge base. Supports multiple action types.

Method: POST Path: /api-knowledge-action

Actions:

Action	Description
`add_entry`	Add a new entry to the knowledge base
`list_entries`	List all entries in the knowledge base
`approve_entry`	Approve a pending entry
`update_entry`	Update an existing entry
`delete_entry`	Soft-delete an entry
`restore_entry`	Restore a soft-deleted entry

Request Body — add_entry:


{
  "action": "add_entry",
  "entry": {
    "title": "Competitor Pricing Update",
    "content": "Competitor X reduced pricing by 15% in Q1 2026."
  }
}

Request Body — list_entries:


{
  "action": "list_entries"
}

Request Body — approve_entry:


{
  "action": "approve_entry",
  "entry_id": "entry-uuid"
}

Request Body — update_entry:


{
  "action": "update_entry",
  "entry_id": "entry-uuid",
  "entry": {
    "title": "Updated Title",
    "content": "Updated content for the knowledge base entry."
  }
}

Request Body — delete_entry:


{
  "action": "delete_entry",
  "entry_id": "entry-uuid"
}

Request Body — restore_entry:


{
  "action": "restore_entry",
  "entry_id": "entry-uuid"
}

Example Response — list_entries:


{
  "entries": [
    {
      "id": "entry-uuid",
      "title": "Competitor Pricing Update",
      "content": "Competitor X reduced pricing by 15% in Q1 2026.",
      "status": "approved",
      "created_at": "2026-03-15T14:30:00Z",
      "updated_at": "2026-03-15T14:30:00Z"
    }
  ]
}

Example Response — add_entry:


{
  "entry_id": "entry-uuid",
  "status": "pending",
  "message": "Entry added successfully. Awaiting approval."
}