The Apposters API

Basics

The base URL is https://api.apposters.com, and every path on this page is relative to it: GET /app/sites means GET https://api.apposters.com/app/sites.

Get a token

Open Account, find API tokens, give the new token a name (what will use it), pick how long it lives - 30 days, 90 days, 1 year or never - and press Create token. The token starts with apo_ and is shown once: copy it then. Send it with every call:

Authorization: Bearer apo_...

A token acts as you: whoever holds it can change your projects and start payments. Keep it in an environment variable or a secret store, never in a web page, a URL, a commit or a log. You can revoke it on the same card at any time; from the next request on it answers 401.

Requests and answers

• Send JSON with Content-Type: application/json. Answers are JSON too, except logs (plain text) and live streams (server-sent events).
• An error is {"error": "What went wrong, in words", "code": "machine_readable"}; code is there when there is something to tell apart.
• 401 - no token, or one that is wrong, expired or revoked. 404 - not found, and also a project that belongs to someone else. 402 with "code": "payment_required" - a paid feature that is not paid for yet. 429 - a limit; try again later.
• Call the API from a server, a terminal or a CI job. Web pages on other sites are blocked by CORS on purpose: a token in a web page is a token anyone can read.

export APPOSTERS_TOKEN=apo_...          # from Account - API tokens
API=https://api.apposters.com
H="Authorization: Bearer $APPOSTERS_TOKEN"

curl -s "$API/agent/me" -H "$H"
# -> {"user": {"id": "...", "email": "you@example.com"}, "auth": "token", "token": {...}}

Quick start: from a repository to a running SaaS

The whole path in six calls. Only step 4 costs money: Embed App, which runs your app. You pay for it yourself on Stripe's page - the API hands you the link and never sees a card. Each step is explained in the sections below.

J="Content-Type: application/json"

# 1. Create a project from the repository
curl -s -X POST "$API/app/sites" -H "$H" -H "$J" \
  -d '{"github_url": "https://github.com/you/your-app", "name": "Your App"}'
# -> 201 {"id": "SITE_ID", "slug": null, ...}
SITE=SITE_ID

# 2. Generate the product site: a landing page, About, FAQ and a sign-in page
curl -s -X POST "$API/app/sites/$SITE/generate" -H "$H" -H "$J" \
  -d '{"kind": "template", "mode": "saas", "pages": ["about", "faq", "auth"]}'
# -> 202 {"job_id": "JOB_ID", "status": "running", ...}
JOB=JOB_ID
curl -s "$API/app/jobs/$JOB" -H "$H"
# -> {"status": "done", "next_job_id": "...", ...}  poll every few seconds, follow next_job_id

# 3. Check that the repository can run here
curl -s "$API/app/sites/$SITE/repo-check" -H "$H"

# 4. Unlock Embed App: open the Stripe link in a browser and pay
curl -s -X POST "$API/billing/embed/checkout" -H "$H" -H "$J" -d "{\"site_id\": \"$SITE\"}"
# -> {"id": "cs_...", "url": "https://checkout.stripe.com/..."}

# 5. Set the app up and deploy it
curl -s -X PUT "$API/app/sites/$SITE/deployment" -H "$H" -H "$J" -d '{"port": 3000, "build_mode": "auto"}'
curl -s -X POST "$API/app/sites/$SITE/deployment/deploy" -H "$H"
# -> 202 {"job_id": "...", "run_id": "..."}

# 6. Pick the address and publish the site
curl -s -X POST "$API/app/sites/$SITE/slug" -H "$H" -H "$J" -d '{"slug": "your-app"}'
curl -s -X POST "$API/app/sites/$SITE/publish" -H "$H" -H "$J" -d '{}'
# -> {"url": "https://your-app.apposters.com", ...}   the app answers at https://your-app.apposters.com/app/

Only need a page about the repository, without the app? Generate a landing page or a website in step 2, skip steps 3 to 5 and publish: nothing on that path costs money.

Projects and pages

Create a project

Private repositories

Apposters reads a public repository like any visitor. For a private one, check first and connect GitHub if it cannot see it:

A private repository can only become a SaaS: its site is about the product and says nothing about the code. The other types answer 422 with "code": "private_repo".

Generate the site

