Praison AI

Human-Readable Issue IDs

Automatic sequential issue identifiers for workspace organization

Issues are automatically assigned sequential identifiers like ISS-1, ISS-2 within each workspace for easy reference and tracking.

Issues are automatically assigned sequential identifiers like ISS-1, ISS-2 within each workspace for easy reference and tracking.

python
from praisonaiagents import Agent

agent = Agent(name="tracker", instructions="Reference issues by stable IDs.")
agent.start("What is the status of ISS-3?")

The user references sequential IDs like ISS-1; the platform assigns them automatically per workspace.

Diagram

Issue ID Generation

📝 Create Issue

🔢 Counter

🏷️ Generate ID

💾 Store Issue

Quick Start

  1. Create First Issue

    Create an issue and receive automatic ID assignment:

    bash
    TOKEN="your-jwt-token"
WS_ID="workspace-id"

curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"First issue"}' \
  --max-time 10

# Response: {"number": 1, "identifier": "ISS-1", "title": "First issue", ...}
  2. Create Additional Issues

    Subsequent issues get sequential numbers automatically:

    python
    import asyncio
from praisonai_platform.client import PlatformClient

async def main():
    client = PlatformClient("http://localhost:8000", token="your-token")
    ws_id = "your-workspace-id"

    issue1 = await client.create_issue(ws_id, "First task")
    print(issue1["identifier"])  # "ISS-1"

    issue2 = await client.create_issue(ws_id, "Second task") 
    print(issue2["identifier"])  # "ISS-2"

    issue3 = await client.create_issue(ws_id, "Third task")
    print(issue3["identifier"])  # "ISS-3"

asyncio.run(main())

How It Works

Diagram
DatabaseWorkspaceAPIUserDatabaseWorkspaceAPIUserCreate Issue RequestCheck Counter & PrefixIncrement CounterNew NumberGenerate IdentifierIssue with IDResponse with identifier
ComponentPurposeExample
CounterTracks next available number3 (next issue will be #3)
PrefixCustomizable identifier prefix"ISS", "PRJ", "BUG"
NumberSequential workspace-scoped number1, 2, 3
IdentifierHuman-readable combined IDISS-1, PRJ-2, BUG-3

Response Fields

Every issue response includes these auto-generated fields:

json
{
  "id": "issue-abc123",
  "number": 3,
  "identifier": "ISS-3", 
  "title": "Third issue in workspace",
  "description": "Issue description",
  "status": "open",
  "created_at": "2026-04-14T06:22:51Z",
  "workspace_id": "workspace-xyz"
}
FieldTypeDescription
numberintegerSequential number within workspace
identifierstringHuman-readable ID ({prefix}-{number})
idstringUnique database identifier

Common Patterns

Basic Issue Creation

bash
# Create issue with curl
curl -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug in login flow", "description": "Users cannot log in"}'

Python SDK Integration

python
from praisonai_platform.client import PlatformClient

async def create_issues():
    client = PlatformClient("http://localhost:8000", token="your-token")

    # Issues get auto-numbered sequentially
    bug = await client.create_issue("ws-123", "Fix login bug")
    print(f"Created: {bug['identifier']}")  # "ISS-1"

    feature = await client.create_issue("ws-123", "Add dark mode")  
    print(f"Created: {feature['identifier']}")  # "ISS-2"

Batch Issue Creation

python
async def bulk_create():
    client = PlatformClient("http://localhost:8000", token="your-token")

    tasks = [
        "Setup development environment",
        "Create user authentication",
        "Implement dashboard",
        "Add notification system"
    ]

    for i, task in enumerate(tasks):
        issue = await client.create_issue("ws-123", task)
        print(f"{i+1}. {issue['identifier']}: {task}")

    # Output:
    # 1. ISS-1: Setup development environment  
    # 2. ISS-2: Create user authentication
    # 3. ISS-3: Implement dashboard
    # 4. ISS-4: Add notification system

Customizing the Prefix

Diagram

Configuration

Workspace Settings

issue_prefix field

New Issues Use New Prefix

Existing Issues Keep Original

Prefix Options

ISS – Default Issues

PRJ – Project Tasks

BUG – Bug Reports

FEAT – Feature Requests

The workspace issue_prefix can be customized per workspace. After changing the prefix, new issues use the new prefix while existing issues retain their original identifiers.

python
# Example: Change prefix to "PRJ" 
# New issues will be: PRJ-4, PRJ-5, etc.
# Existing issues remain: ISS-1, ISS-2, ISS-3

Best Practices

Choose Meaningful Prefixes

Use prefixes that clearly identify the workspace or project type:

  • ISS – General issues
  • BUG – Bug tracking workspace
  • FEAT – Feature request workspace
  • PRJ – Project management workspace
Workspace-Scoped Numbering

Numbers are unique per workspace, not globally:

  • Workspace A: ISS-1, ISS-2, ISS-3
  • Workspace B: ISS-1, ISS-2, ISS-3 (separate counter)
Immutable Identifiers

Once assigned, issue numbers and identifiers never change:

  • Safe to reference in documentation
  • Stable for external integrations
  • Guaranteed uniqueness within workspace
Testing Considerations

Use test workspaces for development to avoid polluting production counters:

python
# Use separate workspace for testing
test_ws = "test-workspace-123"
issue = await client.create_issue(test_ws, "Test issue")

Testing

Run the platform issue numbering tests:

bash
# Test issue numbering mechanism
pytest tests/test_new_gaps.py::TestIssueNumbering -v

# Test API integration
pytest tests/test_new_api_integration.py::TestIssueNumberingAPI -v

Related

Platform API

Complete platform API reference

 Workspace Management

Managing workspaces and settings