GetFacades agent-API

Hurtigstart

1. Opprett en nøkkel

   app.getfacade.ai→Konto→Innstillinger→API→Opprett nøkkel

   Verdien vises én gang og kan ikke gjenopprettes, bare erstattes. Forbrukstaket settes ved opprettelsen og gjelder ved hvert betalte kall.

   Opprett en agentnøkkel

2. Registrer MCP-serveren

   Én oppføring i klientens konfigurasjon, så omstart av klienten. Claude Desktop holder den i claude_desktop_config.json; enhver annen MCP-klient tar de samme tre feltene.

   claude_desktop_config.jsonKopier

   {
     "mcpServers": {
       "getfacade": {
         "command": "npx",
         "args": ["-y", "@getfacade/mcp"],
         "env": { "GETFACADE_API_KEY": "your-key" }
       }
     }
   }

   Miljøvariabler

   Variabel	Påkrevd	Standardverdi
   GETFACADE_API_KEY	Ja	—
   GETFACADE_API_BASE_URL	Nei	https://api.getfacade.ai/api/v1

3. Eller kall HTTP-API-et direkte

   Samme nøkkel fungerer som bearer-token. Forespørsler og svar er JSON:API-dokumenter, der id er et felt på øverste nivå og aldri ligger inne i attributes.

   shellKopier

   curl -X POST https://api.getfacade.ai/api/v1/projects \
     -H "Authorization: Bearer $GETFACADE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"data":{"type":"project","attributes":{"name":"Maple Street 14"}}}'

Verktøy

Tjueen verktøy. MCP-serveren holder ingen tilstand og ingen egne regler: hvert verktøy er ett eller flere kall til endepunktene ved siden av, og hver melding agenten gjengir er skrevet av API-et.

• create_building

  create_building(name, goals?, construction_region?)
    -> { building_id, name }

  Oppretter en bygning. Navnet er unikt innenfor kontoen og maks 50 tegn; en duplikat avvises med 422.

  KallerPOST /projects

• upload_photo

  upload_photo(building_id, file_path, wait_for_validation? = true)
    -> { view_id, validation: { status, reason? } }

  Registrerer en visning, laster opp bytene til en forhåndssignert URL, bekrefter dem og spør til bildet er godtatt eller avvist. Bredde, høyde og md5 beregnes lokalt; sideforholdet utleder serveren.

  KallerPOST /projects/{project}/angles → PUT (presigned) → POST /angles/{angle}/confirm → GET /angles/{angle}/validation

• start_designasynkron

  start_design(building_id, view_id, prompt?, style_ids?, colors?,
               brand_selections?, render_effort?, seed?)
    -> { design_id, job_id, status, seed }

  Prosjekterer fasaden på en valgt visning og viser den på bildet: materialer som kan brukes i byggets land, produkter som faktisk selges der, og oppbygningen bak overflaten. Oppretter en design, køer arbeidet og returnerer jobb-id. Seed er valgfritt: utelates det, genererer serveren en og returnerer den.

  KallerPOST /projects/{project}/concepts → POST /concepts/{concept}/angles/{conceptAngle}/renders

• refine_designasynkron

  refine_design(render_id | design_id + building_id, instruction,
                style_ids?, colors?, brand_selections?, render_effort?, seed?)
    -> { design_id, job_id, status, parent_render_id, seed }

  Reviderer en ferdig design med ord. Instruksjonen brukes på den ferdige designen, så alt den ikke nevner beholdes. Å revidere en hovedvisning oppretter en ny design, så den forrige overskrives aldri.

  KallerGET /renders/{render} → POST /concepts/{concept}/angles/{conceptAngle}/renders (mode: refine)

• get_job

  get_job(job_id, kind: "render" | "album" | "estimate" = "render")
    -> { status, expected_seconds?, result_url?, error?, error_code? }

  Leser tilstanden til én rendering, ett overslag eller ett album.

  KallerGET /renders/{render} · GET /estimates/{estimate}

• list_jobs

  list_jobs(kind?, limit? = 20)
    -> [{ job_id, kind, status, building_id, created_at }]

  Nylige jobber på tvers av kontoen, uferdige først.

  KallerGET /history

• list_designs

  list_designs(building_id)
    -> [{ design_id, note, has_main_render, main_render_id,
         main_render_url, renders }]

  Bygningens design med sine renderinger. Herfra kommer render-id-ene til overslag og album.

  KallerGET /projects/{project}/concepts

• order_estimateasynkron

  order_estimate(design_id, render_ids, currency?,
                 measurement_system?, special_requirements?)
    -> { job_id, status }

  Priser designen linje for linje, i materialer og arbeid, til det de angitte materialene koster i byggets land. Valuta og målesystem følger som standard det landet.

  KallerPOST /projects/{project}/concepts/{concept}/estimates

• order_albumasynkron

  order_album(design_id, render_ids, language?, include_blueprints?,
              include_estimate?, requirements?)
    -> { job_id, status }

  Dokumenterer designen for laget som bygger: materialene, fasadens oppbygning, sikkerhetsnotater og normene bak dem. Krever en ferdig hovedrender.

  KallerPOST /concepts/{concept}/album/generate

