Ask the agent

The agent is the primary interface for the Flashpoint.AI survey platform. Describe what you want in plain language, and the agent plans the work, calls the right tools, and asks for confirmation before anything destructive.

How it works

You send a natural-language message. The agent reads it alongside the current survey context, decides which tools to call, executes them, and streams results back. The entire interaction runs over a single SSE (Server-Sent Events) connection.

Endpoint

POST /api/v1/agent/chat
Content-Type: application/json

{
  "message": "Create a 10-question NPS survey for our Q3 product launch",
  "conversation_id": null,
  "survey_id": null
}

Field	Type	Required	Description
message	string	Yes	Your instruction in natural language
conversation_id	UUID	No	Continue an existing conversation. Omit to start a new one.
survey_id	UUID	No	Scope the conversation to a specific survey

The response is an SSE stream. Each frame is a JSON event with a type field:

Event type	When it fires	Payload
conversation_started	Immediately	conversation_id, survey_id
thinking	Agent is reasoning	Internal reasoning text
text	Agent is composing a response	Streamed text chunks
tool_call	Agent invokes a tool	Tool name, arguments
tool_result	Tool returns	Tool output, artifacts
approval_needed	Destructive action pending	Description, tool call ID, preview
done	Turn complete	conversation_id, final state

The stream sends keepalive comments (: keepalive) every 15 seconds to prevent proxy timeouts.

---

Conversations

Every interaction is part of a persistent conversation thread. Conversations store full message history, so the agent has context from prior turns.

Operation	Endpoint	Method
List conversations	/api/v1/agent/conversations	GET
Create conversation	/api/v1/agent/conversations	POST
Get conversation detail	/api/v1/agent/conversations/{id}	GET
Rename / pin / archive	/api/v1/agent/conversations/{id}	PATCH
Delete conversation	/api/v1/agent/conversations/{id}	DELETE

Conversations can be filtered by survey_id and archived status. Titles are auto-generated from the first message but can be overridden via PATCH.

curl https://surveys.flashpoint.ai/api/v1/agent/conversations \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "title": "Q3 product launch NPS",
      "survey_id": "f8e7d6c5-...",
      "pinned": false,
      "archived": false,
      "created_at": "2026-05-26T09:00:00Z",
      "updated_at": "2026-05-26T09:15:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

---

Planning

When you give the agent a broad objective, it follows a structured planning discipline before building anything.

The planning sequence

1. Understand the objective. If the goal is vague, the agent asks 1-3 clarifying questions. It checks: What business decision will this inform? Who is the target audience? What topics should it cover? Any constraints on length or sample size?

2. Research the topic (optional). For unfamiliar domains, the agent calls research_market or research_audience to gather real-world context before planning. This produces grounded, insight-driven questions instead of generic boilerplate.

3. Present a plan. The agent calls plan_survey to produce a structured blueprint: survey name, objective, audience, blocks (sections), and question counts per block. This emits a plan card for your review — nothing is built yet.

4. Build on approval. Once you approve the plan, the agent creates the survey, adds blocks and questions, sets quotas, and runs a validation check (surveycheck) before reporting completion.

When planning is skipped

The agent builds directly without a plan when:

• You provided a complete list of questions
• You are editing an existing survey (add/update/delete individual questions)
• You asked for a single direct action ("add a question about income")
• You explicitly said "just build it" or "skip the plan"

---

Approval gates

Destructive actions pause for explicit user approval before executing. The agent describes what will happen, and the system renders an approval card in the chat.

Actions that require approval:

Action	What happens on approval
Publish survey	Survey goes live — respondents can access it
Pause / complete survey	Response collection stops
Delete survey	Soft-deleted (recoverable from admin tools)
Delete block or questions	Removed from the survey; skip logic may break
Send email invitations	Outbound emails sent to the recipient list
Resend invitations	Follow-up emails to non-completers
Set quotas	Quota configuration replaced

Approving or rejecting

POST /api/v1/agent/approve

{
  "conversation_id": "a1b2c3d4-...",
  "tool_call_id": "toolu_01X...",
  "approved": true,
  "args_override": null
}

Set approved to false to reject. The agent acknowledges the rejection and does not retry.

Argument overrides

For email-sending actions, you can edit the content before approving. Pass the modified fields in args_override:

