ResearchService.openapi.json

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