curl https://userhero.co/api/v1/feedback \
  -H "Authorization: Bearer sk_live_your_key"

https://userhero.co/api/v1

{
  "error": {
    "code": "not_found",
    "message": "Feedback item not found"
  }
}

curl -X POST https://userhero.co/api/v1/feedback \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Idempotency-Key: unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "ws_123", "projectId": "proj_456", "message": "Bug report"}'

GET /api/v1/feedback?workspaceId={id}

POST /api/v1/feedback/upload?workspaceId={id}

{
  "data": {
    "url": "https://storage.googleapis.com/...",
    "contentType": "image/png",
    "size": 102400
  }
}

{
  "data": {
    "id": "att_1712345678_abc123",
    "url": "https://storage.googleapis.com/...",
    "type": "image",
    "fileName": "screenshot.png",
    "fileSize": 102400,
    "mimeType": "image/png"
  }
}

POST /api/v1/feedback

{
  "workspaceId": "ws_123",
  "projectId": "proj_456",
  "message": "Something is broken",
  "category": "bug",
  "userEmail": "user@example.com",
  "screenshotUrl": "https://storage.googleapis.com/...",
  "context": { "page": "/settings", "browser": "Chrome" }
}

GET /api/v1/feedback/{id}?workspaceId={id}

GET /api/v1/feedback/number/{ticketNumber}?workspaceId={id}

curl https://userhero.co/api/v1/feedback/number/245?workspaceId=ws_123 \
  -H "Authorization: Bearer sk_live_your_key"

PATCH /api/v1/feedback/{id}

{
  "workspaceId": "ws_123",
  "status": "resolved",
  "priority": "high",
  "assigneeId": "user_abc",
  "tags": ["critical"],
  "isPublic": true
}

DELETE /api/v1/feedback/{id}?workspaceId={id}

{
  "customMetadata": {
    "userId": "usr_123",
    "plan": "enterprise",
    "company": "Acme Inc",
    "customFields": {
      "df_name": "Alice",
      "df_email": "alice@example.com",
      "cf_plan_abc12": "Enterprise",
      "cf_account_xyz": "acc_99887"
    }
  }
}

{
  "workspaceId": "ws_123",
  "projectId": "proj_456",
  "message": "Checkout is broken",
  "customMetadata": {
    "userId": "usr_123",
    "plan": "enterprise",
    "customFields": {
      "df_name": "Alice",
      "df_email": "alice@example.com",
      "cf_plan_abc12": "Enterprise",
      "cf_account_xyz": "acc_99887"
    }
  }
}

{
  "id": "fb_abc123",
  "message": "Checkout is broken",
  "customMetadata": {
    "userId": "usr_123",
    "plan": "enterprise",
    "customFields": {
      "df_name": "Alice",
      "df_email": "alice@example.com",
      "cf_plan_abc12": "Enterprise",
      "cf_account_xyz": "acc_99887"
    }
  }
}

GET /api/v1/feedback/{id}/comments

{
  "data": [
    {
      "id": "cc_1712345678_abc123",
      "message": "We're looking into this issue.",
      "authorType": "agent",
      "authorName": "Jane Smith",
      "attachments": [],
      "createdAt": "2026-04-06T10:30:00.000Z"
    },
    {
      "id": "cc_1712345999_def456",
      "message": "Thanks! Here's a screenshot.",
      "authorType": "customer",
      "authorName": "John Doe",
      "attachments": [
        {
          "id": "att_1712345999_xyz",
          "url": "https://storage.googleapis.com/...",
          "type": "image",
          "fileName": "screenshot.png",
          "fileSize": 102400,
          "mimeType": "image/png"
        }
      ],
      "createdAt": "2026-04-06T11:00:00.000Z"
    }
  ]
}

POST /api/v1/feedback/{id}/comments

{
  "message": "We've fixed this in the latest release."
}

{
  "message": "The issue is still happening.",
  "authorType": "customer",
  "authorName": "John Doe",
  "authorEmail": "john@example.com"
}

