Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add a `GET /api/v1/agents` discovery endpoint with capability filtering

Open
  • Is something wrong?
#268 0 comments 0 reactions 0 assignees View on GitHub

@rupesh-kumar-sah is already working on this.

Since Oct 12, 2026.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
node.js, typescript
Domain
api, backend

Research direction

Start with the closed issue #56 for the scoring algorithm, then read src/discovery/agent-scoring.ts and src/discovery/agent-review.entity.ts to see what ranking inputs and any visibility field exist. The cursor utility is in src/common/pagination/. Add a list route for GET /api/v1/agents and a detail route for GET /api/v1/agents/:id, with a controller spec beside the existing agent-scoring.spec.ts. Done when filtering by capability and minimum score, default ranking, and bounded pagination are covered by passing specs.

Written by the indexing model from the issue text.

Description

enhancement help wanted intermediate

Problem

The README (lines 20-21) describes "Agent discovery & recommendation engine" as a core responsibility:

Index agent metadata, capabilities, provenance, and historical performance. Provide discovery endpoints and personalized recommendation/ranking APIs.

src/discovery/ has 8 files — agent-scoring.ts, agent-reviews.service.ts, agent-reviews.controller.ts, review.dto.ts, agent-review.entity.ts — but there is no agent listing or discovery endpoint. The reviews module covers ratings, not discovery.

Why it matters

Discovery is the entry point for the whole agent ecosystem. Without a way to list and filter agents by capability, a client cannot find agents to work with — it can only look up agents it already knows by id. The scoring and ranking logic in agent-scoring.ts exists but has no discovery surface to feed.

Suggested Direction

  1. Add GET /api/v1/agents with typed query parameters: capability, minScore, sortBy, limit, cursor.
  2. Reuse the cursor-pagination utility in src/common/pagination/ for consistency with the GraphQL gateway.
  3. Return agent summaries — id, name, capabilities, score, review count — not full agent records.
  4. Add a GET /api/v1/agents/:id endpoint for full details.
  5. Wire the scoring from agent-scoring.ts into the list response so results are ranked by default.
  6. Add colocated specs; src/discovery/ currently has agent-scoring.spec.ts and agent-reviews.service.spec.ts but no controller spec.

Constraints

  • Agent visibility may be scoped by tenant or role; check whether agent-review.entity.ts has a visibility field.
  • Capability filtering must be parameterised, not string-interpolated.
  • Pagination must be bounded.
  • The scoring algorithm is described in a closed issue (#56, "Agent Performance Scoring & Ranking Algorithm"); read it before designing the response shape.

Acceptance Criteria

  • GET /api/v1/agents returns a paginated, cursor-based list.
  • Filtering by capability and minimum score works.
  • Results are ranked by the existing scoring algorithm.
  • GET /api/v1/agents/:id returns full details for a single agent.
  • Pagination is bounded.
  • Colocated specs cover the controller and service.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.