Submit Feedback via API - Squad AI Documentation

Overview

The Squad API allows you to programmatically submit user feedback, support tickets, survey responses, or any text-based insights directly into your Squad workspace. This enables you to capture feedback from custom sources and integrate Squad’s analysis into your existing workflows.

Use cases: Custom feedback forms, internal tools, mobile apps, chatbots, support systems, or any application where users provide feedback.

Benefits

Real-time feedback ingestion: Push feedback to Squad as it happens, ensuring your product insights are always up-to-date. Source attribution: Tag feedback with custom source identifiers to track which channels generate the most valuable insights. Automated discovery: Squad’s AI automatically analyzes submitted feedback, clusters themes, and surfaces actionable opportunities without manual review.

Quick start

The fastest way to get started is by pasting this prompt into claude code or your favorite AI coding assistant to automatically generate a plan for integrating feedback capturing into your application:

prompt

I want you to visit and understand https://docs.meetsquad.ai/guides/squad-api

I then want you to understand where we might integrate this feedback capturing to this application. I want to capture high quality user feedback. Follow the best practices as outlined in the documentation. If you need to create a feedback form respect the components and patterns in the codebase.

Create a plan and confirm it with me before you implement anything.

Two approaches

Node.js Client Library

Pre-built TypeScript/Node.js package with type safety and error handling

Direct API Integration

Build your own client in any language using our REST API

Prerequisites

Get your API key

Navigate to Workspace dropdown → Settings in Squad
Find the API Access section
Click Generate API Key or copy your existing key

API keys are workspace-scoped. Each workspace has its own unique key.

Choose your integration approach

Node.js/TypeScript projects: Use the npm package for fastest setup
Other languages: Use the REST API directly

Using the npm package

The official @squadai/feedback-client package provides a simple, type-safe way to submit feedback from Node.js applications.

Installation

npm install @squadai/feedback-client

yarn add @squadai/feedback-client

pnpm add @squadai/feedback-client

Quick start

Set your API key

Add your Squad API key to your environment variables:

.env

SQUAD_API_KEY=your-api-key-here

The package automatically reads from process.env.SQUAD_API_KEY for security. Never hardcode API keys in your source code.

Submit feedback

import { submitFeedback } from "@squadai/feedback-client";

const result = await submitFeedback("The checkout process is too complicated", { source: "CHECKOUT_COMPLETE_FEEDBACK_PAGE" });

if (result.success) {
  console.log("✓ Feedback submitted to workspace:", result.data.data.workspaceId);
} else {
  console.error("✗ Error:", result.error.message);
}

That’s it! Squad will automatically analyze the feedback and integrate it into your insights.

Common patterns

Web application
Chat integration
Mobile backend

import express from "express";
import { submitFeedback } from "@squadai/feedback-client";

const app = express();
app.use(express.json());

app.post("/api/feedback", async (req, res) => {
  const { feedback, userEmail } = req.body;

  if (!feedback) {
    return res.status(400).json({ error: "Feedback is required" });
  }

  // Optionally include user context in the feedback
  const feedbackText = `${feedback}\n\nSubmitted by: ${userEmail}`;

  const result = await submitFeedback(feedbackText, {
    source: "WEB_FORM"
  });

  if (result.success) {
    res.json({ message: "Thank you for your feedback!" });
  } else {
    res.status(500).json({ error: "Failed to submit feedback" });
  }
});

app.listen(3000);

import { submitFeedback } from "@squadai/feedback-client";

// When user provides feedback in chat
async function handleFeedbackCommand(message: string, userId: string) {
  const feedbackWithContext = `${message}\n\nUser ID: ${userId}`;

  const result = await submitFeedback(feedbackWithContext, {
    source: "SLACK_BOT"
  });

  return result.success
    ? "Thanks! Your feedback has been recorded."
    : "Sorry, failed to record feedback. Please try again.";
}

import { submitFeedback } from "@squadai/feedback-client";

// API endpoint called from mobile app
export async function submitAppFeedback(
  feedback: string,
  metadata: { appVersion: string; platform: string }
) {
  const enrichedFeedback = `${feedback}\n\nApp: ${metadata.appVersion} (${metadata.platform})`;

  const result = await submitFeedback(enrichedFeedback, {
    source: "MOBILE_APP"
  });

  return {
    success: result.success,
    error: result.success ? null : result.error.message
  };
}

