Open API

Key

The company owner creates a key in Team and plan > API keys. The key is shown once; pass it in every request. Data of other companies is not available with it Open API keys

export GK_API_KEY=gk_...
curl https://generator-koncepciy.lovable.app/api/v1/projects -H "Authorization: Bearer $GK_API_KEY"

Limit: 60 requests per minute per key, above it the answer is 429 with the Retry-After header. Errors come as JSON: {code, message}

Projects

List of company projects with id, name, status and area

curl https://generator-koncepciy.lovable.app/api/v1/projects \
  -H "Authorization: Bearer $GK_API_KEY"

Start a generation

Creates a concept with 1-5 scenarios. parameter_set_id is optional: by default the project's default set is used. overrides change parameters by key on top of the set. The answer is the list of task ids

curl -X POST https://generator-koncepciy.lovable.app/api/v1/projects/PROJECT_ID/generations \
  -H "Authorization: Bearer $GK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"concept_name": "API test", "scenarios": 2, "overrides": {"building.maxLevels": 9}}'

Parameter search for a goal

goal: max_sellable, min_payback or max_npv; variants 6-12. One generation is charged. When the task is ready, its result lists the variants

curl -X POST https://generator-koncepciy.lovable.app/api/v1/projects/PROJECT_ID/optimizations \
  -H "Authorization: Bearer $GK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal": "max_npv", "variants": 9}'

Task status

Status queued, generating, ready, error or cancelled, the engine stage in the chosen language (lang=en|pt|ru), progress 0-100 and the error with its code

curl "https://generator-koncepciy.lovable.app/api/v1/tasks/TASK_ID?lang=en" \
  -H "Authorization: Bearer $GK_API_KEY"

Scenario

KPIs, economics and summary of the current version and signed links to its files, valid for 1 hour

curl https://generator-koncepciy.lovable.app/api/v1/scenarios/SCENARIO_ID \
  -H "Authorization: Bearer $GK_API_KEY"

Webhooks

In API keys the owner adds an https address and chooses events: task.ready, task.failed, scenario.handed_off. We send POST with JSON {id, event, created_at, data}. If there is no 2xx answer within 10 s, we retry 3 times: after 1, 5 and 15 minutes. Every attempt is in the delivery log

Check the signature: X-Signature = sha256= plus hex of HMAC-SHA256 with the webhook secret over the raw body. Example for Node.js:

import crypto from "node:crypto";

// raw: request body as a string, before JSON parsing
function verify(raw, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(raw).digest("hex");
  return header && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

OpenAPI description

Machine-readable description for Postman, Insomnia and code generators: https://generator-koncepciy.lovable.app/api/v1/openapi.json