{
  "message": "Here's what I see",
  "authorType": "customer",
  "authorName": "John Doe",
  "authorEmail": "john@example.com",
  "attachments": [
    {
      "id": "att_1712345678_abc123",
      "url": "https://storage.googleapis.com/...",
      "type": "image",
      "fileName": "screenshot.png",
      "fileSize": 102400,
      "mimeType": "image/png"
    }
  ]
}

GET /api/v1/feedback/{id}/notes

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "Escalated to engineering team.",
      "authorName": "Jane Smith",
      "authorEmail": "jane@company.com",
      "attachments": [],
      "createdAt": "2026-04-06T10:30:00.000Z"
    }
  ]
}

POST /api/v1/feedback/{id}/notes

{
  "content": "Customer confirmed this is reproducible on Chrome 120.",
  "contentHtml": "<p>Customer confirmed this is reproducible on Chrome 120.</p>",
  "mentions": ["user_abc"]
}

GET /api/v1/projects?workspaceId={id}

POST /api/v1/projects

{
  "workspaceId": "ws_123",
  "name": "My App",
  "domain": "app.example.com"
}

GET /api/v1/projects/{id}?workspaceId={id}

{
  "data": {
    "id": "proj_456",
    "workspaceId": "ws_123",
    "name": "My App",
    "domain": "app.example.com",
    "publicKey": "pk_live_abc123",
    "customFieldDefinitions": [
      { "id": "cf_plan_abc12", "label": "Plan", "type": "select", "required": false, "options": ["Free", "Starter", "Pro"] },
      { "id": "cf_score_xyz", "label": "NPS Score", "type": "number", "required": false, "validation": { "min": 0, "max": 10 } },
      { "id": "cf_notes_001", "label": "Notes", "type": "textarea", "required": false, "placeholder": "Any additional context" }
    ],
    "disabledDefaultFields": [],
    "createdAt": "2024-08-12T09:21:04.000Z",
    "updatedAt": "2025-01-04T14:02:11.000Z"
  }
}

PATCH /api/v1/projects/{id}

{
  "workspaceId": "ws_123",
  "name": "Updated Name",
  "domain": "new.example.com",
  "slaRules": [
    { "priority": "urgent", "hours": 4 },
    { "priority": "high", "hours": 24 }
  ]
}

DELETE /api/v1/projects/{id}?workspaceId={id}

GET /api/v1/widgets?workspaceId={id}

POST /api/v1/widgets

{
  "workspaceId": "ws_123",
  "projectId": "proj_456",
  "name": "Feedback Button",
  "config": { "type": "modal" },
  "styling": { "primaryColor": "#6366f1" }
}

GET /api/v1/widgets/{id}?workspaceId={id}

PATCH /api/v1/widgets/{id}

{
  "workspaceId": "ws_123",
  "name": "Updated Widget",
  "enabled": true,
  "config": { "type": "popover" }
}

DELETE /api/v1/widgets/{id}?workspaceId={id}

GET /api/v1/workspaces

{
  "data": [
    {
      "id": "ws_123",
      "name": "Acme Inc",
      "plan": "pro",
      "billingInterval": "yearly",
      "subscriptionStatus": "active",
      "apiAccessEnabled": true,
      "memberCount": 6,
      "role": "owner",
      "createdAt": "2024-08-12T09:21:04.000Z",
      "updatedAt": "2025-01-04T14:02:11.000Z"
    }
  ]
}

GET /api/v1/workspace/{id}

GET /api/v1/workspace/{id}/usage

GET /api/v1/webhooks?workspaceId={id}

POST /api/v1/webhooks

{
  "workspaceId": "ws_123",
  "name": "Zapier Integration",
  "projectId": "proj_456"
}

DELETE /api/v1/webhooks/{id}?workspaceId={id}

# Compute HMAC-SHA256 signature
SIGNATURE=$(echo -n '{"message":"Bug report"}' | openssl dgst -sha256 -hmac "whsec_your_secret" | awk '{print $2}')

curl -X POST https://userhero.co/api/hooks/{slug} \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -d '{"message": "Bug report"}'

GET /api/v1/customers?workspaceId={id}

POST /api/v1/customers

