API contract

The rules for an agent running an app on Embarko with no person watching. Each action lists its method, auth, parameters, response, states, errors, retry rule, and what happens if you call it twice.

Read How to behave first. It prevents the costly mistakes. The per-action reference follows.

All calls are on https://ship.embarko.ai.

How to behave

What names an app?

X-App-Name is the app's identity. It is also the public subdomain, so it is unique across the whole platform, not per company. There is no project id and no create step. The first deploy of a name creates the app. Every later deploy of that name updates it.

• To update an app, deploy the same name again. Do not invent my-app-2. A redeploy of a name you own returns 2xx and replaces the running app in place. It keeps its env vars, domains and DATA_DIR data.
• 409 app_name_taken means a different company owns the name. It does not mean "your app already exists". That case is a normal successful redeploy. Pick a different name. Do not retry the same one.
• Exception: an unclaimed anonymous app that you just deployed. Redeploy it with a token to claim it.

Store the app name you used. It is the only handle you need for status, logs, env vars, history, rollback and Showcase.

Which calls need a token?

Everything is on ship.embarko.ai. The path prefix does not tell you the auth rule. Use this table:

Two path shapes share the host:

• Under /apps: only deploy (POST /apps), status, logs and app feedback (/apps/<name>/status, /logs, /customer-query).
• Under /api/apps/<name>: everything else that names an app. That is the app itself (GET, rename with PATCH, DELETE), domains, analytics, env vars, deployment history, rollback, showcase and slug-change.
• /apps/<name>/domains without /api is a 404.

The token:

• Is sent as Authorization: Bearer <token>.
• Is company-wide, not per app.
• Deploys only. It does not sign in to the dashboard.
• How to get one, and the two ways in that need no token (a connector, or signing in on embarko.ai), are in Authentication.

No header and a bad header are different. Leaving out Authorization is a valid anonymous deploy. A present but invalid token is always a hard 401. It is never downgraded to anonymous.

A claimed app answers 404, not 401, to a caller without the right token on the deploy host. It will not confirm the app exists to a non-owner. So 404 on status or logs means "not yours, or not found", never "definitely does not exist".

What does an error look like?

Every non-2xx response carries both fields:

{ "error": "Human-readable sentence that may change wording", "code": "machine_readable_code" }

• Branch on code. Never parse error.
• Some responses add fields that name the fix: details, detail, foundNestedAt, deployThisInstead, retainCount. Read them first. Several tell you exactly what to change.
• New fields may appear in any response over time. Branch only on fields named here and ignore the rest. Do not fail on an unknown key.

When should I retry?

Retrying a permanent error burns the rate limit and achieves nothing. Go by status class, with two exceptions:

• Backoff: wait 2s, then 5s, then 15s. Three attempts total, then stop and tell the user.
• Never retry in a tight loop. Never retry a 4xx.
• Rate-limited endpoints return the same response whether or not you hit the limit. A retry cannot tell you it worked. Treat one call as your only call.

What happens if I call it twice?

Nothing takes an idempotency key.

Which actions are async, and what are the states?

Two actions answer 202 at once and finish in the background:

• Deploy (POST /apps): poll links.status.
• Rollback: poll the returned deployment.

202 means accepted, never live. Reporting a URL on the 202 is the most common autonomous failure.

States come from the status field of GET .../status:

building / publishing ──▶ starting ──▶ live     → report the URL, then do what `next` says
                      └─▶ failed               → read links.logs, fix, redeploy
                                  └─▶ crashed  → built, but stops on start: read links.logs

How to poll:

1. Server app: poll every 10 seconds.
2. Static site: usually no polling. Its deploy reply is already live.
3. Static site that came back publishing (a very large site): poll every 2 seconds.
4. Give up after 10 minutes and read the logs.

How is every reply shaped?

POST /apps, GET .../status and GET .../logs share four fields:

• Errors keep error and code (branch on code) and add next and links.
• links.feedback is on every reply. Report anything failing or confusing there.
• Use the links the reply gives you. Do not build them from the app name. That way you keep working if the address format changes.

---

Deploy or redeploy an app

POST https://ship.embarko.ai/apps · async · not idempotent

Auth: optional.

• Leave out Authorization for an anonymous deploy.
• Send Bearer <token> to create or update an app your company owns, or to claim an anonymous one.

Required:

Or send the source as JSON. See JSON source below.

Optional:

Example request:

tar -czf /tmp/my-app.tar.gz --exclude=node_modules --exclude=.git \
  --exclude='.env*' -C /path/to/app .

