---
title: "DevPlace REST: Issue Reports and Gitea Integration"
description: "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."
language: null
framework: null
category: api_design
tags:
  - devplace
  - api
  - http-api
  - issue-tracking
  - gitea
  - async-jobs
  - rest
  - integration
  - webhooks
keywords:
  - devplace POST issue report endpoint
  - devplace issue job uid polling status
  - devplace gitea issue mirror integration
  - devplace issue comment api attribution
last_updated: 2026-08-12
difficulty: intermediate
version: "DevPlace (devplace.net), documented 2026-08"
related:
  - conventions_and_errors.md
  - authentication.md
  - ../../tools/gitea/gitea_actions.md
  - README.md
search_priority: normal
status: published
---

# DevPlace REST: Issue Reports and Gitea Integration

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](conventions_and_errors.md) (auth, content
negotiation, pagination, status codes); see [Authentication](authentication.md) 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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `state` | query | string | no | Filter: open (default), closed, or all. |
| `page` | query | integer | no | 1-based page. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `title` | form | string | yes | Title, 1-200 characters. |
| `description` | form | textarea | yes | Description, 1-5000 characters. |

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

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uid` | path | string | yes | Job uid. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `numbers` | form | string | no | Comma-separated issue numbers to include. Omit to plan every open ticket. |

> Returns a job uid and status_url. Poll the status_url 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**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uid` | path | string | yes | Planning job uid. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `uid` | path | string | yes | Planning job uid. |

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

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

*Minimal role:* Public

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `body` | form | textarea | yes | Comment, 1-5000 characters. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `status` | form | string | yes | New status: open or closed. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `attachment_uids` | form | string | yes | Comma separated attachment uids returned by /uploads/upload. |

> 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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `uid` | path | string | yes | Attachment uid. |

## `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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `cid` | path | integer | yes | Gitea comment id. |
| `attachment_uids` | form | string | yes | Comma separated attachment uids returned by /uploads/upload. |

## `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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `number` | path | integer | yes | Issue number. |
| `cid` | path | integer | yes | Gitea comment id. |
| `uid` | path | string | yes | Attachment uid. |