Discourse Meta
Us.anthropic.claude-sonnet-4-5-20250929-v1:0

Discourse Assign Plugin API Documentation

sam

looking at discourse/discourse source code search discourse assign plugin and figure out the exact endpoints and payloads I should use to assign and unassign a topic, document with a curl example and example reply

GitHub_Helper_bot
Thinking...The user wants me to search the discourse/discourse repository for the discourse assign plugin and find the exact endpoints and payloads for assigning and unassigning topics. I need to:
  1. Search for files related to the assign plugin
  2. Find the controller/API endpoints
  3. Document the exact payloads, HTTP methods, and provide curl examples

Let me start by searching for assign-related files in the repository.

I’ll help you find the exact endpoints and payloads for the Discourse assign plugin. Let me search for the relevant files in the discourse/discourse repository.

GitHub search files

Searched for 'assign, plugin' in discourse/discourse/main

GitHub code search

Searched for 'assign plugin controller' in discourse/discourse

Now let me get the actual assign controller file to see the exact endpoints:

GitHub file content

Retrieved content of plugins/discourse-assign/app/controllers/discourse_assign/assign_controller.rb, plugins/discourse-assign/config/routes.rb from discourse/discourse@main

Perfect! I found the assign plugin controller. Now let me examine the specific code to document the endpoints and payloads. Let me also check for more information about the parameters that can be used.

GitHub code search

Searched for 'Assigner.new assign' in discourse/discourse

Perfect! Now I have enough information to document the assign and unassign endpoints. Let me create comprehensive documentation with curl examples.

Discourse Assign Plugin - API Endpoints

Based on the source code, here are the exact endpoints and payloads for assigning and unassigning topics in Discourse:

Base URL

All assign endpoints are mounted at /assign

1. Assign a Topic

Endpoint

PUT /assign/assign.json

Required Parameters

  • target_id (integer) - The ID of the topic
  • target_type (string) - The type of target (e.g., “Topic”)
  • Either:
    • username (string) - Username to assign to, OR
    • group_name (string) - Group name to assign to

Optional Parameters

  • note (string) - A note about the assignment
  • status (string) - Assignment status (requires enable_assign_status setting enabled)
  • should_notify (boolean) - Whether to send notification (default: true)

Authentication

Requires API key or session authentication with assign permissions.

Curl Example - Assign to User

curl -X PUT "https://your-discourse.com/assign/assign.json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME" \
  -d '{
    "target_id": 123,
    "target_type": "Topic",
    "username": "john_doe",
    "note": "Please review this topic",
    "status": "In Progress",
    "should_notify": true
  }'

Curl Example - Assign to Group

curl -X PUT "https://your-discourse.com/assign/assign.json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME" \
  -d '{
    "target_id": 123,
    "target_type": "Topic",
    "group_name": "moderators",
    "note": "Team review needed",
    "should_notify": true
  }'

Success Response

{
  "success": "OK"
}

Error Responses

400 Bad Request - Various assignment failures:

{
  "error": "john_doe is already assigned to this topic"
}

403 Forbidden - User doesn’t have permission:

{
  "error": "You are not permitted to view the requested resource."
}

404 Not Found - Topic or user not found:

{
  "error": "The requested URL or resource could not be found."
}

Possible Error Messages:

  • "already_assigned" - User already assigned to this topic
  • "forbidden_assign_to" - User cannot assign to target user
  • "forbidden_assignee_not_pm_participant" - Assignee not a PM participant
  • "forbidden_assignee_cant_see_topic" - Assignee cannot see the topic
  • "group_already_assigned" - Group already assigned
  • "too_many_assigns_for_topic" - Topic has reached assignment limit
  • "too_many_assigns" - User has reached max assigned topics

2. Unassign a Topic

Endpoint

PUT /assign/unassign.json

Required Parameters

  • target_id (integer) - The ID of the topic
  • target_type (string) - The type of target (e.g., “Topic”)

Authentication

Requires API key or session authentication with assign permissions.

Curl Example

curl -X PUT "https://your-discourse.com/assign/unassign.json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME" \
  -d '{
    "target_id": 123,
    "target_type": "Topic"
  }'

Success Response

{
  "success": "OK"
}

Error Responses

403 Forbidden - User doesn’t have permission
404 Not Found - Topic not found or invalid target type

3. Get Assignment Suggestions

Endpoint

GET /assign/suggestions.json

Curl Example

curl -X GET "https://your-discourse.com/assign/suggestions.json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME"

Response Example

{
  "assign_allowed_on_groups": ["staff", "moderators"],
  "assign_allowed_for_groups": ["trust_level_4"],
  "suggestions": [
    {
      "id": 1,
      "username": "john_doe",
      "name": "John Doe",
      "avatar_template": "/user_avatar/discourse.example.com/john_doe/{size}/123_2.png"
    }
  ]
}

Important Notes

  1. Target Types: The code validates target_type must be a valid assignment type (typically “Topic” or “Post”)

  2. Permissions: Users must have the can_assign? permission, which is controlled by the assign_allowed_on_groups site setting

  3. Assignment Limits:

    • Per-user limit controlled by max_assigned_topics site setting
    • Per-topic limit is ASSIGNMENTS_PER_TOPIC_LIMIT (defined in Assigner class)

  4. Status Feature: Assignment statuses require the enable_assign_status site setting to be enabled

  5. Notifications: By default, assigned users receive notifications unless should_notify is explicitly set to false

  6. Group Assignments: When assigning to a group, all members with appropriate permissions can see and act on the assignment

Alternative: Using URL Parameters

You can also send parameters as form data instead of JSON:

# Assign
curl -X PUT "https://your-discourse.com/assign/assign.json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME" \
  -d "target_id=123" \
  -d "target_type=Topic" \
  -d "username=john_doe" \
  -d "note=Review needed"

# Unassign
curl -X PUT "https://your-discourse.com/assign/unassign.json" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Username: YOUR_USERNAME" \
  -d "target_id=123" \
  -d "target_type=Topic"

This documentation is based on the actual controller code from plugins/discourse-assign/app/controllers/discourse_assign/assign_controller.rb in the discourse/discourse repository.