Documentation
API reference
The Nexugen REST API: authentication, quick start, endpoints, rate limits, errors, Pilot from code, Pilot for your users and webhooks.
REST API
Everything you can do from the dashboard, from your own code: create projects, start agentic builds, fire edits, follow runs, deploy, manage domains, environment and webhooks. Requests and responses are JSON unless an endpoint says otherwise.
https://nexugen.app/api/v1GET https://nexugen.app/api/v1 lists every endpoint without authentication./v2.Authentication
Create a key under Settings, API and webhooks. The key is shown once, at creation. The platform stores only a SHA-256 hash of it, so it cannot be shown again; if you lose it, revoke it and create another.
Send it on every request:
Authorization: Bearer nxg_your_key_here
x-api-key: nxg_… is accepted too. Keys carry one of two permission sets:
- read: list and inspect projects, sessions, events, versions, deploy status, domains, webhooks.
- write: everything above, plus start builds and edits, write files, deploy, change domains and environment variables, steer and cancel runs, manage webhooks. Environment variables are secrets, so reading them needs a write key as well.
- pilot:ask: ask Pilot to do things in your apps, upload files for it and stop its turns. Separate from write, because a turn spends credits and can change a live app's records.
- pilot:approve: approve, reject or undo Pilot's changes. A change that waits for the owner in the dashboard waits over the API too; only a key with this scope can let it through.
- pilot:screen: watch Pilot's live screen (the app, signed in as you) and make links to embed it on your own site.
- pilot:control: click, type and scroll in the app on that screen, as you. Includes pilot:screen.
A key acts as its owner. Project access, team sharing, credits and plan limits apply exactly as they do in the dashboard: a key cannot reach a project its owner cannot.
Quick start
Who am I, and what can this key do?
curl https://nexugen.app/api/v1/me \ -H "Authorization: Bearer $NEXUGEN_API_KEY"
Create a project and build it from a prompt. The call returns as soon as the build is queued.
curl -X POST https://nexugen.app/api/v1/builds \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sunrise Bakery",
"prompt": "A website for a bakery in Lagos: menu with prices, opening hours, a gallery, and a WhatsApp order button."
}'
# 202 { "project": { "id": "cm…", … }, "build": { "queued": true, "jobId": "…" } }Follow the run. Every build and edit is a session; its events are the live log.
# the live run for the project curl "https://nexugen.app/api/v1/sessions?projectId=PROJECT_ID&active=1" \ -H "Authorization: Bearer $NEXUGEN_API_KEY" # tail its events; keep the last seq and pass it back as after= curl "https://nexugen.app/api/v1/sessions/SESSION_ID/events?after=0" \ -H "Authorization: Bearer $NEXUGEN_API_KEY"
A session ends in DONE, FAILED or CANCELLED. AWAITING_INPUT means the agent asked a question: answer it with POST /sessions/:id/events and type: "decision.answer".
Change something.
curl -X POST https://nexugen.app/api/v1/projects/PROJECT_ID/edits \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "instruction": "Make the header sticky and add a dark mode toggle." }'
# 202 { "queued": true, "editJobId": "…", "sessionId": "…" }Put it on the web at its nexugen.app subdomain.
curl -X POST https://nexugen.app/api/v1/projects/PROJECT_ID/self-host-deploy \ -H "Authorization: Bearer $NEXUGEN_API_KEY"
Endpoints
Paths are relative to https://nexugen.app/api/v1. The permission column is the key permission the endpoint needs.
Account
/mereadThe account behind this key: user, plan, credit balance, and the key's own permissions and rate limit.
/billingreadPlan, subscription status and credit usage in full.
Projects
/projectsreadList your projects, newest first.
Query: page (default 1), limit (default 10), status (DRAFT | BUILDING | BUILT | DEPLOYED | FAILED), search.
Returns { projects: [...], pagination: { page, limit, total, totalPages } }
/projectswriteCreate an empty project without building it. Use POST /builds to create and build in one call.
Body: { name, description?, framework?, language?, styling?, features?, visibility? }
Returns 201 { project }
/projects/:idreadOne project with its files listed.
Query: includeContent=true to include every file's contents.
/projects/:idwriteRename or describe a project, or change its status or visibility.
Body: { name?, description?, status?, visibility? }
/projects/:idwriteDelete a project, its files, versions and hosting. Not reversible.
/projects/:id/feedreadThe project's activity feed: runs, comments and decisions in one stream.
Query: after=<seq> to page forward from an earlier response.
/projects/:id/commentswritePost to the project's team thread. Mention @nexugen with an instruction to fire an edit from the thread.
Body: { text }
/projects/:id/proposalsreadEdits made as proposals, awaiting review.
/projects/:id/attentionreadWhat currently needs a human: blocked runs, pending decisions, failed deploys.
/projects/:id/maturityreadThe project's maturity tier and what the next tier requires.
/projects/:id/maturitywriteSet the maturity tier.
Body: { tier }
/projects/:id/sharereadSharing state: private, team or public.
/projects/:id/sharewriteChange who can see the project.
Body: { visibility: "PRIVATE" | "TEAM" | "PUBLIC" }
/projects/:id/leadsreadLeads captured by the project's forms.
Builds and edits
/buildswriteCreate a project and start a full agentic build from a plain-language prompt. The call returns as soon as the build is queued; follow it through /sessions.
Body: { name, prompt, description?, framework? ("nextjs" default), projectType? ("web-app" default; "mobile-app" for Expo), language?, styling?, visibility? }
Returns 202 { project, build: { queued, projectId, jobId } }
/projects/:id/buildwriteStart or restart a build on an existing project from a prompt. Existing requirements are kept and the prompt is layered on top.
Body: { prompt, mode? ("full" default | "incremental" | "debug"), framework?, projectType? }
Returns 202 { queued, projectId, jobId }
/projects/:id/editswriteAsk the agent to change the project. Runs in the background; poll the returned session for progress and the result.
Body: { instruction, asProposal? (review before it lands), pushToGitHub? (default true), runBuildValidation? (default true) }
Returns 202 { queued, projectId, editJobId, sessionId }
/projects/:id/resume-editwriteResume an edit that paused partway (usage limit, restart).
/projects/:id/github-pullwritePull the connected GitHub repository into the project.
Body: { mode?: "regular" | "full", branch? }
Files and versions
/projects/:id/fileswriteWrite one file. Creates it if it does not exist.
Body: { path, content, saveToStorage? (default true), pushToGitHub? (default false) }
/projects/:id/downloadreadDownload the project as a zip, or a single file, or a saved version.
Query: fileId? for one file, versionId? for a saved version.
Returns application/zip (or the file's own content type).
/projects/:id/versionsreadSaved versions (snapshots) of the project.
/projects/:id/versionswriteSnapshot the project as a named version.
Body: { name?, description?, label? }
/projects/:id/versionswriteDelete a saved version.
Query: versionId
/projects/:id/screenshotreadThe latest screenshot of the running project.
/projects/:id/screenshotwriteTake a fresh screenshot.
Hosting and deploys
/projects/:id/runtimereadWhether the hosted app is awake or asleep, and how long since it was last used. Sleeping is normal, not an error.
/projects/:id/runtimewriteKeep the hosted app warm instead of letting it sleep when idle.
Body: { keepWarm: boolean }
/projects/:id/self-host-deployreadStatus of the project on Nexugen hosting (its <slug>.nexugen.app subdomain).
/projects/:id/self-host-deploywriteDeploy (or redeploy) the project to Nexugen hosting.
/projects/:id/self-host-deploywriteTake the project off Nexugen hosting.
/projects/:id/deployreadDeployment history for the GitHub and Vercel pipeline.
/projects/:id/deploywriteRun the external pipeline: save to storage, push to GitHub, deploy to Vercel.
Body: { environment: "PREVIEW" | "STAGING" | "PRODUCTION", pushToGitHub?, deployToVercel?, isPrivate?, customDomain?, autoVersion?, envVars? }
/projects/:id/web-buildreadStatus of the web export of an Expo / React Native project.
/projects/:id/web-buildwriteExport an Expo / React Native project for the web and host it.
/projects/:id/mobile-buildreadStatus and artifacts of native mobile builds.
/projects/:id/mobile-buildwriteStart a native build of a mobile project.
Body: { platforms: ["android" | "ios"] }
Domains and environment
/projects/:id/domainsreadCustom domains attached to the project and their verification state.
/projects/:id/domainswriteAttach a custom domain. The response includes the DNS record to add.
Body: { domain }
/projects/:id/domains/verifywriteCheck the domain's DNS records and mark it verified when they resolve. Call again if DNS has not propagated yet.
Body: { domain }
/projects/:id/domainswriteMake a verified domain the project's primary domain.
Body: { domain }
/projects/:id/domainswriteDetach a custom domain.
Body: { domain }
/domains/searchreadSearch domains to buy: availability and yearly price across common TLDs for a name or keyword.
Query: q (a name or keyword, e.g. "sunrise-bakery" or "sunrisebakery.com"). Limited to 20 searches per minute per account.
Returns { results: [{ domain, available, priceUsd, isPremium }] }
/projects/:id/domains/purchasewriteBuy a domain for the project. Re-checks availability and price, then opens a checkout. After payment the domain is registered, pointed at Nexugen, attached to the project and given a certificate.
Body: { domain, years? (1 to 10, default 1) }. Project owner only.
Returns { url, price, domain, years }. Open url in a browser to pay; nothing is registered until payment succeeds.
/projects/:id/env-varswriteThe project's environment variables. Values are secrets, so this needs a write key.
/projects/:id/env-varswriteSet an environment variable (create or update).
Body: { key, value, description?, isSecret?, isRequired? }
/projects/:id/env-varswriteRemove an environment variable.
Body: { key }
/projects/:id/env-recommendationsreadVariables the project's code expects that are not set yet.
Sessions
/sessionsreadAgent runs you can see: builds, edits and deploys on your projects, plus any a teammate shared.
Query: projectId?, active=1 for live runs only, limit (default 25, max 100).
Returns { sessions: [{ id, projectId, projectName, kind, status, title, situation, eventCount, createdAt, endedAt, ... }] }
/sessions/:idreadOne run: its status (RUNNING, AWAITING_INPUT, IDLE, DONE, FAILED, CANCELLED), current situation, and your access to it.
/sessions/:id/eventsreadThe run's event log: phases, agent output, decisions asked, results. Poll with after=<last seq> to tail it.
Query: after (seq, default 0), limit (default 200, max 500).
Returns { events: [{ seq, type, payload, actorId, createdAt }] }
/sessions/:id/eventswriteTalk to a live run: send a message, steer it at the next phase boundary, or answer a decision it is waiting on.
Body: { type: "user.message" | "user.steer" | "decision.answer", text, decisionId? (required for decision.answer) }
/sessions/:id/cancelwriteStop a run.
/sessions/:id/handoffwriteHand a run to a teammate.
Body: { toUserId, note? }
Pilot
/projects/:id/pilot/turnspilot:askAsk Pilot to do something in the app. Streams the turn as server-sent events by default; every event has an id, so a dropped connection resumes from GET .../turns/:turnId/events with Last-Event-ID. Changes that need the owner still wait for approval.
Body: { message, attachmentIds? }. Query: wait=true for one JSON reply when the turn ends, or async=true for { turnId } at once. Header: Idempotency-Key (a retry with the same key never starts a second turn).
Returns text/event-stream of { type: "turn.started" | "text" (the whole reply so far) | "activity" | "change" | "done" | "error", ... }; with wait=true, { turnId, status, reply, changes, changeIds, editJobIds, messageId }
/projects/:id/pilot/turns/:turnIdreadA turn's state: running, completed, failed or cancelled, with the reply and changes once it ends.
/projects/:id/pilot/turns/:turnId/eventsreadThe turn's event stream from the start, or after Last-Event-ID (header) or after=<id> (query). Replays what was missed, then follows the turn live. Kept for 5 minutes after the turn ends.
Returns text/event-stream, same events as POST .../turns
/projects/:id/pilot/turns/:turnId/cancelpilot:askStop a running turn. Changes it already made stay, and can be undone.
/projects/:id/pilotreadPilot's view of the app: what it can do there, what needs attention now (suggestions), recent changes, free tasks left, and the last 24 hours of conversation.
/projects/:id/pilot/messagesreadConversation history, newest page first.
Query: since, until (ISO dates), cursor (from nextCursor), limit.
Returns { messages, hasOlder, nextCursor, changes }
/projects/:id/pilot/changesreadChanges Pilot made or proposed on the app, newest first.
Query: status (proposed | applied | rejected | undone), limit (default 20, max 100).
Returns { changes: [{ id, kind, status, summary, preview, createdAt, appliedAt, undoneAt, error }] }
/projects/:id/pilot/changes/:changeId/:actionpilot:approveApprove or reject a change waiting for the owner, or undo one that was made. :action is approve, reject or undo. Needs a key with the Pilot approve scope.
Header: Idempotency-Key (optional).
Returns { change }
/projects/:id/pilot/attachmentspilot:askUpload a file (multipart, field "file") for Pilot to use in the next turn; pass the returned id in attachmentIds.
/projects/:id/pilot/clips/:messageIdreadThe short shareable clip of a task Pilot did on the app's screen, when one was made.
/pilot/appswriteConnect an app Nexugen does not host, for Pilot to run: its database, a store platform or a website. action "test" checks the connection and saves nothing; "connect" tests again, saves the credentials encrypted and creates the outside app. Pilot then works on it like any other app (turns, changes, screen).
Body: { action: "test" | "connect", kind: "database" | "platform" | "website", name?, ... }. database: connectionString, siteUrl?, adminUrl?. platform: provider "woocommerce" (siteUrl, consumerKey, consumerSecret) | "shopify" (shopDomain, accessToken) | "wordpress" (siteUrl, username, appPassword) | "stripe" (apiKey, siteUrl?). website: siteUrl, adminUrl?, loginEmail?, loginPassword?
Returns test: { ok, message, name }; connect: { ok, projectId, name, message } (201)
/projects/:id/app-assistantreadPilot for your users: the assistant inside the app for the people who use it, for apps built on Nexugen and outside apps alike. Whether it is on, what it knows (pages and actions, each allow, ask or deny), its settings, spending this month and recent questions; for outside apps also where it learns the app, which sites are proven, and the install snippets (script tag, React component, coding-agent prompt).
/projects/:id/app-assistantwriteTurn Pilot for your users on or off, read the app again, change settings, set an action to allow, ask or deny, or add actions by hand. A Nexugen app gets the tag added and redeploys. An outside app (any stack) learns from a GitHub repo, an OpenAPI spec, its live pages or a platform preset, and only runs on sites proven to be the owner's (the tag, /.well-known/nexugen-pilot.txt, or a DNS TXT record). It spends the owner's credits up to the monthly limit.
Body: { action: "enable" | "disable" | "scan" | "install" } | { action: "settings", settings: { greeting?, monthlyCap?, model?: "fast" | "smart", audience?: "everyone" | "signed-in", pageActions?, origins?, apiBase? } } | { action: "toggle", name, on } | { action: "policy", name, policy: "allow" | "ask" | "deny" } | { action: "sources", sources: { github?: "owner/repo" | { owner, repo, branch? } | null, openapi?: { url?, text? } | null, crawl?: boolean, preset?: "woocommerce" | "shopify" | "wordpress" | null } } | { action: "action_save", item: { name, label, method, path, params?, description?, audience?, base? } } | { action: "action_remove", name } | { action: "origin_add" | "origin_remove", origin } | { action: "verify", origin? }
/projects/:id/pilot/screenpilot:screenPilot's live screen as server-sent events: the app as Pilot sees and drives it, with its cursor, clicks, drawings and step captions. Nothing is sent while the screen is private (someone signing in).
Returns Events: frame { jpeg (base64), w, h } | page { url, device, viewport } | overlay { type: cursor | ripple | highlight | circle | arrow | box | underline | caption | step | clear | control | private, ... } | closed { reason }
/projects/:id/pilot/screen/statuspilot:screenWhether the screen is open, and if so on which site, whether it is private and whether someone else has control.
Returns { open, private, origin, mode, signedIn }
/projects/:id/pilot/screen/openpilot:screenOpen the screen on the app (or switch it between desktop and phone) without asking Pilot anything. The same guards apply as when Pilot opens it.
Body: { where? (a page of the app, e.g. "/orders"), device? ("desktop" | "phone") }
/projects/:id/pilot/screen/closepilot:screenClose the screen.
/projects/:id/pilot/screen/inputpilot:controlUse the app on the screen yourself, as the owner: take control, click, type, press a key or scroll, then hand back. Needs a key with the Pilot control scope.
Body: { kind: "control", on } | { kind: "click", x, y } | { kind: "type", text } | { kind: "key", key } | { kind: "scroll", dy }. x and y are in the page's own pixels (see viewport on the page event).
/projects/:id/pilot/screen/embedspilot:screenA link to a page showing Pilot's live screen, made to go in an <iframe> on your own site. Watch-only unless control is asked for (which needs the control scope). The link stops working when it expires or when the key is revoked.
Body: { ttlSeconds? (default 3600, max 86400; 3600 with control), control? (boolean), origins? (sites allowed to frame it, e.g. ["https://example.com"]; default any) }
Returns { url, expiresAt, control, origins }
/pilot/turnspilot:askAsk the account-wide Pilot (questions about your account and apps, or "build me..."). Same streaming, wait and async modes as a project's turns.
Body: { message, projectId? }
/pilot/turns/:turnIdreadAn account-wide turn's state.
/pilot/turns/:turnId/eventsreadAn account-wide turn's event stream, resumable like a project turn's.
/pilot/turns/:turnId/cancelpilot:askStop a running account-wide turn.
/pilot/changes/:changeId/:actionpilot:approveApprove or reject a proposal the account-wide Pilot made (:action is approve or reject).
Webhooks
/webhooksreadYour webhook endpoints, each with its last five deliveries, and the list of available events.
/webhookswriteRegister an endpoint. The signing secret is returned once, in this response only.
Body: { url, events? (subset of the available events; empty = all), description? }
Returns 201 { endpoint: { id, url, events, secret } }
/webhookswritePause, resume or re-subscribe an endpoint, or send it a test delivery.
Body: { id, isActive?, events?, action?: "test" }
/webhookswriteRemove an endpoint.
Query: id
Rate limits
Each key allows 100 requests per minute by default. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get 429 with a Retry-After header, and the rejected request does not count.
Some actions have their own limits on top, the same ones the dashboard has: edits are limited to 15 per 10 minutes per account, and builds and edits spend AI credits, so a 402 means the account needs credits, not that the key is wrong.
Errors
Errors are JSON with a human-readable message and a stable code:
{ "error": "This key can only read. POST /api/v1/projects/…/edits needs a key with writes allowed.", "code": "insufficient_permission" }| 400 | invalid_request | A required field is missing or malformed. |
| 401 | missing_api_key, invalid_api_key, revoked_api_key, expired_api_key | No usable key on the request. |
| 402 | (from the platform) | Not enough AI credits for a build or edit. |
| 403 | insufficient_permission | A read key on a write endpoint, or a project the owner cannot act on. |
| 404 | not_found | Unknown endpoint, or a project or session the owner cannot see. |
| 405 | method_not_allowed | The path exists, the method does not. |
| 429 | rate_limited | Per-key or per-action limit hit. Honour Retry-After. |
| 502 | upstream_error | The platform could not complete the request. Safe to retry. |
Endpoints that forward to the platform return that route's own error shape, which is always { "error": "…" } and may add details.
Pilot from code
Ask Pilot to do things in an app and watch it work. A turn streams as server-sent events: turn.started first, then text (the whole reply so far, not a fragment), activity as it uses its tools, change for each change it makes or proposes, and done or error.
curl -N -X POST https://nexugen.app/api/v1/projects/$PROJECT_ID/pilot/turns \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "message": "How many orders are waiting to ship?" }'Add ?wait=true to get one JSON reply when the turn ends, or ?async=true to get the turn id at once and follow it with GET .../pilot/turns/:turnId or the pilot.turn.completed webhook. Every event carries an id; if the connection drops, the turn keeps going, and GET .../pilot/turns/:turnId/events with Last-Event-ID picks up where you left off. Events are kept for five minutes after a turn ends.
Changes that need the owner wait for approval exactly as they do in the dashboard. There is no flag that skips it: approve with POST .../pilot/changes/:changeId/approve using a key with pilot:approve, ideally a different key from the one that asks. Keys pasted into a message are hidden before Pilot sees them, and secrets never come back in a reply. Turns cost the same as in the dashboard, free monthly tasks included, and one turn runs at a time per person per app.
Pilot's screen
Pilot works in your app on a live screen, the one you see beside the chat in the dashboard. With a pilot:screen key you can watch it from code, or put it on your own site in an iframe. It is your own screen for that app: open it in the dashboard and from code and both show the same thing.
GET .../pilot/screen streams it as server-sent events: frame (a JPEG, base64), page (address, desktop or phone, size), overlay (Pilot's cursor, clicks, drawings and step captions) and closed. Open it yourself with POST .../pilot/screen/open, or it opens when Pilot needs it. Keys and passwords on the page are painted over in every frame, and while someone is signing in on the screen no frames are sent at all.
To embed it, make a link and put it in an iframe:
curl -X POST https://nexugen.app/api/v1/projects/$PROJECT_ID/pilot/screen/embeds \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ttlSeconds": 3600, "origins": ["https://example.com"] }'
# => { "url": "https://nexugen.app/embed/pilot-screen/eyJ...", "expiresAt": "..." }
<iframe src="https://nexugen.app/embed/pilot-screen/eyJ..." width="960" height="640"
style="border:0" allow="fullscreen"></iframe>A link is watch-only unless you ask for "control": true (that needs pilot:control and lasts an hour at most). origins limits which sites may frame it; leave it out and any site can. Anyone with the link sees the screen until it expires, so make links on your server when a page loads rather than storing them. Revoking the key turns off every link it made. Add ?chrome=0 to hide the address bar and ?theme=light for a light surround.
Pilot for your users
A web app built on Nexugen can give the people who use it their own assistant: a chat inside the app that knows it from its code, answers their questions and does what they ask, through the app's own actions and pages, in their browser, with their own access. Each change waits for their Confirm, and they can talk instead of typing. It is off until you turn it on, spends your credits up to a monthly limit you set, and shows "Powered by Nexugen".
curl -X POST https://nexugen.app/api/v1/projects/$PROJECT_ID/app-assistant \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "action": "enable" }'Turning it on reads the app, adds one script tag to its layout and redeploys. Then { "action": "settings", "settings": { "monthlyCap": 2000, "model": "smart" } } changes how it works, { "action": "toggle", "name": "cancel_order", "on": false } switches one action off, and GET .../app-assistant shows what it knows, what it spent and what people asked. Staff-only actions start off. Each action can be set to allow, ask (always confirm first) or deny with { "action": "policy", "name": "refund_order", "policy": "ask" }, and action_save adds one by hand.
Apps not built on Nexugen get it too, in any language or framework. Connect the app (a website is enough, see below), then tell it where to learn the app:
curl -X POST https://nexugen.app/api/v1/projects/$PROJECT_ID/app-assistant -H "Authorization: Bearer $NEXUGEN_API_KEY" -H "Content-Type: application/json" -d '{ "action": "sources", "sources": { "github": "acme/app",
"openapi": { "url": "https://api.example.com/openapi.json" }, "crawl": true } }'
curl -X POST https://nexugen.app/api/v1/projects/$PROJECT_ID/app-assistant -H "Authorization: Bearer $NEXUGEN_API_KEY" -H "Content-Type: application/json" -d '{ "action": "origin_add", "origin": "https://app.example.com" }'Add it with one script tag in any stack, or <PilotForUsers appKey="pa_..." /> from nexugen/react, whose getAuthHeaders covers APIs on another address or with bearer tokens (the token stays in the visitor's browser). It only runs on sites you prove: the tag on the home page, a file at /.well-known/nexugen-pilot.txt containing the key, or a TXT record at _nexugen-pilot.<host>. It does not run inside native mobile apps, canvas-only interfaces or cross-origin iframes.
Apps not built on Nexugen
Pilot can also run an app Nexugen does not host: connect its database (Postgres or MySQL), a Shopify, WooCommerce, WordPress or Stripe account, or any website. Test first with "action": "test"; nothing is saved. Credentials are stored encrypted and never come back.
curl -X POST https://nexugen.app/api/v1/pilot/apps \
-H "Authorization: Bearer $NEXUGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "action": "connect", "kind": "platform", "provider": "shopify",
"shopDomain": "my-shop.myshopify.com", "accessToken": "shpat_..." }'
# => { "ok": true, "projectId": "..." } then use it like any app: /projects/:id/pilot/turnsAsk Pilot for a feature in an outside app and it adds it to the app's own GitHub repository: it asks you to connect the repository (the Nexugen GitHub App) and once whether changes go straight to main or to a branch with a pull request. The same agent that builds Nexugen apps writes the change, the repository's own checks run, and you get the pull request or commit. Merging and undoing wait for your Approve; your own CI/CD deploys it.
Webhooks
Register an endpoint (POST /webhooks, or under Settings) and the platform POSTs to it when work finishes. Subscribe to specific events or leave events empty for all of them.
| project.created | A project is created. |
| build.started | A full build begins. |
| build.failed | A build stops with an error. |
| edit.completed | An agent edit finishes and its result is saved. |
| deploy.succeeded | A deploy to Nexugen hosting completes. |
| pilot.turn.completed | Pilot finishes a turn: its reply and the changes it made or proposed. |
| pilot.turn.failed | A Pilot turn stops with an error. |
| pilot.change.pending | Pilot proposes a change that waits for the owner's approval. |
| pilot.change.applied | A Pilot change is made, directly or after approval. |
| pilot.change.undone | A Pilot change is undone. |
| build.succeeded | Accepted in subscriptions, not emitted yet. |
| deploy.failed | Accepted in subscriptions, not emitted yet. |
Each delivery is a JSON POST:
POST https://your-server.example/nexugen
content-type: application/json
user-agent: Nexugen-Webhooks/1
x-nexugen-event: edit.completed
x-nexugen-timestamp: 1787600000000
x-nexugen-signature: sha256=3f1c…
{ "event": "edit.completed", "createdAt": "2026-08-24T20:48:19.640Z", "data": { … } }The signature is HMAC-SHA256 with the endpoint's secret over timestamp + "." + rawBody. Verify it against the raw request body, before any JSON parsing, and compare in constant time:
import crypto from 'node:crypto';
export function verifyNexugenWebhook(headers, rawBody, secret) {
const timestamp = headers['x-nexugen-timestamp'];
const received = String(headers['x-nexugen-signature'] || '').replace(/^sha256=/, '');
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
return (
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
);
}Respond with any 2xx within 8 seconds. After 20 consecutive failures the endpoint is paused and shows as such in Settings; fix it and set isActive: true to resume. PATCH /webhooks with action: "test" sends a test delivery.