BrunelDocs

REST API

REST API overview

Brunel's REST API over HTTPS. Base URL, authentication, the request and response format, the typical flow from analysis to Terraform, and the OpenAPI description.

The REST API gives programs the same actions as the app: analyze a repository, design its infrastructure, ask or change, and fetch the generated files. It runs the same tools as the MCP server.

Base URL

https://api.brunel.cloud/v1

The previous address https://brunel.cloud/api/v1 keeps working. The OpenAPI 3.1 description is at https://api.brunel.cloud/v1/openapi.json (public, no key needed).

Authentication

Send an API key in the Authorization header on every request:

bash
curl https://api.brunel.cloud/v1/me -H "Authorization: Bearer $BRUNEL_API_KEY"

See Authentication.

Format

  • Requests with a body are JSON (Content-Type: application/json); other types get unsupported_media_type (HTTP 415).
  • Successful answers are { "data": … }.
  • Errors are { "error": { "code": "…", "message": "…" } } with the HTTP status. See Errors.
  • Every answer carries an x-request-id header.

The typical flow

From a repository to Terraform
API=https://api.brunel.cloud/v1
AUTH="Authorization: Bearer $BRUNEL_API_KEY"

# 1. Analyze (waits for the result, 5 to 60 seconds)
ID=$(curl -s -X POST "$API/projects" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/acme/shop"}' | jq -r .data.conversationId)

# 2. Design four priced tiers, adjusting the context if you want
curl -s -X POST "$API/projects/$ID/design" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"context":{"monthlyBudgetEur":500,"providers":["aws"]}}'

# 3. Ask or change
curl -s -X POST "$API/projects/$ID/messages" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"message":"Use a managed Redis instead of self-hosting it"}'

# 4. List the generated files of the Growth tier, then read one
curl -s "$API/projects/$ID/files?tier=growth" -H "$AUTH"
curl -s "$API/projects/$ID/files?tier=growth&path=terraform/data.tf" -H "$AUTH"

Long calls (analysis, design, refinement) answer when the work is done. Use a client timeout of at least 120 seconds.

Where to go next

REST API overview · Brunel Docs