openapi: 3.1.0 info: title: ResearchService API version: 1.0.0 paths: /api/research/v1/list-arxiv-papers: get: tags: - ResearchService summary: ListArxivPapers description: ListArxivPapers retrieves recent papers from arXiv. operationId: ListArxivPapers parameters: - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: category in: query description: arXiv category filter (e.g., "cs.AI"). Empty returns all tracked categories. required: false schema: type: string - name: query in: query description: Search query for paper titles and abstracts. required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListArxivPapersResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/research/v1/list-trending-repos: get: tags: - ResearchService summary: ListTrendingRepos description: ListTrendingRepos retrieves trending repositories from GitHub. operationId: ListTrendingRepos parameters: - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: language in: query description: Programming language filter (e.g., "python", "typescript"). required: false schema: type: string - name: period in: query description: Trending period (e.g., "daily", "weekly"). Defaults to "daily". required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListTrendingReposResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/research/v1/list-hackernews-items: get: tags: - ResearchService summary: ListHackernewsItems description: ListHackernewsItems retrieves top stories from Hacker News. operationId: ListHackernewsItems parameters: - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: feed_type in: query description: 'Feed type: "top", "new", "best", "ask", "show". Defaults to "top".' required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListHackernewsItemsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' /api/research/v1/list-tech-events: get: tags: - ResearchService summary: ListTechEvents description: ListTechEvents retrieves tech events from Techmeme ICS, dev.events RSS, and curated sources. operationId: ListTechEvents parameters: - name: type in: query description: 'Event type filter: "all", "conferences", "earnings", "ipo", "other". Empty = all.' required: false schema: type: string - name: mappable in: query description: Only events with non-virtual coordinates. required: false schema: type: boolean - name: limit in: query description: Max events to return (0 = unlimited). required: false schema: type: integer format: int32 - name: days in: query description: Events within N days from now (0 = unlimited). required: false schema: type: integer format: int32 responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListTechEventsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListArxivPapersRequest: type: object properties: pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. category: type: string description: arXiv category filter (e.g., "cs.AI"). Empty returns all tracked categories. query: type: string description: Search query for paper titles and abstracts. description: ListArxivPapersRequest specifies filters for retrieving arXiv papers. ListArxivPapersResponse: type: object properties: papers: type: array items: $ref: '#/components/schemas/ArxivPaper' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListArxivPapersResponse contains arXiv papers matching the request. ArxivPaper: type: object properties: id: type: string minLength: 1 description: arXiv paper ID (e.g., "2401.12345"). title: type: string minLength: 1 description: Paper title. summary: type: string description: Paper abstract (may be truncated). authors: type: array items: type: string description: Author names. categories: type: array items: type: string description: arXiv categories (e.g., "cs.AI", "cs.LG"). publishedAt: type: integer format: int64 description: 'Publication time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' url: type: string description: URL to the paper. required: - id - title description: ArxivPaper represents a research paper from arXiv. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results. ListTrendingReposRequest: type: object properties: pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. language: type: string description: Programming language filter (e.g., "python", "typescript"). period: type: string description: Trending period (e.g., "daily", "weekly"). Defaults to "daily". description: ListTrendingReposRequest specifies filters for retrieving trending GitHub repos. ListTrendingReposResponse: type: object properties: repos: type: array items: $ref: '#/components/schemas/GithubRepo' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListTrendingReposResponse contains trending GitHub repositories. GithubRepo: type: object properties: fullName: type: string minLength: 1 description: Repository full name (e.g., "owner/repo"). description: type: string description: Repository description. language: type: string description: Primary programming language. stars: type: integer minimum: 0 format: int32 description: Total star count. starsToday: type: integer format: int32 description: Stars gained in the trending period. forks: type: integer format: int32 description: Number of open forks. url: type: string description: Repository URL. required: - fullName description: GithubRepo represents a trending repository from GitHub. ListHackernewsItemsRequest: type: object properties: pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. feedType: type: string description: 'Feed type: "top", "new", "best", "ask", "show". Defaults to "top".' description: ListHackernewsItemsRequest specifies filters for retrieving Hacker News items. ListHackernewsItemsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/HackernewsItem' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListHackernewsItemsResponse contains Hacker News items. HackernewsItem: type: object properties: id: type: integer format: int32 description: HN item ID. title: type: string minLength: 1 description: Item title. url: type: string description: URL (empty for Ask HN / Show HN text posts). score: type: integer minimum: 0 format: int32 description: Upvote score. commentCount: type: integer format: int32 description: Number of comments. by: type: string description: Author username. submittedAt: type: integer format: int64 description: 'Submission time, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' required: - title description: HackernewsItem represents an item from Hacker News. ListTechEventsRequest: type: object properties: type: type: string description: 'Event type filter: "all", "conferences", "earnings", "ipo", "other". Empty = all.' mappable: type: boolean description: Only events with non-virtual coordinates. limit: type: integer maximum: 500 minimum: 0 format: int32 description: Max events to return (0 = unlimited). days: type: integer minimum: 0 format: int32 description: Events within N days from now (0 = unlimited). description: ListTechEventsRequest specifies filters for retrieving tech events. ListTechEventsResponse: type: object properties: success: type: boolean description: Whether the request succeeded. count: type: integer format: int32 description: Total event count in response. conferenceCount: type: integer format: int32 description: Number of conference-type events. mappableCount: type: integer format: int32 description: Number of mappable (non-virtual with coords) events. lastUpdated: type: string description: ISO 8601 timestamp of last update. events: type: array items: $ref: '#/components/schemas/TechEvent' error: type: string description: Error message if success is false. description: ListTechEventsResponse contains tech events matching the request. TechEvent: type: object properties: id: type: string description: Unique event identifier. title: type: string description: Event title. type: type: string description: 'Event type: "conference", "earnings", "ipo", "other".' location: type: string description: Location description. coords: $ref: '#/components/schemas/TechEventCoords' startDate: type: string description: Start date (YYYY-MM-DD). endDate: type: string description: End date (YYYY-MM-DD). url: type: string description: Event URL. source: type: string description: 'Source: "techmeme", "dev.events", "curated".' description: type: string description: Event description. description: TechEvent represents a single tech event (conference, earnings, IPO, etc.). TechEventCoords: type: object properties: lat: type: number format: double description: Latitude. lng: type: number format: double description: Longitude. country: type: string description: Country name or code. original: type: string description: Original location string before normalization. virtual: type: boolean description: Whether this is a virtual/online event. description: TechEventCoords contains geocoded location data for a tech event.