{
  "conversation_id": "a1b2c3d4-...",
  "tool_call_id": "toolu_01X...",
  "approved": true,
  "args_override": {
    "email_template": {
      "subject": "Updated subject line",
      "body": "Revised email body with {{SURVEY_LINK}}",
      "cta_text": "Start the survey"
    }
  }
}

Only whitelisted fields are accepted per tool. Non-whitelisted keys are silently dropped.

Tool	Overridable fields
send_email_list	email_template
resend_email_list	email_template
send_platform_email	subject, body_text, body_html

Approval requests time out after 10 minutes if no decision is submitted.

---

Workflow examples

1. Build a survey from scratch

You: "Create a 10-question NPS survey for our Q3 product launch targeting existing customers"

Agent:

1. Asks one clarifying question about the product category
2. Calls research_market to gather context on product-launch satisfaction benchmarks
3. Calls plan_survey with a structured blueprint (screener block, main body, demographics)
4. Waits for your approval of the plan
5. On approval: create_survey -> add_block x3 -> add_question x10 -> surveycheck
6. Reports: "Survey created with 10 questions across 3 blocks. Validation passed with no issues."

2. Add a screener

You: "Add a screener that disqualifies anyone under 18"

Agent:

1. Checks the current survey for an existing screener block
2. Calls add_question with type number, validation min: 18, and skip logic to terminate under-18 respondents
3. Runs surveycheck to verify the termination logic resolves correctly
4. Reports: "Added age screener as S1. Respondents under 18 are routed to the termination page."

3. Translate a survey

You: "Translate this survey to Spanish"

Agent:

1. Reads the current survey context to identify all translatable content
2. Calls translate_survey with target language es
3. Reports: "Translation complete. All question text, option labels, and transition messages have been translated to Spanish."

4. Run synthetic respondents and analyze

You: "Run 30 synthetic respondents and give me the top 3 takeaways"

Agent:

1. Redirects to the orchestrator to run synthetic panel respondents through the survey
2. Once responses land, calls get_all_frequencies to pull distributions for every question
3. Calls get_analytics for the summary metrics
4. Composes a narrative summary with the three most notable findings
5. Reports the takeaways inline in the chat

5. Export and email results

You: "Export the results as a CSV and email it to team@company.com"

Agent:

1. Calls export_csv to generate the response data file and upload it to S3
2. Calls send_platform_email with the CSV as an attachment (pauses for approval)
3. On approval, sends the email
4. Reports: "CSV exported (847 responses, 42 columns). Email sent to team@company.com."

6. Analyze open-ended responses

You: "What do the open-ended responses to Q5 say?"

Agent:

1. Calls get_frequencies for Q5 to see the raw text responses
2. Reads through the responses and identifies themes
3. Composes a summary with theme counts and representative quotes
4. Reports: "142 responses to Q5. Top themes: ease of use (38%), pricing concerns (24%), feature requests (18%). Key quote: ..."

---

Collaboration

The agent supports inline comments on survey questions for team review workflows.

Tool	Description
add_comment	Attach a note to a specific question
list_comments	See all comments on the current survey
resolve_comment	Mark a comment as addressed

Example:

"Add a note on Q3: the wording is leading — needs to be more neutral"

The agent attaches the comment to Q3. Team members see it in the survey builder and can resolve it after making edits.

---

Research

The agent can conduct web research before building a survey, producing questions grounded in real market data rather than generic boilerplate.

Tool	Purpose
research_market	Industry trends, competitive landscape, category dynamics
research_audience	Demographics, behaviors, preferences for a target group

Example:

"Research EV ownership trends in the US, then build a survey exploring purchase drivers"

The agent gathers current data on EV adoption rates, top-selling models, and buyer demographics, then uses those findings to inform specific, relevant questions.

---

Redirects

When you ask for something outside the surveys domain, the agent hands the request off to the orchestrator — the parent system that routes between Flashpoint.AI products.

Redirected requests include:

• Creating or managing synthetic persona panels
• Running a panel through a survey
• Generating slide decks or presentations
• Listing or inspecting existing panels

The handoff is seamless. The agent calls redirect_to_orchestrator with your original request, and the orchestrator picks the right tool. You see the result in the same conversation.

---

Tool listing (debug)

To see all registered agent tools and their descriptions:

curl https://surveys.flashpoint.ai/api/v1/agent/tools \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns an array of tool objects with name, category, description, read_only, and destructive flags.