• upscale_renderasynkron

  upscale_render(render_id)
    -> { job_id, status }

  Forstørrer en ferdig rendering. Koster tokens og kjøres asynkront.

  KallerPOST /renders/{render}/upscale

• get_estimate

  get_estimate(estimate_id)
    -> { status, currency, facade_area, materials_total, labor_total,
         grand_total, notes, lines: [{ line_id, section, name, quantity,
         unit, unit_price, line_total }] }

  Selve overslaget: summer, forutsetningene bak dem og hver linje med mengde, enhet og pris. get_job melder statusen til et overslag, aldri innholdet.

  KallerGET /estimates/{estimate}

• add_estimate_line

  add_estimate_line(estimate_id, section, name, quantity,
                    unit_price, unit?, category?)
    -> { line_id }

  Legger til en linje i kalkylen. Enhetene kommer fra dens eget målesystem.

  KallerPOST /estimates/{estimate}/items

• update_estimate_line

  update_estimate_line(estimate_id, line_id, name?, quantity?,
                       unit_price?, unit?, category?, section?)
    -> { line_id }

  Endrer en linje i kalkylen. Bare feltene som sendes endres; serveren regner ut summene på nytt.

  KallerPATCH /estimates/{estimate}/items/{item}

• delete_estimate_line

  delete_estimate_line(estimate_id, line_id)
    -> { deleted }

  Fjerner en linje fra kalkylen.

  KallerDELETE /estimates/{estimate}/items/{item}

• delete_render

  delete_render(render_id)
    -> { deleted }

  Sletter en rendering. Slettes hovedrenderingen, går designet tilbake til utkast.

  KallerDELETE /renders/{render}

• delete_design

  delete_design(building_id, design_id)
    -> { deleted }

  Sletter et design med renderingene under det.

  KallerDELETE /projects/{project}/concepts/{concept}

• delete_building

  delete_building(building_id)
    -> { deleted }

  Sletter en bygning med alt innholdet. Allerede brukte tokens refunderes ikke.

  KallerDELETE /projects/{project}

• list_token_packages

  list_token_packages()
    -> [{ package, tokens, price, currency }]

  Pakkene kontoen kan kjøpe, med pris og antall tokens.

  KallerGET /tokens/packages

• buy_tokensasynkron

  buy_tokens(package)
    -> { status, transaction_id, tokens, checkout_url?, detail }

  Kjøper én pakke til lommeboken til denne nøkkelen. Krever en nøkkel utstedt med kjøp slått på, og går aldri utover det nøkkelen fortsatt kan bruke.

  KallerPOST /tokens/purchase

• get_balance

  get_balance()
    -> { balance, scope: "api", spend_cap, spent, remaining, is_admissible }

  Agentlommeboken, taket for denne nøkkelen og om neste betalte kall blir sluppet gjennom.

  KallerGET /tokens/balance

• report_problem

  report_problem(message, category?,
                 context?: { tool, endpoint, status_code, job_id,
                             expected, actual })
    -> { reference, message }

  Rapporterer en feil i dette API-et: et felt som er beskrevet her, men aldri kommer, et avslag der ordlyden ikke viser veien videre, et resultat som ikke svarer til bestillingen. Gratis og godtatt med tom saldo; tilbake kommer en referanse, ikke et svar.

  KallerPOST /feedback

Autentisering og nøkler

• Nøkkelen sendes som bearer-token i Authorization-hodet. MCP-serveren leser den fra GETFACADE_API_KEY og sender ikke noe annet.
• Verdien vises én gang, ved opprettelsen, og bare hashen lagres. Rotering betyr å opprette en ny nøkkel og trekke tilbake den gamle.
• Hver nøkkel bærer et forbrukstak som håndheves på serveren før kallet når en kontroller. Et nådd tak stopper den nøkkelen, ikke kontoen.
• Nøkler administrerer ikke nøkler: det er en menneskelig handling, og de endepunktene svarer 403 på en agentnøkkel.
• Tilbaketrekking virker umiddelbart. Kall med en tilbaketrukket nøkkel svarer 401.

Asynkront arbeid og polling

• start_design, order_estimate og order_album returnerer en jobb-id og er dermed ferdige. En rendering tar minutter: poll GET /renders/{render} eller GET /estimates/{estimate} til tilstanden er endelig.
• At bildekontrollen er ferdig, meldes over en websocket agenten ikke har. Poll GET /angles/{angle}/validation og les validation.is_in_progress; utled ikke selv sluttilstanden fra statusteksten.
• En ferdig render og et ferdig album ligger på permanente offentlige URL-er: uten signatur og uten utløp. Lenken kan gis direkte til en person, som svar på «vis meg resultatet». Siden den ikke er signert, spør den ingen om lov: den fortsetter å virke for alle som får den, og kan ikke trekkes tilbake.
• GET /renders/{render}/download er noe annet: en signert URL som utløper i løpet av minutter og bærer et filnavn. Den er til for å lagre filen, ikke for å dele den.

