{ "schemes": [], "swagger": "2.0", "info": { "description": "This is the API for the ORKL Threat Intelligence Library.", "title": "ORKL API", "contact": {}, "version": "1.1" }, "host": "orkl.eu", "basePath": "/api/v1", "paths": { "/library/entries": { "get": { "description": "Retrieves a paginated list of intelligence reports and library entries. Supports sorting by various date fields.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "List Library Entries", "parameters": [ { "type": "integer", "description": "limit entries", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset entries", "name": "offset", "in": "query" }, { "type": "string", "default": "created_at", "description": "order by date field - allowed: 'created_at', 'updated_at', 'file_creation_date', 'file_modification_date'", "name": "order_by", "in": "query" }, { "type": "string", "default": "desc", "description": "order - allowed: 'asc', 'desc'", "name": "order", "in": "query" }, { "enum": [ "pdf", "web" ], "type": "string", "description": "filter by ingestion origin - allowed: 'pdf', 'web'", "name": "origin", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/ExtendedLibraryEntry" } } } } ] } }, "500": { "description": "Internal server error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/entry/sha1/{hash}": { "get": { "description": "Retrieves a specific intelligence report based on the SHA-1 hash of its associated file.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "Get Library Entry By Hash", "parameters": [ { "type": "string", "description": "entry SHA1 hash", "name": "hash", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/ExtendedLibraryEntry" } } } ] } }, "400": { "description": "Invalid SHA1 hash format", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "404": { "description": "Library entry not found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "500": { "description": "Internal server error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/entry/{uuid}": { "get": { "description": "Retrieves a specific intelligence report based on its unique UUID identifier.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "Get Library Entry By ID", "parameters": [ { "type": "string", "description": "entry ID (uuid)", "name": "uuid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/ExtendedLibraryEntry" } } } ] } }, "400": { "description": "Invalid UUID format", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "404": { "description": "Library entry not found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "500": { "description": "Internal server error processing UUID", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/info": { "get": { "description": "returns library statistics including total entries, threat actors, sources, latest version and last update time.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "Get Library Information", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/InfoAnswer" } } } ] } }, "500": { "description": "Internal server error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/search": { "get": { "description": "Performs a full-text search across all reports in the ORKL intelligence library.\nSupports exact phrase matching by wrapping terms in quotes (e.g., \"threat actor\").", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "Search Library Entries", "parameters": [ { "type": "string", "description": "query string", "name": "query", "in": "query", "required": true }, { "type": "boolean", "default": false, "description": "return full library entry including plain-text", "name": "full", "in": "query" }, { "type": "integer", "default": 1000, "description": "limit the number of returned entries", "name": "limit", "in": "query" }, { "enum": [ "pdf", "web" ], "type": "string", "description": "filter by ingestion origin - allowed: 'pdf', 'web'", "name": "origin", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/ExtendedLibraryEntry" } } } } ] } }, "406": { "description": "Empty query string provided", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "500": { "description": "Search backend error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/version": { "get": { "description": "Retrieves information about the most recent library version and its release timestamp.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "Get Latest Library Version", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/LibraryVersion" } } } ] } }, "404": { "description": "No library version found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/library/version/entries": { "get": { "description": "Retrieves a paginated history of all published library versions, indicating when the library dataset was updated.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Library" ], "summary": "List Library Versions", "parameters": [ { "type": "integer", "description": "limit entries", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset entries", "name": "offset", "in": "query" }, { "type": "string", "default": "desc", "description": "order - allowed: 'asc', 'desc'", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/VersionsResponse" } } } ] } }, "404": { "description": "No library versions found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/news/entries": { "get": { "description": "Retrieves a paginated list of news items ingested from curated threat-intel RSS feeds, with tagged threat actors. Default order is a hot score combining source weight, threat-actor mentions and recency.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "News" ], "summary": "List News Items", "parameters": [ { "type": "integer", "default": 20, "description": "limit entries (max 100)", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset entries", "name": "offset", "in": "query" }, { "type": "string", "default": "rank", "description": "order - allowed: 'rank' (hot score), 'published_at' (newest first)", "name": "order_by", "in": "query" }, { "type": "string", "description": "filter by feed name, e.g. 'BleepingComputer'", "name": "feed_name", "in": "query" } ], "responses": { "200": { "description": "response additionally carries a 'total' field with the unpaginated item count", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/NewsItem" } } } } ] } }, "500": { "description": "Internal server error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/source/entries": { "get": { "description": "Retrieves a comprehensive list of all referenced intelligence sources (e.g., cybersecurity vendors, blogs) and their respective metadata.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Source" ], "summary": "List Sources", "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/Source" } } } } ] } }, "404": { "description": "No sources found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/source/entry/{uuid}": { "get": { "description": "Retrieves specific information about an intelligence source based on its unique UUID. Can optionally include the full list of associated reports.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Source" ], "summary": "Get Source By ID", "parameters": [ { "type": "string", "description": "entry ID (uuid)", "name": "uuid", "in": "path", "required": true }, { "type": "boolean", "default": false, "description": "return full object including reports", "name": "full", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/Source" } } } ] } }, "400": { "description": "Invalid UUID format", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "404": { "description": "Source not found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "500": { "description": "Internal server error", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/ta/entries": { "get": { "description": "Retrieves a list of documented threat actors in the library, including their known aliases and sources. Unpaginated by default for backwards compatibility; pass 'limit' to page through the results.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ThreatActor" ], "summary": "List Threat Actors", "parameters": [ { "type": "integer", "description": "limit entries - omit to return all threat actors", "name": "limit", "in": "query" }, { "type": "integer", "description": "offset entries", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/ThreatActor" } } } } ] } }, "404": { "description": "No threat actors found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } }, "/ta/entry/{uuid}": { "get": { "description": "Retrieves detailed information about a specific threat actor, including their aliases and associated reports, based on their unique UUID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ThreatActor" ], "summary": "Get Threat Actor By ID", "parameters": [ { "type": "string", "description": "entry ID (uuid)", "name": "uuid", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/definitions/ThreatActor" } } } ] } }, "400": { "description": "Invalid UUID format", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "404": { "description": "Threat actor not found", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } }, "500": { "description": "Internal server error processing UUID", "schema": { "allOf": [ { "$ref": "#/definitions/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } } } }, "definitions": { "ApiResponse": { "type": "object", "properties": { "data": {}, "message": { "type": "string" }, "status": { "type": "string" } } }, "ExtendedLibraryEntry": { "type": "object", "properties": { "authors": { "type": "string" }, "created_at": { "type": "string" }, "deleted_at": {}, "extraction_quality": { "type": "number" }, "file_creation_date": { "type": "string" }, "file_modification_date": { "type": "string" }, "file_size": { "type": "integer" }, "files": { "$ref": "#/definitions/ReportFiles" }, "id": { "type": "string" }, "language": { "type": "string" }, "llm_title": { "type": "string" }, "origins": { "description": "Origins lists the distinct ingestion origins this entry was seen with.\nEach value is either \"pdf\" (direct PDF download) or \"web\" (web page\nrendered to PDF via Websnap). Usually a single value; may contain both\nif the same SHA1 arrived through both pipelines.", "type": "array", "items": { "type": "string" }, "example": [ "pdf" ] }, "plain_text": { "type": "string" }, "references": { "type": "array", "items": { "type": "string" } }, "report_names": { "type": "array", "items": { "type": "string" } }, "sha1_hash": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "threat_actors": { "type": "array", "items": { "$ref": "#/definitions/ThreatActor" } }, "title": { "type": "string" }, "ts_created_at": { "type": "integer" }, "ts_creation_date": { "type": "integer" }, "ts_modification_date": { "type": "integer" }, "ts_updated_at": { "type": "integer" }, "updated_at": { "type": "string" } } }, "InfoAnswer": { "type": "object", "properties": { "library_entries": { "type": "integer" }, "library_last_update": { "type": "string" }, "library_version": { "type": "integer" }, "source_entries": { "type": "integer" }, "threat_actor_entries": { "type": "integer" } } }, "LibraryEntry": { "type": "object", "properties": { "authors": { "type": "string" }, "created_at": { "type": "string" }, "deleted_at": {}, "extraction_quality": { "type": "number" }, "file_creation_date": { "type": "string" }, "file_modification_date": { "type": "string" }, "file_size": { "type": "integer" }, "id": { "type": "string" }, "language": { "type": "string" }, "llm_title": { "type": "string" }, "origins": { "description": "Origins lists the distinct ingestion origins this entry was seen with.\nEach value is either \"pdf\" (direct PDF download) or \"web\" (web page\nrendered to PDF via Websnap). Usually a single value; may contain both\nif the same SHA1 arrived through both pipelines.", "type": "array", "items": { "type": "string" }, "example": [ "pdf" ] }, "plain_text": { "type": "string" }, "references": { "type": "array", "items": { "type": "string" } }, "report_names": { "type": "array", "items": { "type": "string" } }, "sha1_hash": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "threat_actors": { "type": "array", "items": { "$ref": "#/definitions/ThreatActor" } }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "LibraryVersion": { "type": "object", "properties": { "createdAt": { "type": "string" }, "created_library_entries": { "type": "array", "items": { "type": "string" } }, "created_ta_entries": { "type": "array", "items": { "type": "string" } }, "date": { "type": "string" }, "deletedAt": {}, "id": { "type": "integer" }, "updatedAt": { "type": "string" } } }, "NewsItem": { "type": "object", "properties": { "base_score": { "type": "number" }, "created_at": { "type": "string" }, "deleted_at": {}, "feed_group": { "type": "string" }, "feed_name": { "type": "string" }, "guid": { "type": "string" }, "id": { "type": "string" }, "link": { "type": "string" }, "published_at": { "type": "string" }, "summary": { "type": "string" }, "threat_actors": { "type": "array", "items": { "$ref": "#/definitions/ThreatActor" } }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "ReportFiles": { "type": "object", "properties": { "img": { "type": "string" }, "pdf": { "type": "string" }, "text": { "type": "string" } } }, "RichLibVersion": { "type": "object", "properties": { "ID": { "type": "integer" }, "created_library_entries": { "type": "array", "items": { "$ref": "#/definitions/VersionEntryRef" } }, "created_ta_entries": { "type": "array", "items": { "$ref": "#/definitions/VersionEntryRef" } }, "date": { "type": "string" } } }, "Source": { "type": "object", "properties": { "created_at": { "type": "string" }, "deleted_at": {}, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "reports": { "type": "array", "items": { "$ref": "#/definitions/LibraryEntry" } }, "updated_at": { "type": "string" }, "url": { "type": "string" } } }, "ThreatActor": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "deleted_at": {}, "id": { "type": "string" }, "main_name": { "type": "string" }, "reports": { "type": "array", "items": { "$ref": "#/definitions/LibraryEntry" } }, "source_id": { "type": "string" }, "source_name": { "type": "string" }, "tools": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" } } }, "VersionEntryRef": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "VersionsResponse": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/definitions/RichLibVersion" } }, "latest": { "type": "integer" } } } } }