curl -X POST "https://ship.embarko.ai/apps" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "X-App-Name: my-app" \
  -H "X-App-Version: $(git rev-parse --short HEAD)" \
  -H "X-App-Type: portfolio" \
  -H "X-Agent-Name: claude" \
  -F "source=@/tmp/my-app.tar.gz"

App type (X-App-Type). Optional, but send it when you can. Use the example label that fits best, or your own short phrase. To choose it:

1. If what the app does is clear from what you built or what the user said, use that. Don't ask.
2. If it isn't clear, ask the user once, when you confirm the app name: "What kind of app is this (for example a personal website, portfolio, task manager or feedback system)? You can skip this."
3. If the user skips, leave the header out. The deploy works without it.

Send it once. A redeploy without the header keeps the earlier value. A redeploy with a new value replaces it. It does not change how the app is built or run.

Agent name (X-Agent-Name). Optional, but always send it. It is the name of the agent or product you run as.

• The app's deploy history shows it, so the owner sees which agent deployed what.
• It is only a label. It changes nothing you can do, and nothing checks it.
• Send the same value on rollback and on env var writes and applies. Those also create deploy history entries.

Sending the source as JSON. Use this when you can't upload a file, for example through an MCP tool or from a sandbox that can't make outbound requests. Send Content-Type: application/json. Auth, response, errors and build are the same as the multipart upload.

• Limits: 25 MB body, 2000 files. For bigger apps, use the multipart upload.
• Leave out node_modules, build output, .git and .env*. The platform installs and builds for you.
• Send text files as plain text. Use base64 only for binaries.

curl -X POST "https://ship.embarko.ai/apps" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my-app",
    "files": [
      { "path": "index.html", "content": "<h1>Hello</h1>" },
      { "path": "logo.png", "content": "iVBORw0KGgo...", "encoding": "base64" }
    ]
  }'

Success: 202 Accepted (a server app, deployed without a token):

{
  "success": true,
  "status": "building",
  "app": {
    "name": "my-app",
    "kind": "service",
    "claimed": false,
    "expiresAt": "2026-09-30T10:04:00.000Z"
  },
  "next": "Building: poll links.status every 10 seconds until it says \"live\" or \"failed\".",
  "links": {
    "status": "https://ship.embarko.ai/apps/my-app/status",
    "feedback": "https://ship.embarko.ai/apps/my-app/customer-query"
  }
}

A static site (an index.html and assets, nothing to build) is published while the request waits, so the reply is the result:

{
  "success": true,
  "status": "live",
  "app": { "name": "my-site", "kind": "static", "claimed": false, "expiresAt": "2026-09-30T10:04:00.000Z" },
  "next": "Live: give the user links.app and tell them it will be deleted at 2026-09-30T10:04:00.000Z unless claimed. To claim it, follow links.help.",
  "links": {
    "app": "https://my-site.embarko.app",
    "feedback": "https://ship.embarko.ai/apps/my-site/customer-query",
    "help": "https://ship.embarko.ai/capabilities/claim"
  }
}

Other reply variants:

• With a token: app.claimed is true and there is no expiresAt.
• A redeploy that claims a temporary app: next starts with "Claimed: this app is now permanent".
• A server app replaced by a static site: next starts with a warning. Its server is removed and it can't become a server app again.
• app.expiresAt is the exact deletion time of a temporary app. Give the user that time, not a vague "24 hours". There is no reminder email.

Failure: 409:

{
  "error": "App name \"my-app\" is already in use by a different company",
  "code": "app_name_taken",
  "next": "That name belongs to someone else: pick a different one.",
  "links": {
    "feedback": "https://ship.embarko.ai/api/public/customer-query"
  }
}

Before the app exists (a rejected name, a bad token), links.feedback is the public feedback address. It takes the user's email in the body.

Errors:

After a 202: poll links.status until status is live, failed or crashed. Report the URL only on live.

---

Check deploy status

GET https://ship.embarko.ai/apps/<app-name>/status · sync · safe

Auth: none while the app is an unclaimed anonymous deploy. The owning company's token once claimed.

Parameters: none beyond the app name in the path.

Live, not claimed yet: 200. This reply brings up claiming:

{
  "status": "live",
  "app": {
    "name": "my-app",
    "kind": "service",
    "claimed": false,
    "expiresAt": "2026-09-30T10:04:00.000Z"
  },
  "next": "Live: give the user links.app and tell them it will be deleted at 2026-09-30T10:04:00.000Z unless claimed. To claim it, follow links.help.",
  "links": {
    "app": "https://my-app.embarko.app",
    "feedback": "https://ship.embarko.ai/apps/my-app/customer-query",
    "help": "https://ship.embarko.ai/capabilities/claim"
  },
  "deploy": {
    "status": "success"
  }
}

