Skip to main content
POST
/
v1
/
public
/
topics.create
curl --location --request POST 'https://api.userorbit.com/v1/public/topics.create' \
--header 'Authorization: Bearer SUBSCRIBER_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Add dark mode to mobile app",
  "description": "Need dark mode for iOS and Android apps",
  "text": "It would be great to have dark mode support across all platforms.",
  "roadmapId": "roadmap-uuid-123",
  "stageId": "stage-uuid-456",
  "meta": {
    "projectId": "mobile-app",
    "feedback": true
  }
}'

{
  "data": {
    "id": "topic-uuid-new",
    "urlId": "xyz789",
    "url": "/add-dark-mode-to-mobile-app-xyz789",
    "title": "Add dark mode to mobile app",
    "description": "Need dark mode for iOS and Android apps",
    "text": "It would be great to have dark mode support across all platforms.",
    "publishedAt": "2024-01-17T15:00:00Z",
    "createdAt": "2024-01-17T15:00:00Z",
    "updatedAt": "2024-01-17T15:00:00Z",
    "roadmapId": "roadmap-uuid-123",
    "stageId": "stage-uuid-456",
    "subscriberId": "sub-uuid-789",
    "voteCount": 0,
    "commentCount": 0,
    "meta": {
      "projectId": "mobile-app",
      "feedback": true
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.userorbit.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

# With subscriber authentication
Authorization: Bearer SUBSCRIBER_JWT_TOKEN

# Or with API key (allows anonymous topics if enabled)
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
title
string
required
Topic title
​
roadmapId
string
required
Roadmap ID (UUID)
​
stageId
string
required
Stage ID (UUID) - must be a public stage
​
description
string
Short description. If not provided, defaults to title.
​
text
string
Full topic text/details
​
meta
object
Custom metadata
​
name
string
Creator name (for anonymous topics only)
​
email
string
Creator email (for anonymous topics only)

​
Response

​
data
object
Created topic object
curl --location --request POST 'https://api.userorbit.com/v1/public/topics.create' \
--header 'Authorization: Bearer SUBSCRIBER_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Add dark mode to mobile app",
  "description": "Need dark mode for iOS and Android apps",
  "text": "It would be great to have dark mode support across all platforms.",
  "roadmapId": "roadmap-uuid-123",
  "stageId": "stage-uuid-456",
  "meta": {
    "projectId": "mobile-app",
    "feedback": true
  }
}'

{
  "data": {
    "id": "topic-uuid-new",
    "urlId": "xyz789",
    "url": "/add-dark-mode-to-mobile-app-xyz789",
    "title": "Add dark mode to mobile app",
    "description": "Need dark mode for iOS and Android apps",
    "text": "It would be great to have dark mode support across all platforms.",
    "publishedAt": "2024-01-17T15:00:00Z",
    "createdAt": "2024-01-17T15:00:00Z",
    "updatedAt": "2024-01-17T15:00:00Z",
    "roadmapId": "roadmap-uuid-123",
    "stageId": "stage-uuid-456",
    "subscriberId": "sub-uuid-789",
    "voteCount": 0,
    "commentCount": 0,
    "meta": {
      "projectId": "mobile-app",
      "feedback": true
    }
  }
}

​
Error Responses

Private Stage
{
  "error": "cannot publish a topic of private stage"
}
Anonymous Not Allowed
{
  "error": "Bad request"
}
Missing Fields
{
  "error": "title is required"
}

​
Behavior

  • Authentication: Requires subscriber token OR API key with anonymous enabled
  • Anonymous Topics: If team allows anonymous feedback, creates subscriber automatically
  • Random Names: Anonymous users get random names if name not provided
  • Moderation: Auto-published unless stage has moderation enabled
  • Private Stages: Cannot create topics in private stages
  • Event Trigger: Fires topics.create event for webhooks

​
Anonymous Topic Creation

If allowAnonymousFeedback is enabled for the team: 
// Anonymous topic with email
{
  name: 'John Doe',
  email: 'john@example.com',
  title: 'Feature request',
  // ... other fields
}

// Anonymous topic without name (gets random name)
{
  email: 'john@example.com',
  title: 'Feature request',
  // name will be auto-generated like "Blue Happy Elephant"
}

​
Use Cases

  • Feature Requests: Let users suggest new features
  • Public Roadmap: Allow community input on roadmap
  • Feedback Collection: Gather user feedback on product direction

​
Notes

  • Stage must not be marked as private
  • Moderation setting on stage controls auto-publishing
  • Metadata fields are whitelisted for security
  • Creates subscriber record for anonymous submissions
  • Team configuration controls anonymous access