# Miscellaneous API

Utility endpoints for gitignore templates, license templates, markdown rendering, instance info, and signing keys.

---

## Gitignore Templates

### GET `/gitignore/templates`

List all available gitignore template names. Returns an array of strings.

```bash
curl -s "${FORGEJO_URL}/api/v1/gitignore/templates" \
  -H "Authorization: token ${FORGEJO_PAT}"
# Response: ["Actionscript", "Ada", "Agda", ..., "Go", ..., "Node", ..., "Python", ...]
```

### GET `/gitignore/templates/{name}`

Get a specific gitignore template by name. Returns an object with `name` and `source` fields.

```bash
# Get Python gitignore template
curl -s "${FORGEJO_URL}/api/v1/gitignore/templates/Python" \
  -H "Authorization: token ${FORGEJO_PAT}"
# Response: {"name": "Python", "source": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n..."}

# Get Go gitignore template
curl -s "${FORGEJO_URL}/api/v1/gitignore/templates/Go" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Get Node gitignore template
curl -s "${FORGEJO_URL}/api/v1/gitignore/templates/Node" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## License Templates

### GET `/licenses`

List all available license templates. Returns an array of objects.

**Response entry fields:**
- `key` - License identifier (e.g., `"mit"`, `"apache-2.0"`)
- `name` - Human-readable name (e.g., `"MIT License"`)
- `url` - SPDX URL for the license

```bash
curl -s "${FORGEJO_URL}/api/v1/licenses" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### GET `/licenses/{name}`

Get a specific license by its key. Returns full license details including the template body.

**Response fields:**
- `key`, `name`, `url` (same as list entry)
- `spdx_id` - SPDX identifier
- `body` - Full license text template
- `implementation` - Usage notes
- `permissions`, `conditions`, `limitations` - Arrays of strings

```bash
# Get MIT license details
curl -s "${FORGEJO_URL}/api/v1/licenses/MIT" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Get Apache 2.0 license
curl -s "${FORGEJO_URL}/api/v1/licenses/Apache-2.0" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Get GPL-3.0 license
curl -s "${FORGEJO_URL}/api/v1/licenses/GPL-3.0" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Markdown / Markup Rendering

### POST `/markdown`

Render markdown text as HTML.

**Request body (JSON):**
| Field | Type | Description |
|-------|------|-------------|
| `Text` | string | Markdown content to render |
| `Mode` | string | Rendering mode: `"gfm"` (GitHub Flavored Markdown), `"comment"`, or `"document"` |
| `Context` | string | Repository context for resolving relative links (e.g., `"owner/repo"`) |
| `Wiki` | boolean | Whether to use wiki link syntax |

**Response:** HTML string (Content-Type: text/html)

```bash
# Render GFM markdown
curl -s -X POST "${FORGEJO_URL}/api/v1/markdown" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"Text": "# Hello\n**bold** and *italic*\n- list item", "Mode": "gfm"}'

# Render markdown with repo context (resolves relative links)
curl -s -X POST "${FORGEJO_URL}/api/v1/markdown" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"Text": "See issue #1 and @user", "Mode": "comment", "Context": "{owner}/{repo}"}'
```

### POST `/markdown/raw`

Render raw markdown text as HTML. The request body is plain text, not JSON.

**Request:** Raw markdown (Content-Type: text/plain)
**Response:** HTML string (Content-Type: text/html)

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/markdown/raw" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: text/plain" \
  -d '# Hello World

This is **raw** markdown rendering.'
```

### POST `/markup`

Render markup content as HTML. Supports multiple markup formats beyond just markdown.

**Request body (JSON):**
| Field | Type | Description |
|-------|------|-------------|
| `Text` | string | Markup content to render |
| `Mode` | string | Rendering mode: `"gfm"`, `"comment"`, or `"document"` |
| `Context` | string | Repository context for resolving relative links |
| `Wiki` | boolean | Whether to use wiki link syntax |
| `FilePath` | string | Virtual file path to determine markup engine (e.g., `"doc.md"`, `"doc.org"`, `"doc.rst"`) |

```bash
curl -s -X POST "${FORGEJO_URL}/api/v1/markup" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"Text": "# Markup Test\nContent here", "Mode": "gfm", "Context": "{owner}/{repo}", "Wiki": false, "FilePath": "doc.md"}'
```

---

## NodeInfo

### GET `/nodeinfo`

Returns NodeInfo 2.1 data about the Forgejo instance.

**Response fields:**
| Field | Description |
|-------|-------------|
| `software.name` | Software name (e.g., `"forgejo"`) |
| `software.version` | Software version string |
| `protocols` | Supported protocols (e.g., `["activitypub"]`) |
| `usage.users.total` | Total registered users |
| `usage.users.activeMonth` | Users active in the last month |
| `usage.users.activeHalfyear` | Users active in the last 6 months |
| `usage.localPosts` | Total number of repositories |
| `openRegistrations` | Whether new user registration is open |

```bash
curl -s "${FORGEJO_URL}/api/v1/nodeinfo" | jq '.'
```

**Example response:**
```json
{
  "version": "2.1",
  "software": {
    "name": "forgejo",
    "version": "14.0.4+gitea-1.22.0"
  },
  "protocols": ["activitypub"],
  "usage": {
    "users": {
      "total": 150,
      "activeMonth": 42,
      "activeHalfyear": 98
    },
    "localPosts": 500
  },
  "openRegistrations": true
}
```

---

## Version

### GET `/version`

Returns the running application version.

```bash
curl -s "${FORGEJO_URL}/api/v1/version"
# Response: {"version":"14.0.4+gitea-1.22.0"}
```

---

## Signing Keys

### GET `/signing-key.gpg`

Get the instance-level GPG signing key used for signing commits.

```bash
curl -s "${FORGEJO_URL}/api/v1/signing-key.gpg" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### GET `/signing-key.ssh`

Get the instance-level SSH signing key.

```bash
curl -s "${FORGEJO_URL}/api/v1/signing-key.ssh" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Endpoint Summary

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/gitignore/templates` | List gitignore template names |
| GET | `/gitignore/templates/{name}` | Get specific gitignore template |
| GET | `/licenses` | List license templates |
| GET | `/licenses/{name}` | Get specific license details |
| POST | `/markdown` | Render markdown as HTML |
| POST | `/markdown/raw` | Render raw markdown as HTML |
| POST | `/markup` | Render markup as HTML |
| GET | `/nodeinfo` | Instance NodeInfo 2.1 data |
| GET | `/version` | Application version |
| GET | `/signing-key.gpg` | Instance GPG signing key |
| GET | `/signing-key.ssh` | Instance SSH signing key |
