Create Topic

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
  }
}'

curl --location --request POST 'https://api.userorbit.com/v1/public/topics.create' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Add dark mode to mobile app",
  "description": "Need dark mode",
  "roadmapId": "roadmap-uuid-123",
  "stageId": "stage-uuid-456",
  "name": "John Doe",
  "email": "john@example.com"
}'

const response = await fetch('https://api.userorbit.com/v1/public/topics.create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${subscriberToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Add dark mode to mobile app',
    description: 'Need dark mode for mobile',
    text: 'It would be great to have dark mode support.',
    roadmapId: roadmapId,
    stageId: stageId,
    meta: {
      projectId: 'mobile-app'
    }
  })
});

const { data: topic } = await response.json();

import requests

response = requests.post(
    'https://api.userorbit.com/v1/public/topics.create',
    headers={
        'Authorization': f'Bearer {subscriber_token}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Add dark mode to mobile app',
        'description': 'Need dark mode for mobile',
        'text': 'It would be great to have dark mode support.',
        'roadmapId': roadmap_id,
        'stageId': stage_id,
        'meta': {
            'projectId': 'mobile-app'
        }
    }
)

topic = response.json()['data']

{
  "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
    }
  }
}

POST

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
  }
}'

curl --location --request POST 'https://api.userorbit.com/v1/public/topics.create' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Add dark mode to mobile app",
  "description": "Need dark mode",
  "roadmapId": "roadmap-uuid-123",
  "stageId": "stage-uuid-456",
  "name": "John Doe",
  "email": "john@example.com"
}'

const response = await fetch('https://api.userorbit.com/v1/public/topics.create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${subscriberToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Add dark mode to mobile app',
    description: 'Need dark mode for mobile',
    text: 'It would be great to have dark mode support.',
    roadmapId: roadmapId,
    stageId: stageId,
    meta: {
      projectId: 'mobile-app'
    }
  })
});

const { data: topic } = await response.json();

import requests

response = requests.post(
    'https://api.userorbit.com/v1/public/topics.create',
    headers={
        'Authorization': f'Bearer {subscriber_token}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Add dark mode to mobile app',
        'description': 'Need dark mode for mobile',
        'text': 'It would be great to have dark mode support.',
        'roadmapId': roadmap_id,
        'stageId': stage_id,
        'meta': {
            'projectId': 'mobile-app'
        }
    }
)

topic = response.json()['data']

{
  "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
    }
  }
}

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

string

required

Topic title

string

required

Roadmap ID (UUID)

string

required

Stage ID (UUID) - must be a public stage

string

Short description. If not provided, defaults to title.

string

Full topic text/details

object

Custom metadata

Show Meta Fields

string

Call-to-action title

string

Call-to-action URL

string

Call-to-action image URL

string

Meta description

boolean

Mark as feedback type

string

Associated project ID

string

Creator name (for anonymous topics only)

string

Creator email (for anonymous topics only)

Response

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
  }
}'

curl --location --request POST 'https://api.userorbit.com/v1/public/topics.create' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Add dark mode to mobile app",
  "description": "Need dark mode",
  "roadmapId": "roadmap-uuid-123",
  "stageId": "stage-uuid-456",
  "name": "John Doe",
  "email": "john@example.com"
}'

const response = await fetch('https://api.userorbit.com/v1/public/topics.create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${subscriberToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Add dark mode to mobile app',
    description: 'Need dark mode for mobile',
    text: 'It would be great to have dark mode support.',
    roadmapId: roadmapId,
    stageId: stageId,
    meta: {
      projectId: 'mobile-app'
    }
  })
});

const { data: topic } = await response.json();

import requests

response = requests.post(
    'https://api.userorbit.com/v1/public/topics.create',
    headers={
        'Authorization': f'Bearer {subscriber_token}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Add dark mode to mobile app',
        'description': 'Need dark mode for mobile',
        'text': 'It would be great to have dark mode support.',
        'roadmapId': roadmap_id,
        'stageId': stage_id,
        'meta': {
            'projectId': 'mobile-app'
        }
    }
)

topic = response.json()['data']

{
  "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

Get Topic Info Subscribe to Topic

API Reference

Roadmap

Feedback

Subscribers

Authentication

Request Body

Response

Error Responses

Behavior

Anonymous Topic Creation

Use Cases

Notes

​Authentication

​Request Body

​Response

​Error Responses

​Behavior

​Anonymous Topic Creation

​Use Cases

​Notes

Authentication

Request Body

Response

Error Responses

Behavior

Anonymous Topic Creation

Use Cases

Notes