ResearchService.openapi.yaml

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.