Ratebegrensninger per nøkkel

En agentnøkkel har egne kvoter, atskilt fra de menneskelige øktene på samme konto, slik at en agent i løkke ikke spiser opp kvoten til personen foran skjermen. Avslaget er billig: det tas i mellomvaren, før alt databasearbeid.

Idempotens

Et betalt kall oppretter en jobb, og betalingen følger jobben. Å gi kallet et navn er det som lar en gjentakelse returnere den samme jobben i stedet for å opprette en nummer to.

• Idempotency-Key kreves i ethvert betalt kall med en API-nøkkel: starte eller forbedre et design, forstørre et render, bestille et kostnadsoverslag eller et album, generere et overslag på nytt. Uten den svarer kallet 422 IDEMPOTENCY_KEY_REQUIRED, og ingenting legges i kø.
• Enhver verdi på 8 til 191 tegn, én per bestilling; vanligvis en UUID. En ny bestilling får en ny verdi: to like kall under to verdier er to design.
• Gjentar du et kall med samme verdi og samme body, får du den opprinnelige statusen og bodyen tilbake, med Idempotent-Replay: true i svaret. Ingenting legges i kø, og ingenting belastes to ganger.
• Samme verdi med en annen body svarer 422 IDEMPOTENCY_KEY_REUSED. En gjentakelse som kommer mens det første kallet fortsatt går, svarer 409 IDEMPOTENCY_IN_PROGRESS: vent, og send det samme kallet på nytt.
• Ethvert 4xx-svar frigjør verdien, så den samme kan sendes igjen når årsaken er rettet. Verdier huskes i 24 timer, per konto.
• @getfacade/mcp lager verdien og gjentar kallet under den på egen hånd, så et verktøykall trenger ikke sende noe.

Feil

Feil kommer som JSON:API-feildokumenter. Laravels valideringssvar har ikke JSON:API-form og bærer teksten i message.

Den lesbare teksten skrives av API-et, på språket til den som kaller. Vis errors[].detail som den står i stedet for å lage din egen melding.

Betaling og adgang

• Betalte kall trekker på krediter i api-omfanget, og adgangen ser bare på den saldoen: hver nøkkel betaler i krediter.
• Et aktivt Pro Plan fyller api-lommeboken opp til 1 000 krediter én gang per faktureringsperiode. Utover det kjøpes krediter.
• En nøkkel fyller bare på sin egen lommebok hvis den ble utstedt med kjøp slått på, og høyst med det den fortsatt kan bruke, så et kjøp hever aldri forbrukstaket.
• api-området er en egen lommebok. Appens kreditter, gratisnivået inkludert, brukes aldri av en nøkkel.
• Forbruket telles per nøkkel, så hver assistents bruk er synlig for seg.
• Forhåndssjekken er GET /tokens/balance, feltet data.attributes.agent.is_admissible. Blokken finnes bare for agentnøkler, og flagget speiler adgangsmellomvaren nøyaktig. Les det i stedet for selv å sammenligne saldo og tak.
• Adgangen avgjøres før arbeid legges i kø, så et avvist kall koster ingenting.

Farge- og merketokener

start_design tar to uavhengige lister med maks ti oppføringer hver. Rekkefølgen bærer rollen 60/30/10: første oppføring er den dominerende veggfargen.

colors

brand_selections

Grammatikken er category:level:id[@value][.value]. Delen etter @ bærer slugger for geometriverdier, unike innenfor kategorien sin, så aksen de hører til slås opp i stedet for å skrives ut i tokenet. Et ukjent token avvises med 422 og forbigås aldri i stillhet.

Full økt

Én bygning, ett bilde, ett design og så de to dokumentene. Instruksjonen som gir det:

Opprett en bygning som heter Maple Street 14, last opp ./front.jpg som visningen dens og start et design med varmgrå vegger og hvite lister. Bestill overslaget og albumet for resultatet.

create_building(name: "Maple Street 14")
  -> { building_id: "0f8c…" }

upload_photo(building_id: "0f8c…", file_path: "./front.jpg")
  -> { view_id: "41ab…", validation: { status: "approved" } }

start_design(building_id: "0f8c…", view_id: "41ab…",
             colors: ["#8A8F7D", "#F2F0EB"],
             brand_selections: ["siding:line:40@double-4-dutchlap"])
  -> { design_id: "7d21…", job_id: "b933…", status: "queued" }

get_job(job_id: "b933…")
  -> { status: "completed", result_url: "https://…" }

refine_design(render_id: "b933…",
              instruction: "put a canopy over the front door")
  -> { design_id: "9e44…", job_id: "c07f…", status: "queued" }

order_estimate(design_id: "9e44…", render_ids: ["c07f…"])
order_album(design_id: "9e44…", render_ids: ["c07f…"], include_estimate: true)

Ressurser

• Denne siden som Markdown
• OpenAPI 3.1-spesifikasjon (YAML)
• @getfacade/mcp på npm
• Kontakt oss