{"openapi":"3.1.0","info":{"title":"OPC UA Modeler API","version":"1.0.0","description":"Create, validate, and generate OPC UA companion specifications and information models. Converts YAML into standard NodeSet2.xml + Symbols.CSV + documentation.","contact":{"name":"Sterfive","url":"https://www.sterfive.com"}},"servers":[{"url":"https://api.opcua-modeler.sterfive.io","description":"Production"},{"url":"http://localhost:3300","description":"Local development"}],"paths":{"/api/v1/validate":{"post":{"operationId":"validateModel","summary":"Validate a YAML model","description":"Validates an OPC UA YAML model and returns diagnostics. **No authentication required** — 5 calls/day per IP (discovery mode). With a bearer token, uses your tier's daily limit.","tags":["Models"],"security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"text/yaml":{"schema":{"type":"string"},"example":"# yaml-language-server: $schema=https://support.sterfive.com/nodeset2.schema.json\nnamespaceUri: http://example.com/UA/MyModel/\nversion: 1.0.0\nobjectTypes:\n  - browseName: MyObjectType\n    subtypeOf: ua:BaseObjectType"}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"400":{"description":"Malformed YAML"},"401":{"description":"Authentication required (only without discovery quota)"},"415":{"description":"Unsupported content type"},"422":{"description":"Engine error"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/generate":{"post":{"operationId":"generateModel","summary":"Generate NodeSet2.xml from YAML","description":"Converts a YAML model into standard OPC UA NodeSet2.xml, Symbols.CSV, and documentation. **Requires a bearer token.** Sign up free at /signup.","tags":["Models"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"text/yaml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Generated artifacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"Malformed YAML"},"401":{"description":"Authentication required"},"415":{"description":"Unsupported content type"},"422":{"description":"Engine error"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/reverse":{"post":{"operationId":"reverseModel","summary":"Reverse-engineer NodeSet2.xml to YAML","description":"Converts an existing NodeSet2.xml file back into editable YAML format. **Requires a bearer token.** Sign up free at /signup.","tags":["Models"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"ns","in":"query","description":"Namespace URI to extract. Auto-detected if not provided.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/xml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Reversed YAML model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseResponse"}}}},"400":{"description":"Malformed XML or missing namespace"},"415":{"description":"Unsupported content type"},"422":{"description":"Engine error"},"429":{"description":"Rate limit exceeded"}}}},"/api/v1/try-server":{"post":{"operationId":"startTryServer","summary":"Start an ephemeral OPC UA Try Server","description":"Compiles a YAML model and starts a real, disposable OPC UA server reachable at opc.tcp://<host>:<port>/opcua-server/<slug> for 2 hours — anonymous auth, no security policy, read the address space with any OPC UA client (e.g. UA Expert). **Requires sign-in** (session or bearer token) and is capped per plan (Free: 1, Pro: 3 concurrent).","tags":["Try Server"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"text/yaml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Try Server started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TryServerResponse"}}}},"400":{"description":"Empty request body"},"401":{"description":"Authentication required"},"415":{"description":"Unsupported content type"},"422":{"description":"The model failed to compile"},"429":{"description":"Concurrent Try Server limit reached for your plan"},"503":{"description":"No Try Server capacity available right now"}}},"get":{"operationId":"getTryServerStatus","summary":"Check a Try Server's status","tags":["Try Server"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Try Server status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TryServerStatusResponse"}}}},"400":{"description":"Missing slug parameter"},"401":{"description":"Authentication required"}}},"delete":{"operationId":"stopTryServer","summary":"Stop a Try Server early","tags":["Try Server"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stopped"},"400":{"description":"Missing slug parameter"},"401":{"description":"Authentication required"},"403":{"description":"You do not own this Try Server"},"404":{"description":"No active Try Server with that slug"}}}},"/api/v1/companions":{"get":{"operationId":"listCompanions","summary":"List available companion specifications","description":"Returns all supported OPC UA companion specifications with their tier (free/pro).","tags":["Companions"],"responses":{"200":{"description":"Companion specifications list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanionsResponse"}}}}}}}},"components":{"schemas":{"Diagnostic":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"code":{"type":"string","description":"Diagnostic code (DSL-E-*, DSL-W-*, DSL-I-*)"},"message":{"type":"string"},"line":{"type":"integer","description":"Line number in YAML (if available)"}},"required":["severity","code","message"]},"ValidateResponse":{"type":"object","properties":{"valid":{"type":"boolean"},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}}},"required":["valid","diagnostics"]},"GenerateResponse":{"type":"object","properties":{"valid":{"type":"boolean"},"artifacts":{"type":"object","description":"Present only when valid is true","properties":{"nodeset2_xml":{"type":"string","description":"Base64-encoded NodeSet2.xml"},"symbols_csv":{"type":"string","description":"Base64-encoded Symbols.CSV"},"documentation_md":{"type":"string","description":"Base64-encoded Markdown documentation"}},"required":["nodeset2_xml","symbols_csv","documentation_md"]},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}}},"required":["valid","diagnostics"]},"ReverseResponse":{"type":"object","properties":{"yaml":{"type":"string","description":"The generated YAML model"},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/Diagnostic"}}},"required":["yaml","diagnostics"]},"Companion":{"type":"object","properties":{"alias":{"type":"string","description":"Short alias used in namespaces: list"},"name":{"type":"string","description":"Human-readable name"},"uri":{"type":"string","description":"OPC UA namespace URI"},"tier":{"type":"string","enum":["free","pro"]}},"required":["alias","name","uri","tier"]},"CompanionsResponse":{"type":"object","properties":{"companions":{"type":"array","items":{"$ref":"#/components/schemas/Companion"}}},"required":["companions"]},"TryServerResponse":{"type":"object","properties":{"slug":{"type":"string"},"endpoint":{"type":"string","description":"opc.tcp:// connection URL"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp"}},"required":["slug","endpoint","expiresAt"]},"TryServerStatusResponse":{"type":"object","properties":{"slug":{"type":"string"},"status":{"type":"string","enum":["running","not_found"]},"endpoint":{"type":"string"},"expiresAt":{"type":"string"}},"required":["slug","status"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (stfv_* prefix). Get one free at /signup. Tiers: Discovery (no key, 5/day validate only) → Free (25/day all endpoints) → Pro (unlimited)."}}}}