Source naming

The source parameter helps you track which channels generate feedback. It must follow strict formatting:

// ✅ Uppercase letters and underscores only
const validSources = [
  "WEB_FORM",
  "MOBILE_APP",
  "SLACK_BOT",
  "SUPPORT_TICKET",
  "USER_INTERVIEW",
  "API_INTEGRATION",
  "SURVEY_IMPORT"
];

await submitFeedback("Great feature!", {
  source: "WEB_FORM" // ✅ Correct
});

// ❌ These will throw an error
await submitFeedback("Great feature!", {
  source: "web-form" // ❌ Lowercase and hyphens
});

await submitFeedback("Great feature!", {
  source: "WebForm" // ❌ Mixed case
});

await submitFeedback("Great feature!", {
  source: "WEB FORM" // ❌ Spaces not allowed
});

await submitFeedback("Great feature!", {
  source: "WEB_FORM_123" // ❌ Numbers not allowed
});

Pro tip: Use descriptive source names that match your analytics. For example, MOBILE_APP vs WEB_APP lets you compare feedback across platforms in Squad Insights.

Using the REST API

For non-Node.js projects or custom implementations, use Squad’s REST API directly. You can access the complete openAPI spec here: OpenAPI Spec

Authentication

All API requests require an API key in the Authorization header:

Authorization: your-api-key-here

Endpoints

Basic submission
With source

POST /v1/data-ingressSubmit feedback without source attribution.

cURL

curl -X POST https://api.meetsquad.ai/v1/data-ingress \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: text/plain" \
  -d "The mobile app crashes when I try to upload photos"

Python

import requests

api_key = "your-api-key-here"
feedback = "The mobile app crashes when I try to upload photos"

response = requests.post(
    "https://api.meetsquad.ai/v1/data-ingress",
    headers={
        "Authorization": api_key,
        "Content-Type": "text/plain"
    },
    data=feedback
)

if response.status_code == 201:
    data = response.json()
    print(f"✓ Feedback submitted to workspace: {data['data']['workspaceId']}")
else:
    print(f"✗ Error: {response.status_code}")

JavaScript (fetch)

const apiKey = "your-api-key-here";
const feedback = "The mobile app crashes when I try to upload photos";

const response = await fetch("https://api.meetsquad.ai/v1/data-ingress", {
  method: "POST",
  headers: {
    "Authorization": apiKey,
    "Content-Type": "text/plain"
  },
  body: feedback
});

if (response.ok) {
  const data = await response.json();
  console.log(`✓ Feedback submitted to workspace: ${data.data.workspaceId}`);
} else {
  console.error(`✗ Error: ${response.status}`);
}

package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
)

func submitFeedback(apiKey, feedback string) error {
    url := "https://api.meetsquad.ai/v1/data-ingress"

    req, err := http.NewRequest("POST", url, bytes.NewBufferString(feedback))
    if err != nil {
        return err
    }

    req.Header.Set("Authorization", apiKey)
    req.Header.Set("Content-Type", "text/plain")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    if resp.StatusCode == 201 {
        fmt.Println("✓ Feedback submitted successfully")
    } else {
        body, _ := io.ReadAll(resp.Body)
        fmt.Printf("✗ Error: %d - %s\n", resp.StatusCode, string(body))
    }

    return nil
}

POST /v1/data-ingress/{feedbackSource}Submit feedback with source attribution for better tracking.

cURL

curl -X POST https://api.meetsquad.ai/v1/data-ingress/MOBILE_APP \
  -H "Authorization: your-api-key-here" \
  -H "Content-Type: text/plain" \
  -d "Love the new dark mode feature!"

Python

import requests

api_key = "your-api-key-here"
feedback = "Love the new dark mode feature!"
source = "MOBILE_APP"  # Must be UPPERCASE_WITH_UNDERSCORES

response = requests.post(
    f"https://api.meetsquad.ai/v1/data-ingress/{source}",
    headers={
        "Authorization": api_key,
        "Content-Type": "text/plain"
    },
    data=feedback
)

if response.status_code == 201:
    print("✓ Feedback submitted with source:", source)
else:
    print(f"✗ Error: {response.status_code}")

Ruby

require 'net/http'
require 'uri'