Live and claimed: 200. This reply brings up Showcase:

{
  "status": "live",
  "app": {
    "name": "my-app",
    "kind": "service",
    "claimed": true
  },
  "next": "Live: give the user links.app. If they want it listed publicly, follow links.help.",
  "links": {
    "app": "https://my-app.embarko.app",
    "feedback": "https://ship.embarko.ai/apps/my-app/customer-query",
    "help": "https://ship.embarko.ai/capabilities/showcase"
  },
  "deploy": {
    "status": "success"
  }
}

Failed: 200. error names the cause. links.logs points at stderr:

{
  "status": "failed",
  "app": {
    "name": "my-app",
    "kind": "service",
    "claimed": true
  },
  "error": "Exit code 127 means a command in the build script was not found inside the build image. …",
  "next": "Build failed: read links.logs, fix the cause, and redeploy with the same name. If it isn't clear, report it to links.feedback (see links.help).",
  "links": {
    "feedback": "https://ship.embarko.ai/apps/my-app/customer-query",
    "logs": "https://ship.embarko.ai/apps/my-app/logs?stream=stderr",
    "help": "https://ship.embarko.ai/capabilities/feedback"
  },
  "deploy": {
    "status": "failed"
  }
}

• States: status is one of building, publishing, starting, live, failed, crashed, not_deployed, unknown. See Async behaviour and states.
• A sleeping app (scale to zero) reads live. next says it wakes on the first request.
• Static sites have no server. live means the files are published. There is no separate health check, and next never mentions logs.
• Deprecated: deploy.status (in_progress, success, failed, unknown) stays for older copies of the deploy script. Read status instead. deploy will be removed.
• Not durable: status reflects the most recent attempt held in memory. Use deployment history for durable history.

Errors: both carry next and links.feedback.

---

Read logs

GET https://ship.embarko.ai/apps/<app-name>/logs · sync · safe

Auth: same rule as status.

Optional: ?stream=stderr (default stdout).

Success: 200:

{
  "available": true,
  "allocId": "b457e652-...",
  "stream": "stdout",
  "logs": "...tail of recent output..."
}

• logs is about the last 8KB of output.
• It is a snapshot at call time, not a stream. Call again to follow along.
• Always the most recent allocation, healthy or not.
• No long-term retention and no retention guarantee.
• When the latest build failed, the reply holds the build output instead, with source: "build" and a next saying the cause is in there. The failing command is named there. This includes a failed redeploy while the previous version still runs.

Static site: 200. Nothing runs on the server, so there are no logs:

{
  "status": "not_available",
  "available": false,
  "reason": "This is a static site, so there are no app logs: nothing runs on the server.",
  "app": {
    "name": "my-site",
    "kind": "static"
  },
  "next": "Static sites have no logs: if a page looks wrong, check the files and redeploy (see links.help).",
  "links": {
    "feedback": "https://ship.embarko.ai/apps/my-site/customer-query",
    "help": "https://ship.embarko.ai/capabilities/static-sites"
  }
}

Nothing deployed yet: 200:

{
  "available": false,
  "reason": "No allocation has ever been created for this app yet",
  "next": "No logs yet because the app hasn't started: check links.status.",
  "links": {
    "status": "https://ship.embarko.ai/apps/my-app/status",
    "feedback": "https://ship.embarko.ai/apps/my-app/customer-query"
  }
}

---

List deployment history

GET https://ship.embarko.ai/api/apps/<app-name>/deployments · sync · safe

Auth: deploy token, always.

Returns: the app's deployments, newest first.

• Each entry has at least an id, a status, and the version deployed.
• Use the id for GET /deployments/<id> and for rollback.
• Only entries with status success are valid rollback targets.

Each entry also says who made it:

GET .../deployments/<id> returns one entry. Use it to poll a rollback to completion.

Errors:

---

Roll back to an earlier deployment

POST https://ship.embarko.ai/api/apps/<app-name>/rollback · async · not idempotent

Auth: deploy token, always.

Optional body:

• {} or no body: go back to the most recent successful deployment that isn't the current one. Usually what you want.
• {"deploymentId": "..."}: pick a specific version. Read the history first. rollbackTarget: true marks the valid targets.

Example:

