# Search API

## Search Repositories

```
GET /api/v1/repos/search
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search keyword |
| `topic` | boolean | Search only in topics |
| `includeDesc` | boolean | Include description in search (default: true) |
| `uid` | integer | Filter by owner user ID |
| `priority_owner_id` | integer | Prioritize repos owned by this user |
| `team_id` | integer | Filter by team ID |
| `starredBy` | integer | Show repos starred by this user ID |
| `private` | boolean | Include private repos (requires auth) |
| `template` | boolean | Filter template repos |
| `archived` | boolean | Filter archived repos |
| `mode` | string | Search mode: `source`, `fork`, `mirror`, `collaborative` |
| `exclusive` | boolean | Match mode exclusively |
| `sort` | string | Sort by: `alpha`, `created`, `updated`, `size`, `id`, `stars`, `forks` |
| `order` | string | `asc` or `desc` |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# Basic keyword search
curl -s "${FORGEJO_URL}/api/v1/repos/search?q=webapp" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search by topic
curl -s "${FORGEJO_URL}/api/v1/repos/search?q=golang&topic=true" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search only source repos (not forks/mirrors), sorted by stars
curl -s "${FORGEJO_URL}/api/v1/repos/search?q=api&mode=source&sort=stars&order=desc" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search for repos by a specific owner
curl -s "${FORGEJO_URL}/api/v1/repos/search?uid={user_id}&sort=updated&order=desc" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search for template repos
curl -s "${FORGEJO_URL}/api/v1/repos/search?template=true&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search non-archived repos with keyword
curl -s "${FORGEJO_URL}/api/v1/repos/search?q=myproject&archived=false&includeDesc=true" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Find repos starred by a user
curl -s "${FORGEJO_URL}/api/v1/repos/search?starredBy=3&sort=stars&order=desc" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated search
curl -s "${FORGEJO_URL}/api/v1/repos/search?q=test&page=2&limit=20" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Search Issues Across Repos

```
GET /api/v1/repos/issues/search
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search keyword |
| `state` | string | `open`, `closed` |
| `labels` | string | Comma-separated label names |
| `milestones` | string | Comma-separated milestone names |
| `since` | string | Only issues updated after (ISO 8601) |
| `before` | string | Only issues updated before (ISO 8601) |
| `type` | string | `issues` or `pulls` |
| `priority_repo_id` | integer | Repository ID to prioritize in results |
| `review_requested` | boolean | Filter PRs where authenticated user's review was requested |
| `reviewed` | boolean | Filter PRs reviewed by the authenticated user |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# Search open issues across all repos
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?q=bug&state=open" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search by labels
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?labels=critical,security&state=open" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search only pull requests
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?q=refactor&type=pulls" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search issues updated since a date
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?since=2024-01-01T00:00:00Z&state=open" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search by milestone
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?milestones={milestone_name}&state=open" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Combined filters
curl -s "${FORGEJO_URL}/api/v1/repos/issues/search?q=auth&state=open&labels=enhancement&type=issues&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Search Users

```
GET /api/v1/users/search
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search keyword |
| `uid` | integer | Filter by user ID |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# Search users by keyword
curl -s "${FORGEJO_URL}/api/v1/users/search?q=john" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Get specific user by ID
curl -s "${FORGEJO_URL}/api/v1/users/search?uid={user_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated user search
curl -s "${FORGEJO_URL}/api/v1/users/search?q=dev&page=1&limit=20" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Search Topics

```
GET /api/v1/topics/search
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search keyword |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# Search topics
curl -s "${FORGEJO_URL}/api/v1/topics/search?q=golang" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated topic search
curl -s "${FORGEJO_URL}/api/v1/topics/search?q=web&page=1&limit=50" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Search Organization Teams

```
GET /api/v1/orgs/{org}/teams/search
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `q` | string | Search keyword |
| `include_desc` | boolean | Include team descriptions in search |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# Search teams in an org
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/teams/search?q=backend" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Search including descriptions
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/teams/search?q=deploy&include_desc=true" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated team search
curl -s "${FORGEJO_URL}/api/v1/orgs/{org}/teams/search?q=dev&page=1&limit=20" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Response Notes

All search endpoints return paginated results. The response headers include:

- `X-Total-Count` - Total number of matching results
- `X-PageCount` - Total number of pages
- `X-Page` - Current page number
- `X-PerPage` - Items per page
- `X-HasMore` - Whether more pages exist

The response body wraps results in a `data` array for repo search:

```json
{
  "ok": true,
  "data": [
    { "id": 1, "full_name": "org/repo", ... }
  ]
}
```

Issue and user searches return flat arrays.
