openapi-3.1.json
Rama main · réplica de lectura del repositorio original.
{
"openapi": "3.1.0",
"info": {
"title": "Jiro Search API",
"version": "0.4.0",
"description": "Local-first web search, scraping, and social media intelligence platform. Supports 9+ search engines, 12 social platforms, hybrid search, structured extraction, and smart intent routing.",
"contact": {
"name": "Jiro Team",
"url": "https://github.com/DevAnimecx/jiro"
},
"license": {
"name": "MIT",
"url": "https://opensource.org/licenses/MIT"
}
},
"servers": [
{
"url": "http://localhost:8000",
"description": "Local development"
},
{
"url": "https://api.jiro.dev",
"description": "Production"
}
],
"tags": [
{
"name": "search",
"description": "Web search across multiple engines"
},
{
"name": "scrape",
"description": "URL content extraction"
},
{
"name": "social",
"description": "Social media scraping and search"
},
{
"name": "smart",
"description": "Smart search with intent routing"
},
{
"name": "structured",
"description": "Structured data extraction"
},
{
"name": "plugins",
"description": "Plugin management"
},
{
"name": "monitor",
"description": "Server monitoring and health"
}
],
"paths": {
"/v1/search": {
"post": {
"tags": [
"search"
],
"summary": "Search the web",
"description": "Search across multiple engines with filtering, biasing, and hybrid ranking.",
"operationId": "search",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limit exceeded"
}
}
}
},
"/v1/search/multi": {
"post": {
"tags": [
"search"
],
"summary": "Multi-query search",
"description": "Execute multiple search queries in parallel.",
"operationId": "searchMulti",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MultiQueryRequest"
}
}
}
},
"responses": {
"200": {
"description": "Multi-query results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MultiQueryResponse"
}
}
}
}
}
}
},
"/v1/scrape": {
"post": {
"tags": [
"scrape"
],
"summary": "Scrape a URL",
"description": "Extract content from a URL as markdown, text, or structured data.",
"operationId": "scrape",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScrapeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Scraped content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScrapeResponse"
}
}
}
},
"400": {
"description": "Invalid URL"
}
}
}
},
"/v1/social": {
"post": {
"tags": [
"social"
],
"summary": "Scrape social media URL",
"description": "Scrape a social media post, profile, or thread from 12 supported platforms.",
"operationId": "socialScrape",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialScrapeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Social content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialResponse"
}
}
}
},
"400": {
"description": "Unsupported platform"
}
}
}
},
"/v1/social/batch": {
"post": {
"tags": [
"social"
],
"summary": "Batch scrape social URLs",
"description": "Scrape multiple social media URLs in parallel.",
"operationId": "socialBatch",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialBatchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Batch results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialBatchResponse"
}
}
}
}
}
}
},
"/v1/social/platforms": {
"get": {
"tags": [
"social"
],
"summary": "List supported social platforms",
"operationId": "socialPlatforms",
"responses": {
"200": {
"description": "Platform list",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"/v1/social/search": {
"post": {
"tags": [
"social"
],
"summary": "Search social platforms",
"description": "Search across multiple social platforms simultaneously.",
"operationId": "socialSearch",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialSearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialSearchResponse"
}
}
}
}
}
}
},
"/v1/social/search/everywhere": {
"post": {
"tags": [
"social"
],
"summary": "Search all social platforms",
"description": "Search across all 12 supported social platforms.",
"operationId": "socialSearchEverywhere",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialSearchEverywhereRequest"
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialSearchResponse"
}
}
}
}
}
}
},
"/v1/smart": {
"post": {
"tags": [
"smart"
],
"summary": "Smart search with intent routing",
"description": "Automatically detect search intent and route to the appropriate handler.",
"operationId": "smartSearch",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartRequest"
}
}
}
},
"responses": {
"200": {
"description": "Smart search result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartResponse"
}
}
}
}
}
}
},
"/v1/smart/classify": {
"post": {
"tags": [
"smart"
],
"summary": "Classify search intent",
"description": "Classify the intent of a search query without executing it.",
"operationId": "smartClassify",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartClassifyRequest"
}
}
}
},
"responses": {
"200": {
"description": "Intent classification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SmartClassifyResponse"
}
}
}
}
}
}
},
"/v1/structured/extract": {
"post": {
"tags": [
"structured"
],
"summary": "Extract structured data",
"description": "Extract structured data from search results using JSON schema.",
"operationId": "structuredExtract",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StructuredExtractRequest"
}
}
}
},
"responses": {
"200": {
"description": "Extracted data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StructuredExtractResponse"
}
}
}
}
}
}
},
"/v1/plugins": {
"get": {
"tags": [
"plugins"
],
"summary": "List plugins",
"operationId": "listPlugins",
"responses": {
"200": {
"description": "Plugin list",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PluginInfo"
}
}
}
}
}
}
}
},
"/v1/plugins/{name}": {
"get": {
"tags": [
"plugins"
],
"summary": "Get plugin info",
"operationId": "getPlugin",
"parameters": [
{
"name": "name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Plugin info",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PluginInfo"
}
}
}
},
"404": {
"description": "Plugin not found"
}
}
}
},
"/v1/monitor/status": {
"get": {
"tags": [
"monitor"
],
"summary": "Get server status",
"operationId": "monitorStatus",
"responses": {
"200": {
"description": "Server status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerStatus"
}
}
}
}
}
}
},
"/v1/monitor/health": {
"get": {
"tags": [
"monitor"
],
"summary": "Health check",
"operationId": "monitorHealth",
"responses": {
"200": {
"description": "Health status",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"components": {
"SearchRequest": {
"type": "object",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"description": "Search query"
},
"engine": {
"type": "string",
"enum": [
"google",
"bing",
"brave",
"duckduckgo",
"youtube",
"amazon",
"ebay",
"yandex",
"baidu"
],
"default": "google"
},
"type": {
"type": "string",
"enum": [
"web",
"images",
"news",
"videos",
"shopping",
"places"
],
"default": "web"
},
"max_results": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
"language": {
"type": "string",
"default": "en"
},
"location": {
"type": "string",
"default": "us"
},
"time_range": {
"type": "string",
"enum": [
"any",
"day",
"week",
"month",
"year"
],
"default": "any"
},
"safe_search": {
"type": "boolean",
"default": true
},
"depth": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Crawl depth"
},
"include_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"bias_domains": {
"type": "object",
"additionalProperties": {
"type": "number"
}
},
"freshness": {
"type": "string",
"enum": [
"any",
"day",
"week",
"month",
"year"
]
},
"category": {
"type": "string"
},
"hybrid": {
"type": "boolean",
"description": "Enable hybrid search"
},
"answer": {
"type": "boolean",
"description": "Generate synthesized answer"
},
"highlights": {
"type": "boolean",
"description": "Include highlights"
}
}
},
"SearchResponse": {
"type": "object",
"properties": {
"search_metadata": {
"type": "object"
},
"organic_results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganicResult"
}
},
"answer": {
"type": "string",
"description": "Synthesized answer"
},
"highlights": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_query": {
"type": "object",
"description": "Multi-query results"
}
}
},
"OrganicResult": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"link": {
"type": "string",
"format": "uri"
},
"snippet": {
"type": "string"
},
"position": {
"type": "integer"
},
"source": {
"type": "string"
},
"relevance": {
"type": "number",
"description": "Relevance score 0-1"
},
"highlights": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"MultiQueryRequest": {
"type": "object",
"required": [
"q"
],
"properties": {
"q": {
"type": "string"
},
"num_variations": {
"type": "integer",
"minimum": 2,
"maximum": 10,
"default": 3
},
"engine": {
"type": "string"
},
"max_results": {
"type": "integer"
}
}
},
"MultiQueryResponse": {
"type": "object",
"properties": {
"queries": {
"type": "array",
"items": {
"type": "string"
}
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchResponse"
}
},
"merged": {
"$ref": "#/components/schemas/SearchResponse"
}
}
},
"ScrapeRequest": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"format": {
"type": "string",
"enum": [
"markdown",
"text",
"html",
"json"
],
"default": "markdown"
},
"include_metadata": {
"type": "boolean",
"default": true
}
}
},
"ScrapeResponse": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"content": {
"type": "string"
},
"metadata": {
"type": "object"
},
"links": {
"type": "array",
"items": {
"type": "string"
}
},
"images": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SocialScrapeRequest": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Social media URL"
}
}
},
"SocialResponse": {
"type": "object",
"properties": {
"platform": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"post",
"profile",
"thread",
"comment"
]
},
"data": {
"type": "object"
},
"scraped_at": {
"type": "string",
"format": "date-time"
}
}
},
"SocialBatchRequest": {
"type": "object",
"required": [
"urls"
],
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"maxItems": 50
}
}
},
"SocialBatchResponse": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SocialResponse"
}
},
"total": {
"type": "integer"
},
"failed": {
"type": "integer"
}
}
},
"SocialSearchRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string"
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
}
},
"SocialSearchEverywhereRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
}
},
"SocialSearchResponse": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SocialResponse"
}
},
"total": {
"type": "integer"
}
}
},
"SmartRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"web",
"images",
"news",
"videos",
"shopping"
],
"default": "web"
},
"max_results": {
"type": "integer",
"default": 10
},
"schema": {
"type": "object",
"description": "JSON Schema for structured extraction"
}
}
},
"SmartResponse": {
"type": "object",
"properties": {
"intent": {
"type": "string"
},
"target": {
"type": "string"
},
"results": {
"type": "object"
}
}
},
"SmartClassifyRequest": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string"
}
}
},
"SmartClassifyResponse": {
"type": "object",
"properties": {
"query": {
"type": "string"
},
"intent": {
"type": "string"
},
"confidence": {
"type": "number"
},
"target": {
"type": "string"
},
"social_platform": {
"type": "string"
},
"category": {
"type": "string"
},
"reasoning": {
"type": "string"
}
}
},
"StructuredExtractRequest": {
"type": "object",
"required": [
"query",
"schema"
],
"properties": {
"query": {
"type": "string"
},
"schema": {
"type": "object",
"description": "JSON Schema for desired output"
},
"engine": {
"type": "string"
},
"max_results": {
"type": "integer"
}
}
},
"StructuredExtractResponse": {
"type": "object",
"properties": {
"data": {
"type": "array"
},
"schema": {
"type": "object"
},
"extraction_method": {
"type": "string"
}
}
},
"PluginInfo": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"version": {
"type": "string"
},
"author": {
"type": "string"
},
"description": {
"type": "string"
},
"homepage": {
"type": "string"
}
}
},
"ServerStatus": {
"type": "object",
"properties": {
"version": {
"type": "string"
},
"engines": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PluginInfo"
}
},
"health": {
"type": "object"
},
"cache_enabled": {
"type": "boolean"
},
"plugins_enabled": {
"type": "boolean"
}
}
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"status_code": {
"type": "integer"
}
}
}
},
"security": [
{
"ApiKeyAuth": []
},
{
"BearerAuth": []
}
]
}