api_key = "your-api-key-here"
feedback = "Love the new dark mode feature!"
source = "MOBILE_APP"

uri = URI("https://api.meetsquad.ai/v1/data-ingress/#{source}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "text/plain"
request.body = feedback

response = http.request(request)

if response.code == "201"
  puts "✓ Feedback submitted with source: #{source}"
else
  puts "✗ Error: #{response.code}"
end

PHP

<?php
$apiKey = "your-api-key-here";
$feedback = "Love the new dark mode feature!";
$source = "MOBILE_APP";

$ch = curl_init("https://api.meetsquad.ai/v1/data-ingress/{$source}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $feedback);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: {$apiKey}",
    "Content-Type: text/plain"
]);

$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($statusCode === 201) {
    echo "✓ Feedback submitted with source: {$source}\n";
} else {
    echo "✗ Error: {$statusCode}\n";
}
?>

Response format

Success (201 Created):

{
  "data": {
    "id": "insight_abc123",
    "workspaceId": "ws_xyz789",
    "content": "The mobile app crashes when I try to upload photos",
    "source": "MOBILE_APP",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Error responses:

Status	Meaning	Common causes
400	Bad Request	Empty feedback, invalid format
401	Unauthorized	Missing or invalid API key
500	Server Error	Temporary issue, retry with backoff

Check authentication

Use the whoami endpoint to verify your API key:

cURL

curl https://api.meetsquad.ai/v1/whoami \
  -H "Authorization: your-api-key-here"

Response

{
  "organizationId": "org_123",
  "organizationName": "Acme Corp",
  "workspaceId": "ws_456",
  "workspaceName": "Product Feedback"
}

Best practices

Add context

Include metadata like user ID, platform, or app version in the feedback text

Use sources consistently

Standardize source names across your org (e.g., always use MOBILE_APP not variations)

Handle errors gracefully

Implement retry logic with exponential backoff for transient failures

Formatting feedback

Structure feedback for better analysis:

"The checkout process is too slow. It takes 5-6 clicks to complete a purchase and I have to re-enter my payment info every time.

User: john@example.com
Platform: iOS
App Version: 2.3.1"

Why this works:
✓ Specific problem described
✓ Measurable details (5-6 clicks)
✓ Context included (payment re-entry)
✓ Metadata for segmentation

"App is bad"

Why this doesn't work:
✗ Too vague - no actionable insights
✗ No context or details
✗ Can't be clustered with similar issues
✗ Missing metadata

Troubleshooting

Feedback not appearing in Squad

Verify API key is correct and workspace-scoped
Check that feedback text is non-empty
Ensure API response was 201 (not 400 or 500)
Give Squad 30-60 seconds to process and cluster new insights

401 Unauthorized errors

Confirm API key is set in environment variables (for npm package)
Verify API key hasn’t been regenerated or revoked
Check you’re using the correct workspace’s key
Test with the /whoami endpoint to validate authentication

Source parameter errors

Source must be UPPERCASE_WITH_UNDERSCORES only
No numbers, hyphens, or spaces allowed
Defaults to UNKNOWN if not specified

Timeout issues

Default timeout is 10 seconds
Increase timeout for slower connections: { timeout: 30000 }
Check your network connectivity
Try with a smaller batch size

What’s next?

View your insights

See how Squad analyzes and clusters your API-submitted feedback

Integrations

Connect additional data sources for richer insights

Chat with data

Ask Squad questions about your API-submitted feedback

Build strategy

Turn feedback into opportunities and solutions

Need help? Contact support@meetsquad.ai or check our API documentation for more details.

​Overview

​Benefits

​Quick start

​Two approaches

Node.js Client Library

Direct API Integration

​Prerequisites

​Using the npm package

​Installation

​Quick start

​Common patterns

​Source naming

​Using the REST API

​Authentication

​Endpoints

​Response format

​Check authentication

​Best practices

Add context

Use sources consistently

Handle errors gracefully

​Formatting feedback

​Troubleshooting

​What’s next?

View your insights

Integrations

Chat with data

Build strategy

Overview

Benefits

Quick start

Two approaches

Prerequisites

Using the npm package

Installation

Quick start

Common patterns

Source naming

Using the REST API

Authentication

Endpoints

Response format

Check authentication

Best practices

Formatting feedback

Troubleshooting

What’s next?