curl "https://ship.embarko.ai/api/apps/my-app/deployments" \
  -H "Authorization: Bearer $DEPLOY_TOKEN"

curl -X POST "https://ship.embarko.ai/api/apps/my-app/rollback" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" -H "Content-Type: application/json" \
  -H "X-Agent-Name: claude" \
  -d '{"deploymentId": "<deploymentId>"}'   # or '{}' for the previous good one

Success: 202 Accepted: { accepted, deploymentId, rolledBackTo: { id, version }, statusUrl, terminal: false }.

• Rollback creates a new history entry pointing at the old image. History is never rewritten.
• Poll until its status leaves in_progress.
• No rebuild. It reruns an existing image under current configuration: today's env vars and domains, not those of the original deploy.

Failure: 422:

{ "error": "Cannot roll back: the image is no longer available...", "code": "rollback_image_unavailable", "retainCount": 5 }

Errors:

---

Change an app's web address

POST https://ship.embarko.ai/api/apps/<app-name>/slug-change · async · not idempotent

Auth: deploy token, always.

Required: newName in the body.

This changes the URL itself. PATCH /api/apps/<name> is different: it changes the display name and leaves the URL alone.

Ask the user first. The old address stops working the moment the new one is live. There is no redirect, anything linking to it breaks, and someone else can claim the freed name. See escalation.

Example:

curl -X POST "https://ship.embarko.ai/api/apps/my-app/slug-change" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"newName": "my-better-app"}'

Success:

Poll GET https://ship.embarko.ai/api/slug-changes/<project-id> until terminal is true.

• state ends succeeded or failed.
• currentSlug always says where the app actually is.
• A failed migration leaves the app on its old address, untouched.

Errors:

Good to know:

• Slow for a live app: minutes, not seconds. It needs a fresh HTTPS certificate for the new hostname. The app is stopped while its stored data moves, and it keeps that data.
• Afterwards, deploy with the new name. A call to the old name gets 404 app_renamed with newName and a retryUrl. Follow that. Do not deploy a fresh app under the old name. That creates a second, empty app.
• A custom domain carries over and keeps working throughout. An app with one keeps its real address.
• A Showcase listing follows the rename. Its page moves to /showcase/app/<new-name>.

---

Environment variables

Base: https://ship.embarko.ai/api/apps/<app-name>/env-vars. Deploy token always.

Key rule: ^[A-Za-z_][A-Za-z0-9_]*$.

Example:

curl -X PUT "https://ship.embarko.ai/api/apps/my-app/env-vars/STRIPE_KEY" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "sk_live_..."}'

curl -X POST "https://ship.embarko.ai/api/apps/my-app/env-vars/apply" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "X-Agent-Name: claude"

A write only stores the value. The running app does not see it until you do one of these:

1. Call POST /env-vars/apply.
2. Deploy again.
3. Send "apply": true on the write. It applies at once with no rebuild (202, with a statusUrl to poll).

Leave apply off to batch several writes into one restart. Writing a key and reporting success without applying leaves the app on the old value.

Good to know:

• Send X-Agent-Name on the apply call and on any write with "apply": true. Applying creates a deploy history entry. On these calls a malformed name is ignored, not rejected.
• Values are write-only. You can never read a secret back, with or without the token. If you need a value, ask the user.
• Static sites have no env vars. Setting or applying one on a static site (app.kind: "static") is refused with 409 not_supported_for_static. Put configuration in the site's files, or deploy it as a server app under a new name. Listing and deleting still work.

---

List on Showcase

PUT https://ship.embarko.ai/api/apps/<app-name>/showcase · sync · idempotent

Auth: deploy token. The app must be claimed. A temporary app has no token to call this with.

Only when the user wants it listed. Then:

1. Check for an existing listing: GET https://ship.embarko.ai/api/public/showcase/apps/<app-name> (no token). An app has one listing, reused on the public gallery and every event page. If it exists, reuse its details and send only what changes.
2. Draft the rest from the project. Infer tagline, what it does, the AI that built it, a category and tags from the code, README and live app. Write for people searching: what it does, who it is for, the problem it solves, in plain words.
3. Ask only for what you can't know: who built it, a profile link, and whether to show a contact email. Never invent creator details, links, screenshots, an event slug or a code.
4. Show the user the listing and get their go-ahead before the PUT. A public listing is live the moment it is sent.

Body:

Example:

