{
  "openapi": "3.1.0",
  "info": {
    "title": "NotHoly API",
    "version": "1.0.0",
    "description": "OpenAI and Anthropic compatible inference, plus research routes for CVE, advisories, web and files. Prompts and responses are not stored. Amounts are decimal strings in USD.",
    "contact": {
      "url": "https://docs.notholy.com"
    }
  },
  "servers": [
    {
      "url": "https://api.notholy.com/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Inference"
    },
    {
      "name": "Models"
    },
    {
      "name": "Account"
    },
    {
      "name": "Research"
    }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "createChatCompletion",
        "summary": "Chat completion (OpenAI format)",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              },
              "example": {
                "model": "notholy-pulse",
                "messages": [
                  {
                    "role": "user",
                    "content": "Explain IDOR in two sentences."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A completion, or text/event-stream when stream is true.",
            "headers": {
              "x-request-id": {
                "$ref": "#/components/headers/RequestId"
              },
              "x-notholy-concurrency-limit": {
                "$ref": "#/components/headers/ConcurrencyLimit"
              },
              "x-notholy-concurrency-remaining": {
                "$ref": "#/components/headers/ConcurrencyRemaining"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/responses": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "createResponse",
        "summary": "Response (OpenAI Responses format, stateless)",
        "description": "previous_response_id returns 400. Send the full conversation in input.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponseRequest"
              },
              "example": {
                "model": "notholy-specter",
                "input": "Summarize what CVSS 3.1 AV:N means."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A response object, or text/event-stream when stream is true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/completions": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "createCompletion",
        "summary": "Text completion (legacy OpenAI format)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionRequest"
              },
              "example": {
                "model": "notholy-vector",
                "prompt": "The OWASP category for SSRF is",
                "max_tokens": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A completion.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/messages": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "createMessage",
        "summary": "Message (Anthropic Messages format)",
        "description": "The Anthropic SDK base URL is https://api.notholy.com. cache_control is ignored; PDF document sources return 400.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "notholy-pulse",
                "max_tokens": 512,
                "messages": [
                  {
                    "role": "user",
                    "content": "What is a Sigma rule?"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A message, or text/event-stream when stream is true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/messages/count_tokens": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "countTokens",
        "summary": "Count input tokens (Anthropic format)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MessageRequest"
              },
              "example": {
                "model": "notholy-pulse",
                "messages": [
                  {
                    "role": "user",
                    "content": "What is a Sigma rule?"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token count.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input_tokens": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "input_tokens"
                  ]
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/embeddings": {
      "post": {
        "tags": [
          "Inference"
        ],
        "operationId": "createEmbedding",
        "summary": "Embeddings (no model available yet)",
        "description": "Always returns 404 model_not_found until an embedding model is added. Not charged.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string"
                  },
                  "input": {}
                },
                "required": [
                  "model",
                  "input"
                ]
              },
              "example": {
                "model": "notholy-embed",
                "input": "text"
              }
            }
          }
        },
        "responses": {
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": [
          "Models"
        ],
        "operationId": "listModels",
        "summary": "List models",
        "responses": {
          "200": {
            "description": "The public catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/models/{id}": {
      "get": {
        "tags": [
          "Models"
        ],
        "operationId": "getModel",
        "summary": "Get one model",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "notholy-pulse"
          }
        ],
        "responses": {
          "200": {
            "description": "One model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Model"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getCredits",
        "summary": "Balance of the organization and spend of the key",
        "responses": {
          "200": {
            "description": "Credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Credits"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/cve/{id}": {
      "get": {
        "tags": [
          "Research"
        ],
        "operationId": "getCve",
        "summary": "One CVE with NVD, CISA KEV and FIRST EPSS data",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^CVE-\\d{4}-\\d{4,}$"
            },
            "example": "CVE-2021-44228"
          }
        ],
        "responses": {
          "200": {
            "description": "The consolidated record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/cve/search": {
      "get": {
        "tags": [
          "Research"
        ],
        "operationId": "searchCve",
        "summary": "Search the CVE mirror",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "openssl"
          },
          {
            "name": "vendor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cwe",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "CWE-79"
          },
          {
            "name": "kev",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "min_cvss",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10
            }
          },
          {
            "name": "min_epss",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/advisories/query": {
      "post": {
        "tags": [
          "Research"
        ],
        "operationId": "queryAdvisories",
        "summary": "Advisories for a package and version",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ecosystem",
                  "name"
                ],
                "properties": {
                  "ecosystem": {
                    "type": "string",
                    "example": "npm"
                  },
                  "name": {
                    "type": "string",
                    "example": "lodash"
                  },
                  "version": {
                    "type": "string",
                    "example": "4.17.15"
                  }
                }
              },
              "example": {
                "ecosystem": "npm",
                "name": "lodash",
                "version": "4.17.15"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Advisories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/web/search": {
      "post": {
        "tags": [
          "Research"
        ],
        "operationId": "webSearch",
        "summary": "Web search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "maxLength": 400
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20
                  }
                }
              },
              "example": {
                "query": "CVE-2024-3094 xz backdoor analysis",
                "count": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results with title, URL and snippet.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/web/read": {
      "post": {
        "tags": [
          "Research"
        ],
        "operationId": "webRead",
        "summary": "Read a public page through the protected egress",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              },
              "example": {
                "url": "https://nvd.nist.gov/vuln/detail/CVE-2021-44228"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page title and text.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/files": {
      "post": {
        "tags": [
          "Research"
        ],
        "operationId": "uploadFile",
        "summary": "Upload a file for static analysis (kept 1 hour)",
        "parameters": [
          {
            "name": "x-file-name",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "handler.js"
          },
          {
            "name": "wait",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Wait for the analysis to finish"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analyzed file (with wait=1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "analysis running.": null,
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/files/{id}": {
      "get": {
        "tags": [
          "Research"
        ],
        "operationId": "getFile",
        "summary": "File status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/files/{id}/content": {
      "get": {
        "tags": [
          "Research"
        ],
        "operationId": "getFileContent",
        "summary": "Extracted text of a file",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Extracted text in chunks.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer nh_live_..."
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "Non-streaming requests with the same key within 24 hours return the first response and are not charged again.",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Send it to support when reporting a problem.",
        "schema": {
          "type": "string"
        }
      },
      "ConcurrencyLimit": {
        "description": "Requests you can run at once.",
        "schema": {
          "type": "integer"
        }
      },
      "ConcurrencyRemaining": {
        "description": "Free slots when this request started.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "Error": {
        "description": "An error in the format of the endpoint.",
        "headers": {
          "retry-after": {
            "description": "Seconds to wait",
            "at most 60. Sent with 429 and 503.": null,
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "unsupported_parameter",
                  "invalid_api_key",
                  "insufficient_credits",
                  "account_suspended",
                  "consent_required",
                  "key_not_allowed",
                  "model_not_found",
                  "not_found",
                  "request_too_large",
                  "rate_limit_exceeded",
                  "concurrency_limit_exceeded",
                  "capacity_busy",
                  "internal_error",
                  "upstream_error",
                  "model_unavailable",
                  "upstream_timeout"
                ]
              }
            }
          }
        }
      },
      "Message": {
        "type": "object",
        "required": [
          "role"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "developer",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {},
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_call_id": {
            "type": "string"
          }
        }
      },
      "Tool": {
        "type": "object",
        "required": [
          "type",
          "function"
        ],
        "properties": {
          "type": {
            "const": "function"
          },
          "function": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "notholy-pulse"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "stream": {
            "type": "boolean"
          },
          "stream_options": {
            "type": "object",
            "properties": {
              "include_usage": {
                "type": "boolean"
              }
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tool"
            }
          },
          "tool_choice": {},
          "reasoning_effort": {
            "type": "string",
            "enum": [
              "low",
              "high"
            ],
            "description": "Levels each model accepts are in GET /models capabilities.reasoning_efforts"
          },
          "max_tokens": {
            "type": "integer"
          },
          "max_completion_tokens": {
            "type": "integer"
          },
          "temperature": {
            "type": "number"
          },
          "top_p": {
            "type": "number"
          },
          "stop": {},
          "seed": {
            "type": "integer"
          },
          "response_format": {
            "type": "object",
            "additionalProperties": true
          },
          "n": {
            "type": "integer",
            "const": 1
          }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "const": "chat.completion"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          },
          "prompt_tokens_details": {
            "type": "object",
            "properties": {
              "cached_tokens": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ResponseRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "input": {},
          "instructions": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "reasoning": {
            "type": "object",
            "properties": {
              "effort": {
                "type": "string",
                "enum": [
                  "low",
                  "high"
                ]
              }
            }
          },
          "max_output_tokens": {
            "type": "integer"
          },
          "stream": {
            "type": "boolean"
          }
        }
      },
      "CompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "max_tokens": {
            "type": "integer"
          },
          "temperature": {
            "type": "number"
          },
          "stop": {},
          "stream": {
            "type": "boolean"
          }
        }
      },
      "MessageRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "max_tokens": {
            "type": "integer"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "system": {},
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "tool_choice": {
            "type": "object",
            "additionalProperties": true
          },
          "thinking": {
            "type": "object",
            "additionalProperties": true
          },
          "stop_sequences": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "temperature": {
            "type": "number"
          },
          "stream": {
            "type": "boolean"
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "notholy-pulse"
          },
          "object": {
            "const": "model"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "deprecated"
            ]
          },
          "context_length": {
            "type": "integer"
          },
          "max_output_tokens": {
            "type": "integer"
          },
          "input_modalities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "base_model": {
            "type": "string",
            "description": "The open model this one is built on",
            "when NotHoly shows it.": null
          },
          "default": {
            "type": "boolean",
            "description": "Present and true on the model clients should pick when the user has not chosen one."
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "tools": {
                "type": "boolean"
              },
              "reasoning": {
                "type": "boolean"
              },
              "reasoning_efforts": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "pricing": {
            "type": "object",
            "description": "USD per 1M tokens, as decimal strings.",
            "properties": {
              "currency": {
                "const": "USD"
              },
              "unit": {
                "type": "string"
              },
              "input": {
                "type": "string"
              },
              "output": {
                "type": "string"
              },
              "cached_input": {
                "type": "string"
              }
            }
          }
        }
      },
      "Credits": {
        "type": "object",
        "properties": {
          "object": {
            "const": "credits"
          },
          "currency": {
            "const": "USD"
          },
          "balance": {
            "type": "string"
          },
          "reserved": {
            "type": "string"
          },
          "available": {
            "type": "string"
          },
          "key": {
            "type": "object",
            "properties": {
              "spent": {
                "type": "string"
              },
              "total_budget": {
                "type": "string"
              },
              "daily_budget": {
                "type": "string"
              }
            }
          }
        }
      },
      "File": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      }
    }
  }
}