{"openapi":"3.1.0","info":{"title":"Heta Compiler API","version":"0.2.0","description":"API for interacting with the Heta Compiler via HTTP."},"servers":[{"url":"https://heta-api.insysbio.com","description":"Main server for Heta API"}],"paths":{"/build":{"post":{"operationId":"buildPlatform","summary":"Build or validate a Heta platform","description":"Validate or compile a Heta modeling platform from supplied files. By default, index.heta is the entry point and no export format is selected. Set declaration.export to generate files in requested formats. The response includes compilation logs, generated files, and temporary download information, including diagnostics when compilation fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Files and optional compiler settings for one remote build. Supply every source file referenced by the entry point.","required":["inputFiles"],"properties":{"lifetime":{"type":"number","minimum":0,"default":3600,"description":"Seconds to retain the build files and ZIP download. Defaults to 3600 (one hour). Set to 0 to delete them immediately after the response."},"inputFiles":{"type":"array","description":"Source files for this platform. Include index.heta unless declaration.importModule.source names another entry point, and include any files it imports.","minItems":1,"items":{"$ref":"#/components/schemas/File"},"example":[{"filepath":"index.heta","format":"utf8","filebody":"include model.heta;\n\n"}]},"declaration":{"type":"object","description":"Compiler configuration in the same form as platform.yml. Omit it to use the compiler defaults, including index.heta as the entry point and no exports.","properties":{"importModule":{"type":"object","description":"Entry point for the model. Omit to read index.heta as Heta source.","required":["source"],"properties":{"source":{"type":"string","description":"Path of the entry point file, relative to the platform root. Include this path in inputFiles. Defaults to index.heta.","default":"index.heta","example":"src/index.heta"},"type":{"type":"string","enum":["heta","table","xlsx","json","yaml","sbml"],"description":"Source format of the entry point file. Defaults to heta.","default":"heta","example":"json"}}},"options":{"type":"object","description":"Optional compiler settings for validation, debugging, and output directories.","properties":{"unitsCheck":{"type":"boolean","default":false,"description":"Check unit consistency in the platform when true. Defaults to false."},"debug":{"type":"boolean","description":"Save additional compiler metadata in options.metaDir when true. Defaults to false.","default":false},"distDir":{"type":"string","description":"Directory for generated export files, relative to the platform root. Defaults to dist.","default":"dist"},"metaDir":{"type":"string","description":"Directory for debug metadata, relative to the platform root. Defaults to meta.","default":"meta"}}},"export":{"$ref":"#/components/schemas/Export"}}}},"example":{"lifetime":1800,"inputFiles":[{"filepath":"index.heta","format":"utf8","filebody":"x1 @Record := 1.2;\n\nc1 @Compartment .= 5;"}],"declaration":{"importModule":{"source":"index.heta","type":"heta"},"options":{"unitsCheck":true,"debug":false,"distDir":"dist","metaDir":"meta"},"export":[{"format":"JSON"},{"format":"YAML"},{"format":"DBSolve","version":"25"},{"format":"SBML","version":"L3V2"},{"format":"Simbio"},{"format":"Mrgsolve"},{"format":"Table","splitByClass":true,"omitRows":3,"bookType":"xlsx"},{"format":"Matlab"},{"format":"Dot"},{"format":"Summary"}]}}}}}},"responses":{"200":{"description":"Compilation finished.","content":{"application/json":{"schema":{"type":"object","description":"Result of one build. Inspect logs for diagnostics; outputFiles contains generated file contents, downloadLink provides a ZIP archive, and filesLink points to the build directory served by Apache in production.","required":["outputFiles","logs","taskId","lifeend","downloadLink","filesLink"],"properties":{"outputFiles":{"type":"array","description":"Generated files, including the platform declaration and requested exports. Each item includes its path and content.","items":{"$ref":"#/components/schemas/File"}},"logs":{"type":"array","description":"Compiler log messages and diagnostics. Inspect these even when the request succeeds.","items":{"type":"string"}},"taskId":{"type":"string","description":"Identifier of this build, used in the download URL.","example":"5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"},"lifeend":{"type":"number","description":"Unix timestamp in seconds when retained files are scheduled for deletion.","example":1634025600},"downloadLink":{"type":"string","description":"Temporary ZIP download for the build files. Relative to the API origin in REST responses; absolute in MCP results. Unavailable after lifeend or when lifetime is 0.","example":"/download/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"},"filesLink":{"type":"string","description":"Temporary URL of the build directory, served by Apache in production for direct file access. Relative to the API origin in REST responses; absolute in MCP results. The local Node server does not serve /files. Unavailable after lifeend or when lifetime is 0.","example":"/files/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"}},"additionalProperties":false,"example":{"outputFiles":[{"filepath":"platform.yml","format":"utf8","filebody":"{\"export\":[{\"format\":\"JSON\"}]}"},{"filepath":"dist/output.heta.json","format":"binary","filebody":"..."}],"logs":["Compilation OK!"],"taskId":"5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b","lifeend":1634025600,"downloadLink":"/download/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b","filesLink":"/files/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"}}}}},"400":{"description":"Invalid request parameters. Request structure do not match the schema. Issues with user's API request.","content":{"application/json":{"schema":{"type":"object","required":["name","message"],"properties":{"name":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Wrong format of export option."},"errors":{"type":"array","items":{"type":"object"}}},"additionalProperties":false}}}},"422":{"description":"Unprocessable entity. The request is well-formed but unable to process. Compilation finished but with errors. This is usually because of platform files misconfiguration not related to the compiler or API.","content":{"application/json":{"schema":{"type":"object","properties":{"outputFiles":{"type":"array","description":"Array of the generated files.","items":{"$ref":"#/components/schemas/File"}},"logs":{"type":"array","description":"Array of log messages.","items":{"type":"string"}},"taskId":{"type":"string","description":"Task ID for getting files in UIDs format.","example":"5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"},"lifeend":{"type":"number","description":"Time when files will be deleted in Unix timestamp seconds format.","example":1634025600},"downloadLink":{"type":"string","description":"Link for downloading a ZIP file with all generated files.","example":"/download/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"},"filesLink":{"type":"string","description":"Temporary URL of the build directory, served by Apache in production for direct file access. The local Node server does not serve /files.","example":"/files/5f7b1b7b-0b7b-4b7b-8b7b-0b7b7b7b7b7b"}}}}}},"500":{"description":"Internal server error. Some critical error occurred during compilation. Problem with heta-compiler or api application development.","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"Internal Heta compiler error."},"errors":{"type":"array","items":{"type":"object"}}},"additionalProperties":false}}}}}}},"/download/{taskId}":{"get":{"operationId":"downloadFile","summary":"Download file","description":"Download a ZIP file associated with a whole content of the build platform.","parameters":[{"name":"taskId","in":"path","required":true,"description":"Unique task ID from /build POST response.","schema":{"type":"string","example":"9cc63441-a35c-4e41-b62c-505532fd79a6"}}],"responses":{"200":{"description":"File is ready for download.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"File is not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"File is not found."}}}}}},"500":{"description":"Internal server error. Problem in api application developed.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Unknown error."}}}}}}}}},"/info":{"get":{"operationId":"getInfo","summary":"Get Heta API environment info","description":"Check that Heta API is reachable and return the Heta compiler and Node.js versions used by the server, along with the OpenAPI schema path. No arguments are required.","responses":{"200":{"description":"Information about the Heta Compiler.","content":{"application/json":{"schema":{"type":"object","required":["description","version","node","schema"],"properties":{"description":{"type":"string","description":"Short description of the API service.","example":"API connector for Heta compiler"},"version":{"type":"string","description":"Version of Heta compiler installed on the server.","example":"0.12.2"},"node":{"type":"string","description":"Version of the Node.js runtime used by the server.","example":"v20.0.0"},"schema":{"type":"string","description":"Path to the OpenAPI schema for Heta API.","example":"/schema"}},"additionalProperties":false}}}}}}},"/schema":{"get":{"operationId":"getSchema","description":"Get the OpenAPI schema for the Heta Compiler API.","responses":{"200":{"description":"OpenAPI schema for the Heta Compiler API.","content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string","example":"3.1.0"}}}}}}}}}},"components":{"schemas":{"Export":{"type":"array","default":[],"description":"Export formats to generate after validation. Omit or leave empty to check the platform without generating format-specific exports.","items":{"type":"object","required":["format"],"properties":{"format":{"type":"string","enum":["JSON","YAML","DBSolve","SBML","Simbio","Mrgsolve","Table","XLSX","Julia","Matlab","Dot","Summary","Canonical","HetaCode","Dynms"],"description":"Output format to generate. Use one of the listed names with the shown capitalization."},"spaceFilter":{"type":"string","description":"Regular expression selecting namespaces to export. Omit to export all applicable namespaces.","example":"^one|two$"},"omit":{"type":"array","description":"Property paths to omit from JSON, YAML, or Table output.","items":{"type":"string"},"example":["notes","tags"]},"noUnitsExpr":{"type":"boolean","description":"For JSON and YAML exports, write units as Unit arrays when true; otherwise use UnitsExpr."},"powTransform":{"type":"string","enum":["keep","operator","function"],"description":"How to represent exponentiation in DBSolve output."},"version":{"type":"string","enum":["25","26","L2V3","L2V4","L2V5","L3V1","L3V2"],"description":"Target format version for DBSolve or SBML output. Choose a version supported by the selected format."},"eventsOff":{"type":"boolean","description":"Exclude switchers from exported DBSolve events when true."},"groupConstBy":{"type":"string","description":"JSON path used to group constants in the Initial Values section of DBSolve output.","example":"tags[0]"},"auxAsNotes":{"type":"boolean","description":"Append auxiliary content as a JSON object in Simbio Notes when true."},"omitRows":{"type":"number","description":"Number of empty rows to add to Table or XLSX output sheets.","example":3},"bookType":{"type":"string","enum":["xlsx","xlsm","xlsb","biff8","wk3","csv","txt","sylk","biff5","biff4","biff3","biff2","html","dif","dbf","wk1","xlml","ods","fods","rtf","prn","eth"],"description":"Workbook or text file type for Table output."},"splitByClass":{"type":"boolean","description":"Write each component class to a separate sheet or file in Table and XLSX exports when true."}}}},"File":{"type":"object","required":["filepath"],"properties":{"filepath":{"type":"string","description":"File path relative to the platform root. For input files, include the entry point and all imported files."},"format":{"type":"string","enum":["binary","utf8"],"default":"utf8","description":"Encoding of filebody: utf8 for text or binary for a binary string. Defaults to utf8 for input files."},"filebody":{"type":"string","description":"File contents as a string in the encoding named by format."}}}}}}