curl -X PUT "https://ship.embarko.ai/api/apps/my-app/showcase" \
  -H "Authorization: Bearer $DEPLOY_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "collectionSlug": "walkover",
    "code": "Z3H63FRD",
    "name": "My App",
    "tagline": "One line about it",
    "description": "What it does",
    "story": "Why it was built",
    "creatorName": "Jane",
    "creatorProfile": "https://x.com/jane",
    "contributorEmails": ["jane@example.com", "sam@example.com"],
    "builtWith": "Claude",
    "category": "AI Tool",
    "tags": ["chat", "notes"],
    "screenshotUrls": ["https://example.com/1.png"],
    "videoUrl": "https://youtube.com/watch?v=abc",
    "customHtml": "<section>...</section>"
  }'

Success: 201 on first listing, 200 on update. Both return the listing with status and a one-line next.

• A repeat call merges: only the fields you send change.
• "" clears a field and [] clears a list.
• A single-field update is fine and a retry is safe. There is no separate edit endpoint.

Approval:

After it's live, follow next. It asks you to help the user promote the app: short posts for each platform about what they built, who it helps and why to try it. If there is no video yet, it asks you to suggest a short demo. Qualifying approved videos get a year of Embarko Pro for that app.

Errors:

---

Request a deploy token

POST https://ship.embarko.ai/api/public/deploy-tokens/request · sync · not safe to repeat

Auth: none. Required body: {"email": "..."}.

1. Check first: look in $DEPLOY_TOKEN and ~/.embarko/credentials. If the user already has a token, don't request one.
2. Call it once. Never loop.
3. Ask the user to paste the token. It is emailed to that address and is never in the response. You cannot read it back, print it, or receive it.

Good to know:

• Always returns 202, whether or not the address exists and whether or not you hit a rate limit.
• A new address gets an account and company created automatically.
• Limits: 5/hour per email, 10/hour per IP. The response is the same either way, so a retry tells you nothing.

---

Send feedback as an agent

POST https://ship.embarko.ai/apps/<app-name>/customer-query · sync

Auth: same rule as status. None while unclaimed, token once claimed.

Required: header X-Agent-Name (free text), body type and message (1–5000 chars).

type says what kind of problem it was:

feature and feedback are still accepted too.

Errors:

No app yet? Use POST /api/public/customer-query with an email in the body. It needs no auth and is rate limited to 10/email, 20/IP and 500/hour globally.

---

Read the capability manifest

GET https://ship.embarko.ai/capabilities · sync · safe · no auth

A contents page: one line per topic, saying what it covers and where to read it. Open only the topic you need.

{
  "version": "2026-09-29",
  "about": "What Embarko can and can't do. Open the topic you need; each one answers fully on its own.",
  "topics": [
    { "topic": "deploy", "covers": "Uploading an app, what it needs to run here, and waiting for it to go live", "url": "https://ship.embarko.ai/capabilities/deploy" },
    { "topic": "custom-domain", "covers": "Using your own domain for an app, including the DNS step a person has to do", "url": "https://ship.embarko.ai/capabilities/custom-domain" }
  ],
  "links": { "all": "https://ship.embarko.ai/capabilities/all", "docs": "https://embarko.ai/docs/capabilities" }
}

GET https://ship.embarko.ai/capabilities/<topic> answers one question in full:

• Topics: deploy, static-sites, claim, files, env-vars, custom-domain, logs, rollback, scale-to-zero, showcase, feedback and not-supported.
• Common other names work too (domains, database, secrets, cron…).
• ?feature=<topic> on the contents URL does the same thing.
• An unknown topic is 404 unknown_topic with the list of topics.

GET https://ship.embarko.ai/capabilities/all returns the whole contract at once.

All three need no token and are cached for an hour (with an ETag). Read the topic before relying on a feature. It wins over any prose page, including this one.

---

Manage a live app

All on the deploy host under /api/apps/<name>, all with a deploy token.

Good to know:

• You cannot create the DNS record. Register and verify are yours. The record lives in the user's registrar account. Hand them what POST /domains returns and wait.
• Analytics 503 means the subsystem is unreachable. It is not zero traffic. Do not report it as such.
• Rename changes the display name only. PATCH does not move the slug (the URL). Moving the URL is change the web address, a much heavier call. It takes the app offline for minutes and kills the old address.
• Delete requires confirmAppName in the body. Missing or wrong is 400 confirmation_required and deletes nothing. Get the user's explicit go-ahead first. See escalation.
• Memory can't be changed. There is no agent call and no dashboard control. Reduce the app's footprint instead.

---

Related

• Capabilities: the same surface by feature, with limits.
• Troubleshooting: every error code and its fix.
• Overview: what Embarko is and when to choose it.