DevPlace REST: Issue Reports and Gitea Integration

Filing, listing and commenting on issue tickets that are mirrored to a Gitea repository: the AI rewrite job that normalises a report into a ticket, the job polling endpoint, and the notification path back to the reporter.

The issue tracker is a full integration with a Gitea repository. The listing and detail views read issues straight from Gitea with their live status, and a report you file is first rewritten by the internal AI service into a consistent ticket, then posted to Gitea as an issue. The original reporter is notified when a developer replies or the status changes, and a comment posted here is pushed to Gitea and attributed to your account.

Every endpoint follows the shared Conventions & Errors (auth, content negotiation, pagination, status codes); see Authentication for the four ways to sign requests.

GET /issues - List issue tickets

Render the issue board from Gitea, paginated and filterable by state.

Minimal role: Public

Parameters

Sample response

{
  "issues": [
    {
      "number": 0,
      "title": "Title",
      "state": "string",
      "html_url": "/path",
      "comments_count": 0,
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00",
      "author_username": "username",
      "author_uid": "UID",
      "author_avatar_seed": "string",
      "is_local_author": false
    }
  ],
  "pagination": null,
  "state": "string",
  "configured": false,
  "error_message": "string"
}

POST /issues/create - Report an issue

Enqueue an issue report. It is enhanced by AI and filed on the tracker.

Minimal role: Member

Parameters

Returns a job uid and statusurl. Poll the statusurl until status is done to get the issue number.

Sample response

{
  "uid": "JOB_UID",
  "status_url": "/issues/jobs/JOB_UID"
}

GET /issues/jobs/{uid} - Issue filing job status

Poll the filing job; the result carries the new issue number and url.

Minimal role: Public

Parameters

Sample response

{
  "uid": "JOB_UID",
  "kind": "issue_create",
  "status": "done",
  "number": 42,
  "issue_url": "/issues/42",
  "enhanced": true,
  "error": null,
  "created_at": "2026-06-12T09:00:00+00:00",
  "completed_at": "2026-06-12T09:00:03+00:00"
}

POST /issues/planning - Generate a tickets planning report

Enqueue a phased markdown implementation document for open tickets, with each ticket's full description reproduced verbatim (inline plus a Source Tickets appendix) alongside implementation steps and acceptance criteria. Admin only.

Minimal role: Admin

Parameters

Returns a job uid and statusurl. Poll the statusurl until status is done to read the markdown and download it.

Provide 'numbers' to plan only a chosen subset of open tickets; omitting it plans all open tickets.

Sample response

{
  "uid": "PLANNING_JOB_UID",
  "status_url": "/issues/planning/PLANNING_JOB_UID"
}

GET /issues/planning/{uid} - Planning report job status

Poll the planning job; the result carries the rendered markdown and the download URL. Admin only.

Minimal role: Admin

Parameters

Sample response

{
  "uid": "PLANNING_JOB_UID",
  "kind": "planning",
  "status": "done",
  "download_url": "/issues/planning/PLANNING_JOB_UID/download",
  "markdown": "# Open Tickets Implementation Plan\n\n...",
  "ai_used": true,
  "issue_count": 12,
  "bytes_out": 4096,
  "error": null,
  "created_at": "2026-06-15T09:00:00+00:00",
  "completed_at": "2026-06-15T09:00:05+00:00"
}

GET /issues/planning/{uid}/download - Download the planning report

Download the generated planning report as a markdown file. Admin only.

Minimal role: Admin

Parameters

GET /issues/{number} - View an issue ticket

Render a Gitea issue and its comments. Returns an HTML page.

Minimal role: Public

Parameters

Sample response

{
  "issue": {
    "number": 0,
    "title": "Title",
    "state": "string",
    "html_url": "/path",
    "comments_count": 0,
    "created_at": "2026-01-01T00:00:00+00:00",
    "updated_at": "2026-01-01T00:00:00+00:00",
    "author_username": "username",
    "author_uid": "UID",
    "author_avatar_seed": "string",
    "is_local_author": false
  },
  "body": "string",
  "comments": [
    {
      "id": 0,
      "body": "string",
      "html_url": "/path",
      "created_at": "2026-01-01T00:00:00+00:00",
      "author_username": "username",
      "author_uid": "UID",
      "author_avatar_seed": "string",
      "is_local_author": false,
      "attachments": [
        {
          "uid": "UID",
          "filename": "string",
          "url": "/path",
          "size": 0,
          "is_image": false,
          "is_video": false,
          "mime_type": "string",
          "created_at": "2026-01-01T00:00:00+00:00",
          "can_modify": false
        }
      ]
    }
  ],
  "attachments": [
    {
      "uid": "UID",
      "filename": "string",
      "url": "/path",
      "size": 0,
      "is_image": false,
      "is_video": false,
      "mime_type": "string",
      "created_at": "2026-01-01T00:00:00+00:00",
      "can_modify": false
    }
  ],
  "can_comment": false,
  "can_attach": false,
  "viewer_is_admin": false
}

POST /issues/{number}/comment - Comment on an issue

Post a comment to the Gitea issue, attributed to the current user.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/issues/12",
  "data": {
    "comment_id": 1
  }
}

POST /issues/{number}/status - Change an issue status

Open or close the Gitea issue. Admin only.

Minimal role: Admin

Parameters

Sample response

{
  "ok": true,
  "redirect": "/issues/12",
  "data": {
    "state": "closed"
  }
}

GET /issues/{number}/attachments - List issue attachments

Return the files attached to an issue ticket.

Minimal role: Public

Parameters

Sample response

{
  "number": 0,
  "attachments": [
    {
      "uid": "UID",
      "filename": "string",
      "url": "/path",
      "size": 0,
      "is_image": false,
      "is_video": false,
      "mime_type": "string",
      "created_at": "2026-01-01T00:00:00+00:00",
      "can_modify": false
    }
  ]
}

POST /issues/{number}/attachments - Attach files to an issue

Link already-uploaded files (from /uploads/upload) to an open issue. The files are also mirrored to the Gitea tracker. Allowed only while the issue is open.

Minimal role: Member

Parameters

Only the open issue accepts changes; a closed issue returns 409.

You can only link your own uploads unless you are an administrator.

DELETE /issues/{number}/attachments/{uid} - Delete an issue attachment

Soft-delete a file from an open issue (owner or administrator) and remove it from the tracker.

Minimal role: Member

Parameters

POST /issues/{number}/comments/{cid}/attachments - Attach files to an issue comment

Link already-uploaded files to an issue comment (issue must be open). Mirrored to the Gitea comment.

Minimal role: Member

Parameters

DELETE /issues/{number}/comments/{cid}/attachments/{uid} - Delete an issue comment attachment

Soft-delete a file from an issue comment (owner or administrator) and remove it from the tracker.

Minimal role: Member

Parameters