{
  "openapi": "3.1.0",
  "info": {
    "title": "Hyperlambda public agent surface",
    "version": "1.0.0",
    "summary": "The endpoints on hyperlambda.dev that anyone, human or agent, may call without a key.",
    "description": "Everything here answers without signup. The slots and health endpoints are plain GETs. The sandbox endpoints execute Hyperlambda inside a whitelisted runtime, and an agent should call them first with describe set to true, to learn which functions it may use and which rate limit applies. The same data as the slots endpoint is published as static files at https://docs.ainiro.io/reference/slots.json and https://docs.ainiro.io/reference/slots-index.json, which have no throttle. The machine readable entry point is https://hyperlambda.dev/.well-known/hyperlambda-agent.",
    "license": { "name": "MIT", "url": "https://github.com/polterguy/magic/blob/master/LICENSE" },
    "contact": { "name": "Thomas Hansen", "email": "thomas@ainiro.io", "url": "https://hyperlambda.dev/thomas-hansen" }
  },
  "servers": [ { "url": "https://hyperlambda.dev" } ],
  "externalDocs": { "description": "Documentation of every slot of Hyperlambda", "url": "https://docs.ainiro.io/reference/slots/" },
  "paths": {
    "/magic/modules/docs/slots": {
      "get": {
        "operationId": "listSlots",
        "summary": "Every slot of Hyperlambda, with its complete signature",
        "description": "Returns one JSON array, with an object for every compiled slot, holding its name, description and signature (value, arguments, constraints and what it returns). Throttled per IP address, so fetch it once and keep it, or use the static copy at https://docs.ainiro.io/reference/slots.json.",
        "responses": {
          "200": { "description": "All slots", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Slot" } } } } },
          "429": { "description": "The per IP address throttle was exceeded. Use the static copy instead." }
        }
      }
    },
    "/magic/modules/docs/playground": {
      "post": {
        "operationId": "playground",
        "summary": "Sandboxed Hyperlambda that introspects the slots",
        "description": "Executes caller supplied Hyperlambda inside a whitelisted sandbox that can introspect every slot and transform the result with pure tree, string and math functions, and nothing else. Call it with describe set to true first.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxRequest" } } } },
        "responses": { "200": { "description": "The result, with a state saying what happened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } } }
      }
    },
    "/magic/modules/hl-test/run": {
      "post": {
        "operationId": "sandbox",
        "summary": "Sandboxed Hyperlambda that composes the public endpoints",
        "description": "Executes caller supplied Hyperlambda inside a whitelisted sandbox, to compose the public endpoints, and the files behind them, in one call. Call it with describe set to true first, to learn which functions you may use.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxRequest" } } } },
        "responses": { "200": { "description": "The result, with a state saying what happened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } } }
      }
    },
    "/magic/modules/health/summary": {
      "get": {
        "operationId": "healthSummary",
        "summary": "Is master of the Magic Cloud codebase passing?",
        "description": "The shortest answer, built from the live and repo results. master is passing, failing or unknown, where unknown means SonarCloud or GitHub did not answer and the values are the last known copy. Also returns the quality gate, coverage, the CI conclusion, the latest release and how many commits master is ahead of it.",
        "responses": {
          "200": {
            "description": "The verdict",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "master": { "type": "string", "enum": ["passing", "failing", "unknown"] },
              "quality-gate": { "type": "string" },
              "coverage": { "type": "string" },
              "ci": { "type": "string" },
              "release": { "type": "string" },
              "commits-ahead": { "type": "integer" },
              "stale": { "type": "boolean" },
              "generated": { "type": "string", "format": "date-time" },
              "details": { "type": "object" }
            } } } }
          }
        }
      }
    },
    "/magic/modules/health/live": {
      "get": {
        "operationId": "healthLive",
        "summary": "Quality gate and latest CI run of the Magic Cloud codebase",
        "description": "SonarCloud measures and the latest CI run on master, cached for 2 minutes. When stale is true, SonarCloud or GitHub did not answer, and the values are the last known copy, which means unknown, not passing.",
        "responses": { "200": { "description": "Live health", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/repo": {
      "get": {
        "operationId": "healthRepo",
        "summary": "Latest release, and what master is ahead of it by",
        "description": "The latest release of Magic Cloud, the commits master is ahead of it, and the newest commits, cached for 10 minutes.",
        "responses": { "200": { "description": "Repository state", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/pulls": {
      "get": {
        "operationId": "healthPulls",
        "summary": "Recently closed pull requests, with their authors",
        "description": "The 100 most recently closed pull requests of Magic Cloud, each with its author (login, profile URL, avatar and type, which is Bot for a bot) and a merged date that is null when it was closed without being merged, cached for 10 minutes. Count the merged ones per author to see who is merging code. When stale is true, GitHub did not answer, and the values are the last known copy.",
        "responses": { "200": { "description": "Recent pull requests", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/history": {
      "get": {
        "operationId": "healthHistory",
        "summary": "Quality history, weekly commits and code churn",
        "description": "History of the Magic Cloud codebase, cached for 30 minutes.",
        "responses": { "200": { "description": "History", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/scorecard": {
      "get": {
        "operationId": "healthScorecard",
        "summary": "OpenSSF Scorecard of the repository",
        "description": "The overall OpenSSF Scorecard score from 0 to 10, and every check with its score and reason. A score of -1 means a check could not be evaluated. Calculated weekly and on every push to master by an independent tool, read from api.securityscorecards.dev and cached for 5 minutes. When stale is true, the source did not answer, and the values are the last known copy.",
        "responses": { "200": { "description": "Scorecard", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/deps": {
      "get": {
        "operationId": "healthDeps",
        "summary": "Dependency vulnerability status",
        "description": "A state that is exactly one of clean, vulnerable, running, failed, stale and unknown, so no missing value has to be interpreted. Then advisories open and suppressed per severity (always numbers), every advisory with package, version, severity and link, the latest run of the workflow that builds the report, and the open Dependabot pull requests, built from NuGet and npm audits that run nightly and on every push to master, cached for 5 minutes. When stale is true, a source did not answer, the values are the last known copy, and the state is stale. An empty list of findings is returned as null, so read findings-count.",
        "responses": { "200": { "description": "Dependency report", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/quality": {
      "get": {
        "operationId": "healthQuality",
        "summary": "Quality gate conditions, most complex files and code per language",
        "description": "The quality gate conditions of the Magic Cloud codebase (metric, status, comparator, threshold, actual), the ten files with the highest cognitive complexity, and the lines of code per language as a language=lines string separated by semicolons. Read from SonarCloud and cached for 10 minutes. When stale is true, SonarCloud did not answer, and the values are the last known copy.",
        "responses": { "200": { "description": "Gate, hotspots and languages", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/health/plugins": {
      "get": {
        "operationId": "healthPlugins",
        "summary": "Test coverage of every plugin",
        "description": "One object for every plugin of the Magic Cloud codebase, read from SonarCloud and cached for 30 minutes. A plugin without tests has null coverage. When stale is true, SonarCloud did not answer, and the values are the last known copy.",
        "responses": {
          "200": {
            "description": "Coverage per plugin",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "generated": { "type": "string", "format": "date-time" },
              "stale": { "type": "boolean" },
              "plugins": { "type": "array", "items": { "type": "object", "properties": {
                "name": { "type": "string" },
                "coverage": { "type": ["string", "null"], "description": "Percent, null when the plugin has no tests" },
                "lines-to-cover": { "type": ["string", "null"] },
                "uncovered-lines": { "type": ["string", "null"] },
                "ncloc": { "type": ["string", "null"], "description": "Lines of code" }
              } } }
            } } } }
          }
        }
      }
    },
    "/magic/modules/health/project": {
      "get": {
        "operationId": "healthProject",
        "summary": "GitHub stars and forks, and the number of commits and releases",
        "description": "Stars and forks, plus the Link headers whose rel last page number is the total number of commits and of releases, cached for 1 hour.",
        "responses": { "200": { "description": "Project numbers", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/magic/modules/tools/url-to-markdown": {
      "get": {
        "operationId": "urlToMarkdown",
        "summary": "A web page as Markdown, with token counts",
        "description": "Fetches the page at url and returns it as Markdown, with the token counts of the page before and after conversion. Limited to 10 requests per minute per IP address.",
        "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } } ],
        "responses": { "200": { "description": "Markdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string" }, "html_tokens": { "type": "integer" }, "markdown_tokens": { "type": "integer" } } } } } } }
      }
    },
    "/magic/modules/tools/sitemap": {
      "get": {
        "operationId": "sitemapUrls",
        "summary": "The URLs of a sitemap",
        "description": "Takes the address of a sitemap or a sitemap index, and returns every URL with its last modification date, which is null when the sitemap has none.",
        "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } } ],
        "responses": { "200": { "description": "URLs", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "lastmod": { "type": ["string", "null"] } } } } } } } }
      }
    },
    "/magic/modules/chinook/Genre": {
      "get": {
        "operationId": "chinookGenre",
        "summary": "Sample database, the Genre table",
        "description": "The Chinook sample database is exposed as endpoints generated from its schema. Every table has /magic/modules/chinook/{Table}, plus {Table}-count, {Table}-group, {Table}-aggregate, {Table}-distinct and {Table}-count-distinct. See the agent entry point for the full list.",
        "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ],
        "responses": { "200": { "description": "Rows", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Slot": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "signature": { "type": "object", "description": "Value, arguments, constraints and what the slot returns" }
        }
      },
      "SandboxRequest": {
        "type": "object",
        "properties": {
          "describe": { "type": "boolean", "description": "Set to true instead of sending code, to learn the functions you may use, and the rate limit and timeout that apply to you. Counts against nothing." },
          "hyperlambda": { "type": "string", "description": "Hyperlambda to check and execute" }
        }
      },
      "SandboxResponse": {
        "type": "object",
        "properties": {
          "state": { "type": "string", "enum": ["described", "executed", "rejected", "unknown-slot", "invalid-invocation", "error", "timeout", "generator-failed"] },
          "reason": { "type": "string" }
        }
      }
    }
  }
}