{"openapi":"3.1.0","info":{"title":"Concept Generator API","version":"1.0.0","description":"Projects, generations, tasks and scenarios of your company. Authenticate with an API key created by the company owner in Team and plan > API keys: Authorization: Bearer gk_... Limit 60 requests per minute per key. Generations are charged exactly as in the interface"},"servers":[{"url":"https://allportugalplan.one/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key gk_..."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"Project":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"city":{"type":["string","null"]},"status":{"type":"string","enum":["draft","in_progress","review","archived"]},"area_ha":{"type":["number","null"]},"default_parameter_set_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["generate","regenerate","import","export","optimize"]},"status":{"type":"string","enum":["queued","generating","ready","error","cancelled"]},"stage":{"type":["string","null"]},"progress":{"type":"integer"},"project_id":{"type":"string"},"concept_id":{"type":["string","null"]},"scenario_id":{"type":["string","null"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"result":{"type":["object","null"],"description":"Only for kind optimize: {goal, variants, best, seconds}"},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"finished_at":{"type":["string","null"]}}},"Scenario":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"project_id":{"type":"string"},"concept_id":{"type":"string"},"version":{"type":["object","null"],"properties":{"id":{"type":"string"},"created_at":{"type":"string"},"reason":{"type":"string"},"tep":{"type":"object"},"economics":{"type":"object"},"summary":{"type":"object"},"files":{"type":"object","additionalProperties":{"type":"object","properties":{"url":{"type":"string"},"expires_at":{"type":"string"}}}}}}}},"WebhookPayload":{"type":"object","description":"Webhook body, signed with HMAC-SHA256 of the raw body: header X-Signature: sha256=<hex>. Events: task.ready, task.failed, scenario.handed_off","properties":{"id":{"type":"string"},"event":{"type":"string"},"created_at":{"type":"string"},"data":{"type":"object"}}}}},"paths":{"/projects":{"get":{"summary":"List company projects","responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}},"401":{"description":"Missing, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests per minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/generations":{"post":{"summary":"Start a generation: a new concept with 1-5 scenarios, one generation charged per scenario","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["concept_name","scenarios"],"properties":{"concept_name":{"type":"string","maxLength":200},"scenarios":{"type":"integer","minimum":1,"maximum":5},"parameter_set_id":{"type":"string","format":"uuid","description":"Defaults to the project's default set"},"overrides":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Parameter key -> value, on top of the set"},"options":{"type":"object","additionalProperties":true,"description":"Generation options; omitted keys keep the launch screen defaults"}}}}}},"responses":{"201":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"concept_id":{"type":"string"},"task_ids":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Missing, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough generations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests per minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/optimizations":{"post":{"summary":"Start a parameter search for a goal, one generation charged","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["goal"],"properties":{"goal":{"type":"string","enum":["max_sellable","min_payback","max_npv"]},"variants":{"type":"integer","minimum":6,"maximum":12,"default":9},"parameter_set_id":{"type":"string","format":"uuid"},"overrides":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"options":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"task_id":{"type":"string"}}}}}},"401":{"description":"Missing, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough generations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A search for this project is already queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests per minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{id}":{"get":{"summary":"Task status, stage, progress and error code","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","pt","ru"],"default":"en"}}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"401":{"description":"Missing, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests per minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/scenarios/{id}":{"get":{"summary":"Scenario KPIs, economics, summary and signed links to the current version files (valid 1 hour)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Scenario","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scenario"}}}},"401":{"description":"Missing, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 requests per minute for this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}