Skip to main content

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

Prerequisites

1

Get your API key

  1. Navigate to Workspace dropdown → Settings in Squad
  2. Find the API Access section
  3. Click Generate API Key or copy your existing key
API keys are workspace-scoped. Each workspace has its own unique key.
2

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

Quick start

1

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.
2

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

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);

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
});
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

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}`);
}
Go
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
}

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:
StatusMeaningCommon causes
400Bad RequestEmpty feedback, invalid format
401UnauthorizedMissing or invalid API key
500Server ErrorTemporary 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: [email protected]
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

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?

Need help? Contact [email protected] or check our API documentation for more details.