canonical: https://jentic.com/apis/brainq.com/brainq # Brainq Houston (vsc pool) The Houston API manages compute nodes and the virtual machines that run on them. It lists and creates nodes, reads a single node's details, and patches a node's configuration, then exposes each node's VMs along with their details, events, metrics, traffic usage, and uptime. Node-level reads cover events, metrics, traffic usage, uptime intervals, and the service-level indicator. It also lists software releases for a target, checks the current version, and serves release files for download. ## For AI agents List and create compute nodes, inspect their VMs, and read metrics, uptime, and release files, across 21 endpoints secured with an API key in the Authorization header. ## Scope Does not handle billing, DNS, or object storage. Use for managing compute nodes and their virtual machines only. ## Capabilities - List and create compute nodes, read one node's details, and patch a node's configuration - List the VMs on a node and read a single VM's details - Read a VM's events, metrics, traffic usage, and uptime - Read node-level events, metrics, traffic usage, uptime intervals, and the service-level indicator - List releases for a target, check the current version, and download a release file ## Use cases ### Fleet and VM Monitoring Keep a view of a compute pool without logging into a console. An agent lists nodes, opens one node's VMs, and reads each VM's metrics, uptime, and traffic usage, then rolls the node-level uptime intervals and service-level indicator into a status report. This turns raw fleet telemetry into an answer an agent can act on. Example prompt: List nodes, open one node's VM list, and read each VM's metrics and uptime ### Node Provisioning and Release Checks Grow or update a pool programmatically. An agent creates a node, patches its configuration, then lists releases for a target, checks the current version, and downloads the right release file. The release operations let the agent confirm it is deploying the expected build. Example prompt: Create a node, patch its configuration, then list releases for the target and check the current version ### AI Agent Integration via Jentic An AI agent discovers and calls the Houston API through Jentic without handling the API key directly. The agent searches by intent, receives the matching operation and its input schema, and reads node or VM telemetry while Jentic injects the stored key in the Authorization header. This gives the agent fleet visibility without reading the reference docs or holding secrets. Example prompt: Search Jentic for 'list nodes', load the operation schema, and read node details with Jentic-injected credentials ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/nodes` | Get the list of nodes | | POST | `/nodes` | Create a new node | | GET | `/nodes/{xid}` | Get node details | | PATCH | `/nodes/{xid}` | Patch a node | | GET | `/nodes/{node_xid}/vm` | Get the VM list for a node | | GET | `/releases/{target}` | Get the list of releases for a target | ## Key resources - **Nodes** — List, create, read, and patch nodes, and read their events, metrics, traffic usage, uptime, and SLI - **VMs** — List a node's VMs and read each VM's details, events, metrics, traffic usage, and uptime - **Releases** — List releases for a target, check the current version, and download release files ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 63 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 89 / 100 - Developer Experience & Jentic Compatibility: 69 / 100 - AI-Readiness & Agent Experience: 45 / 100 - Agent Usability: 94 / 100 - Security: 50 / 100 - AI Discoverability: 61 / 100 - **View full report:** https://jentic.com/apis/brainq.com/brainq/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Houston API by hand means obtaining a key, sending it as a Bearer token in the Authorization header against houston.brainq.com, and polling node and VM telemetry yourself. Through Jentic you install once, import Houston from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Houston puts the node id in the URL path, so a rule can pin your agent to one node and the operations you pick, such as reading its metrics and uptime, while leaving node creation and configuration patching out of the set. - **Credential handling:** Your Houston API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list nodes' or 'read a VM's metrics', and Jentic returns the matching Houston operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **DigitalOcean** — Public-cloud compute with Droplets, versus Houston's node-and-VM pool management. - **Linode** — Linode cloud instances, versus Houston's own node and VM telemetry. - **Scaleway Instance** — Scaleway instance provisioning that can run alongside a Houston-managed pool. ## FAQ ### What authentication does the Houston API use? The Houston API authenticates with an API key sent as a Bearer token in the Authorization header, per its OpenAPI spec. Every node, VM, and release operation expects that header. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never reaches the agent. ### Is there a Houston MCP server? You do not need a separate MCP server to give your agent the Houston API. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls its node and VM operations on demand. Operations are discovered as needed, so no extra server's tool definitions load into the agent's context. ### Can I read a VM's metrics with the Houston API? Yes. List a node's VMs, then read a single VM's metrics, events, traffic usage, and uptime. The responses are structured JSON an agent can summarise into a status report. ### Can I limit what my agent is allowed to do with the Houston API? Yes. Houston puts the node id in the URL path, so with Jentic you can pin the agent to one node and allow only the reads it needs, such as metrics and uptime, while withholding node creation and configuration patches. Because you run Jentic One yourself, every call the agent makes is logged. ### How do I list nodes with the Houston API through Jentic? Search Jentic for 'list nodes' to get the matching Houston operation and its input schema, then your agent calls it and reads each node's details. To run it on your own infrastructure, install Jentic One from its GitHub repo.