{
  "workspaceId": "ws_123",
  "name": "Jane Smith",
  "primaryEmail": "jane@example.com",
  "company": "Acme Inc",
  "tags": ["enterprise", "beta"]
}

GET /api/v1/customers/{id}

PATCH /api/v1/customers/{id}

{
  "name": "Jane Smith-Rogers",
  "tags": ["enterprise", "beta", "vip"],
  "customFields": { "plan": "pro", "accountManager": "alex" }
}

DELETE /api/v1/customers/{id}

POST /api/v1/customers/{targetId}/merge

{
  "sourceCustomerId": "cust_old_duplicate"
}

{
  "data": {
    "id": "cust_target",
    "mergedSourceId": "cust_old_duplicate",
    "mergedFeedbackCount": 5
  }
}

GET /api/v1/automations

{
  "automations": [
    {
      "id": "jg9bTVq5gSvjVm0L55cS",
      "name": "Auto-assign billing",
      "scope": "feedback.created",
      "enabled": true,
      "priority": 0,
      "systemGenerated": false,
      "conditions": { "combinator": "and", "rules": [] },
      "actions": [{ "type": "assign_agent", "params": { "userId": "user_abc" } }],
      "runStats": { "matched7d": 42, "errored7d": 0 },
      "lastRunAt": "2026-05-30T10:00:00.000Z",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "def456"
}

GET /api/v1/automations/{id}

POST /api/v1/automations/{id}/run

{
  "runId": "run_xyz789",
  "outcome": "matched",
  "actionsExecuted": [
    { "type": "set_status", "success": true },
    { "type": "add_tag", "success": true }
  ]
}

GET /api/v1/automations/{id}/runs

{
  "runs": [
    {
      "id": "run_xyz789",
      "outcome": "matched",
      "runAt": "2026-05-30T10:00:00.000Z",
      "feedbackId": "feedback_abc123",
      "actionsExecuted": [
        { "type": "set_status", "success": true }
      ],
      "actor": { "userId": "user_abc", "name": "Alice", "system": false }
    }
  ]
}

const API_KEY = 'sk_live_your_key';
const BASE = 'https://userhero.co/api/v1';

// List feedback
const res = await fetch(`${BASE}/feedback?workspaceId=ws_123`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const { data } = await res.json();

// List feedback by user email
const userRes = await fetch(`${BASE}/feedback?workspaceId=ws_123&userEmail=user@example.com`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

// Upload an image
const form = new FormData();
form.append('file', fs.createReadStream('screenshot.png'));
const uploadRes = await fetch(`${BASE}/feedback/upload?workspaceId=ws_123`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});
const { data: { url } } = await uploadRes.json();

// Upload an audio file
const audioForm = new FormData();
audioForm.append('file', fs.createReadStream('recording.webm'));
const audioUpload = await fetch(`${BASE}/feedback/upload?workspaceId=ws_123`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: audioForm,
});
const { data: { url: audioUrl } } = await audioUpload.json();

// Create feedback with attachment and audio
await fetch(`${BASE}/feedback`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspaceId: 'ws_123',
    projectId: 'proj_456',
    message: 'Feature request from API',
    screenshotUrl: url,
    audioUrl: audioUrl,
  }),
});

// Upload a conversation attachment
const attForm = new FormData();
attForm.append('file', fs.createReadStream('screenshot.png'));
attForm.append('feedbackId', 'feedback_id');
const attRes = await fetch(`${BASE}/feedback/upload?workspaceId=ws_123`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: attForm,
});
const attachment = (await attRes.json()).data;

// Add agent reply with attachment
await fetch(`${BASE}/feedback/feedback_id/comments`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Here is the fix',
    attachments: [attachment],
  }),
});

// Add customer reply on behalf of end-user
await fetch(`${BASE}/feedback/feedback_id/comments`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'The issue is still happening',
    authorType: 'customer',
    authorName: 'John Doe',
    authorEmail: 'john@example.com',
  }),
});

// Add internal note
await fetch(`${BASE}/feedback/feedback_id/notes`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'Escalated to engineering',
  }),
});