POST /app/sites/{site_id}/generate -> 202 {"job_id": "..."}. The AI writes the pages from the repository's README and metadata, in the project's design. Three project types:

# SaaS: a product site about what the app does; its buttons open the app at /app/
{"kind": "template", "mode": "saas", "pages": ["about", "faq", "auth"], "community": false}

# Website: a landing page about the repository plus the pages you list
{"kind": "template", "mode": "website", "pages": ["about", "faq"]}

# Landing page: one page about the repository
{"kind": "template", "mode": "landing"}

pages is any of about, faq and auth (the sign-in page); the landing page is always made. "community": true adds a community forum for the people who register, linked from the menu. A SaaS is for running the app with Embed App; a landing page and a website are free to publish and can become a SaaS later.

Your own wishes: add "instructions": "...", up to 2000 characters, with what the pages should say beyond the repository, in your words - for example "Add a pricing section. On the FAQ page, answer whether it is free." The landing page, About and FAQ each take the part meant for them, and a wish that names no page goes on the landing page; the sign-in page ignores it. It is not saved with the project: send it again with any later generation that should follow it. A longer text answers 422 with "code": "instructions_too_long".

Wait for it

Read and change

Generate again: {"kind": "template", "regenerate": true} to the same generate call remakes the landing page and keeps the project type. To change the type, send the whole new plan with "regenerate": true: the landing page and every page of the plan are made again, and the old versions stay in the history. Add instructions to change something specific: {"kind": "about", "instructions": "..."} remakes only the About page that way. Changes go live when you publish again.

Running the app (Embed App)

Embed App builds your repository and runs it at /app/ on the project's own address, for example https://your-app.apposters.com/app/, or on your domain. The /app prefix is taken off before a request reaches the app, so an app that serves at / works as it is; one that routes in the browser needs its base path set to /app. Setting up, deploying, fixing, starting and restarting answer 402 until Embed App is paid for; reading, stopping, logs, metrics, settings and removing always work.

Check the repository first

GET /app/sites/{site_id}/repo-check?ref=HEAD&path=Dockerfile reads the repository without building it:

• dockerfile: true - there is a Dockerfile at that path. analysis.expose is the port to use; analysis.kind: "cli" or a not-a-server warning means it is a command-line tool, not a web app.
• dockerfile_found - the repository builds another file; pass its path as dockerfile_path.
• auto.found: true - Apposters can build it without a Dockerfile, the way its framework builds (Vite, Next.js, React, Vue, Angular, Astro, Express, Django, FastAPI, Flask, Streamlit, Go, a plain index.html and more): auto.name, auto.build, auto.start or auto.output, and auto.dockerfile is the Dockerfile it would write.
• setup.vars - the settings the app asks for, with name, required, description and input: auto ones come with a ready value, generate ones take any long random string, secret ones are yours to fill in.

Set it up and deploy

While it runs

Sign-in in front of the app: with a sign-in page published and the app deployed, PATCH /app/sites/{site_id} with {"auth_redirect_to_app": true} sends people who sign in on your site straight to the app, and lets only them use it.

Publishing

Publishing also writes the site's sitemap.xml and robots.txt, link-preview tags and the analytics tag, and lets search engines know about the pages.

Payments

Generating, publishing, the address on apposters.com and a hosted app's free tier - 512 MB of memory, one CPU and 3 GB of disk for its image and data together - cost nothing. These do:

The prices are on the Pricing page and in GET /billing/prices (no token needed). You always pay on Stripe's page in a browser; the API starts the payment and checks it, and never takes card details.

More memory or disk for an app, either together with Embed App or on its own once the app is set up. The number is the size the app should end up with, not an addition, and you pay only for the units you do not have yet:

POST /billing/embed/checkout    {"site_id": "...", "resources": {"memory": 2, "disk": 1}}
POST /billing/memory/checkout   {"site_id": "...", "units": 4}
POST /billing/disk/checkout     {"site_id": "...", "units": 2}

Confirm them the same way. More memory takes effect on the next deploy, more disk at once. Signs an app needs them: a failed deploy whose last_run.diagnosis.limit.kind is memory, or a deploy answered 409 with "code": "storage_full". Lowering or cancelling what you pay for is done in the browser, under Manage payments in Account.

Custom domain

Connecting a domain and checking its DNS are paid for with the domain product (see Payments).

Tokens

Limits