{"openapi":"3.1.0","info":{"title":"Ideenatlas Semantic Search API","description":"Public API for AI agents and automated Deep Research.","version":"1.0.1"},"servers":[{"url":"https://ideenatlas.eu","description":"Production Server"}],"paths":{"/api/search":{"post":{"tags":["controller"],"summary":"Search semantically for scientific papers","description":"Searches the ideenatlas.eu vector database for scientific papers, related topic fields, and serendipitous connections.\nINSTRUCTION FOR THE 'query' PARAMETER: It MUST be a single, dense, factual paragraph extracting the core scientific idea. Use precise, objective scientific language (no conversational filler like 'The user wants...'), like a paper's abstract.\nAlways analyze the returned 'similarTopicFields' and 'serendipitousConnections' for deep research.\nThe API returns JSON by default. Append '?format=md' to receive a highly token-optimized Markdown document.\n","operationId":"searchIdeenatlas","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"json"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiSearchRequestDto"}}},"required":true},"responses":{"200":{"description":"Search and analysis were successful. Returns JSON by default or Markdown if requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiResponseDto"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request, e.g., the query was empty."},"500":{"description":"An internal server error occurred during processing."}},"x-openai-isConsequential":false}},"/api/search/view":{"get":{"tags":["controller"],"summary":"Semantic Search for Browsing Bots","description":"Searches the ideenatlas.eu vector database for scientific papers, related topic fields, and serendipitous connections.\nINSTRUCTION FOR THE 'query' PARAMETER: It MUST be a single, dense, factual paragraph extracting the core scientific idea. Use precise, objective scientific language (no conversational filler like 'The user wants...'), like a paper's abstract.\nAlways analyze the returned 'similarTopicFields' and 'serendipitousConnections' for deep research.\nThe API returns JSON by default. Append '?format=md' to receive a highly token-optimized Markdown document.\n","operationId":"searchIdeenatlasHTML","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/html":{"schema":{"type":"string"}}}}},"x-openai-isConsequential":false}},"/":{"get":{"tags":["controller"],"operationId":"apiRoot","parameters":[{"name":"!Accept","in":"header","schema":{"type":"string","enum":["text/html"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiManifestDto"}}}}}}},"/ai":{"get":{"summary":"AI Gateway","description":"Searches the ideenatlas.eu vector database for scientific papers, related topic fields, and serendipitous connections.\nINSTRUCTION FOR THE 'query' PARAMETER: It MUST be a single, dense, factual paragraph extracting the core scientific idea. Use precise, objective scientific language (no conversational filler like 'The user wants...'), like a paper's abstract.\nAlways analyze the returned 'similarTopicFields' and 'serendipitousConnections' for deep research.\nThe API returns JSON by default. Append '?format=md' to receive a highly token-optimized Markdown document.\n","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}},"x-openai-isConsequential":false}},"/impressum":{"get":{"summary":"Legal Notice","description":"Legal information about the provider.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}},"/privacy":{"get":{"summary":"Privacy Policy","description":"Information about data processing.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}},"/licenses":{"get":{"summary":"Licenses","description":"List of used open source licenses.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}},"/faq":{"get":{"summary":"FAQ","description":"Frequently Asked Questions page.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}},"/about":{"get":{"summary":"About","description":"Information about the Ideenatlas project.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}},"/api":{"get":{"summary":"API Info","description":"General information and documentation about the API.","responses":{"200":{"description":"HTML Page","content":{"text/html":{"schema":{"format":"html"}}}}}}}},"components":{"schemas":{"ApiSearchRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"The scientific query or idea summary to be analyzed. Please follow the detailed formatting guidelines provided in the endpoint description.","example":"Quantum computing algorithms for optimizing supply chain logistics in global trade."}}},"ClusterHierarchyItem":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the cluster, e.g., 'all_vectors-4-1'."},"name":{"type":"string","description":"The human-readable name of the cluster."},"score":{"type":"number","format":"double","description":"The confidence score (probability) that the query belongs to this cluster within its parent, generated by the HDBSCAN models."}}},"DetailedResult":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the document in the database."},"title":{"type":"string","description":"The title of the document."},"summary":{"type":"string","description":"The abstract or summary of the document."},"score":{"type":"number","format":"float","description":"A score from 0.0 to 1.0 indicating the relevance of this topic to the original query, based on the cosine similarity between input text vector and entries vector."},"contentUrl":{"type":"string","description":"A direct URL to the source of the document (e.g., an arXiv or PubMed page). If it does not work, search the internet for the title + summary."}}},"JsonApiResponseDto":{"type":"object","description":"The complete and detailed result of a semantic search query.","properties":{"summary":{"$ref":"#/components/schemas/Summary","description":"A high-level summary of the query and its most important findings."},"ownIdeaAnalysis":{"$ref":"#/components/schemas/OwnIdeaAnalysis","description":"Provides details about how the user's input query was categorized within the knowledge graph."},"similarTopicFields":{"type":"array","description":"A list of topic fields that are semantically very similar to the user's query. Do not judge by their names, look into the result papers.","items":{"$ref":"#/components/schemas/TopicField"}},"serendipitousConnections":{"type":"array","description":"A curated list of surprising yet relevant topic fields that are not obviously related to the query. These are meant to inspire new lines of thought. Do not judge by their names, look into the result papers.","items":{"$ref":"#/components/schemas/TopicField"}},"detailedSimilarResults":{"type":"array","description":"A list of the most relevant individual documents (e.g., scientific papers) found for the query.","items":{"$ref":"#/components/schemas/DetailedResult"}}}},"OwnIdeaAnalysis":{"type":"object","properties":{"clusterHierarchy":{"type":"array","description":"The hierarchical path through the knowledge graph that best represents the query, from broad topics to specific ones, predicted by HDBSCAN models.","items":{"$ref":"#/components/schemas/ClusterHierarchyItem"}}}},"Summary":{"type":"object","properties":{"inputTitle":{"type":"string","description":"A pure placeholder title."},"inputIdea":{"type":"string","description":"The original query text given to the API, all results are based on it."},"mainTopics":{"type":"array","description":"The topics identified for the user's query, they are hierarchical, predicted with HDBSCAN.","items":{"type":"string"}},"similarTopicFields":{"type":"array","description":"Summaries of the most similar topic fields.","items":{"$ref":"#/components/schemas/SummaryTopic"}},"serendipitousConnections":{"type":"array","description":"Summaries of the most relevant serendipitous connections.","items":{"$ref":"#/components/schemas/SummaryTopic"}}}},"SummaryTopic":{"type":"object","properties":{"name":{"type":"string","description":"The name of the cluster."},"description":{"type":"string","description":"A short description of the cluster's content."},"relevance":{"type":"number","format":"float","description":"A score from 0.0 to 1.0 indicating the relevance of this topic to the original query, based on the cosine similarity between input text vector and topic centroid vector. For the serendipitous clusters, the score is that from its top result, as it is more helpful in that case."}}},"TopicField":{"type":"object","properties":{"clusterId":{"type":"string","description":"The unique identifier of the cluster, e.g., 'all_vectors-4-1'."},"clusterName":{"type":"string","description":"The human-readable name of the cluster."},"relevanceScore":{"type":"number","format":"float","description":"A score from 0.0 to 1.0 indicating the relevance of this topic to the original query, based on the cosine similarity between input text vector and topic centroid vector. For the serendipitous clusters, the score is that from its top result, as it is more helpful in that case."},"summary":{"type":"string","description":"A short description of the cluster's content."},"results":{"type":"array","description":"A list of the most relevant documents found within this cluster.","items":{"$ref":"#/components/schemas/DetailedResult"}}}},"ApiManifestDto":{"type":"object","properties":{"apiName":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"openapiSpecUrl":{"type":"string"}}}}}}