import requests

API_KEY = "sk_live_your_key"
BASE = "https://userhero.co/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List feedback
res = requests.get(f"{BASE}/feedback", headers=headers, params={"workspaceId": "ws_123"})
feedback = res.json()["data"]

# List feedback by user email
res = requests.get(f"{BASE}/feedback", headers=headers, params={
    "workspaceId": "ws_123",
    "userEmail": "user@example.com",
})

# Upload an image
with open("screenshot.png", "rb") as f:
    upload_res = requests.post(
        f"{BASE}/feedback/upload",
        headers=headers,
        params={"workspaceId": "ws_123"},
        files={"file": ("screenshot.png", f, "image/png")},
    )
url = upload_res.json()["data"]["url"]

# Upload an audio file
with open("recording.webm", "rb") as f:
    audio_res = requests.post(
        f"{BASE}/feedback/upload",
        headers=headers,
        params={"workspaceId": "ws_123"},
        files={"file": ("recording.webm", f, "audio/webm")},
    )
audio_url = audio_res.json()["data"]["url"]

# Create feedback with attachment and audio
requests.post(f"{BASE}/feedback", headers=headers, json={
    "workspaceId": "ws_123",
    "projectId": "proj_456",
    "message": "Bug from CI pipeline",
    "screenshotUrl": url,
    "audioUrl": audio_url,
})

# Upload a conversation attachment
with open("screenshot.png", "rb") as f:
    att_res = requests.post(
        f"{BASE}/feedback/upload",
        headers=headers,
        params={"workspaceId": "ws_123"},
        data={"feedbackId": "feedback_id"},
        files={"file": ("screenshot.png", f, "image/png")},
    )
attachment = att_res.json()["data"]

# Add agent reply with attachment
requests.post(f"{BASE}/feedback/feedback_id/comments", headers=headers, json={
    "message": "Here is the fix",
    "attachments": [attachment],
})

# Add customer reply on behalf of end-user
requests.post(f"{BASE}/feedback/feedback_id/comments", headers=headers, json={
    "message": "The issue is still happening",
    "authorType": "customer",
    "authorName": "John Doe",
    "authorEmail": "john@example.com",
})

# Add internal note
requests.post(f"{BASE}/feedback/feedback_id/notes", headers=headers, json={
    "content": "Escalated to engineering",
})

# List feedback by user email
curl "https://userhero.co/api/v1/feedback?workspaceId=ws_123&userEmail=user@example.com" \
  -H "Authorization: Bearer sk_live_your_key"

# Upload an image
curl -X POST "https://userhero.co/api/v1/feedback/upload?workspaceId=ws_123" \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "file=@screenshot.png"

# Create feedback with screenshot
curl -X POST "https://userhero.co/api/v1/feedback" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "ws_123", "projectId": "proj_456", "message": "Bug report", "screenshotUrl": "https://storage.googleapis.com/..."}'

# Upload conversation attachment
curl -X POST "https://userhero.co/api/v1/feedback/upload?workspaceId=ws_123" \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "file=@screenshot.png" \
  -F "feedbackId=feedback_id"

# Add agent reply
curl -X POST "https://userhero.co/api/v1/feedback/feedback_id/comments" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "We are looking into this."}'

# Add customer reply on behalf of end-user
curl -X POST "https://userhero.co/api/v1/feedback/feedback_id/comments" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Still broken", "authorType": "customer", "authorName": "John Doe", "authorEmail": "john@example.com"}'

# List comments
curl "https://userhero.co/api/v1/feedback/feedback_id/comments" \
  -H "Authorization: Bearer sk_live_your_key"

# Add internal note
curl -X POST "https://userhero.co/api/v1/feedback/feedback_id/notes" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Escalated to engineering"}'

# List projects
curl "https://userhero.co/api/v1/projects?workspaceId=ws_123" \
  -H "Authorization: Bearer sk_live_your_key"

# Create project with idempotency
curl -X POST "https://userhero.co/api/v1/projects" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-proj-001" \
  -d '{"workspaceId": "ws_123", "name": "New Project"}'