API
Publish a page from your terminal
Two HTTP requests put an HTML file or a .zip of a folder at a live URL. They work in a script, a CI job, and a coding agent such as Claude Code or Codex. Every plan has it, Free included.
# 1. Create the page (a draft with a private preview link)
curl -X POST https://api.convika.com/v1/api/pages \
-H "Authorization: Bearer $CONVIKA_API_KEY" \
-F "file=@index.html" \
-F "name=Launch page"
# 2. Make it live
curl -X POST https://api.convika.com/v1/api/pages/PAGE_ID/publish \
-H "Authorization: Bearer $CONVIKA_API_KEY"No credit card.
Publish in 3 steps
- Sign up, then open Settings and API keys in the dashboard and create a key. Copy it right away: it's shown once.
- Put the key in your shell or your CI's secrets as CONVIKA_API_KEY.
- Send the page with curl: an HTML file, or a .zip of a folder. The first request returns the page's id and a private preview link. The second makes it live and returns its URL.
Every answer is JSON: the page's address is in url and its id in id.
REST API
Call these endpoints from curl, a GitHub Actions step, or any HTTP client.
Base URL
https://api.convika.com/v1/apiAuthentication
Authorization: Bearer cvk_...Send your key in the Authorization header of every request. A key works in the workspace it was made in and acts as the member who made it.
| Endpoint | What it does |
|---|---|
| POST /pages | Creates a page from HTML or a .zip. Returns its id, its URL, its state (draft), and a private preview link. |
| PUT /pages/{id} | Saves a new version of the page. It goes live at the same URL when you publish. |
| POST /pages/{id}/publish | Makes the newest version live and returns the page with its live URL. |
| POST /pages/{id}/unpublish | Takes the page offline and keeps it as a draft, ready to publish again. |
| GET /pages | Lists the workspace's pages, newest change first. Page through them with limit and offset. |
| GET /pages/{id} | Returns one page: id, name, URL, state, and version numbers. |
Sending a page
Send multipart/form-data with file (an .html file, or a .zip of index.html and the files it uses) and an optional name. Or send JSON: {"html": "…", "name": "…"}. A .zip becomes one page with its CSS, JavaScript, images, and fonts inside, the same way the upload box on convika.com reads a folder.
Create a page and publish it
# 1. Create the page (a draft with a private preview link)
curl -X POST https://api.convika.com/v1/api/pages \
-H "Authorization: Bearer $CONVIKA_API_KEY" \
-F "file=@index.html" \
-F "name=Launch page"
# 2. Make it live
curl -X POST https://api.convika.com/v1/api/pages/PAGE_ID/publish \
-H "Authorization: Bearer $CONVIKA_API_KEY"Update a live page at the same URL
curl -X PUT https://api.convika.com/v1/api/pages/PAGE_ID \
-H "Authorization: Bearer $CONVIKA_API_KEY" \
-F "file=@dist.zip"
curl -X POST https://api.convika.com/v1/api/pages/PAGE_ID/publish \
-H "Authorization: Bearer $CONVIKA_API_KEY"What comes back
{
"id": "PAGE_ID",
"name": "Launch page",
"url": "https://your-name.convika.page",
"state": "live",
"liveVersion": 2,
"latestVersion": 2,
"createdAt": "2026-11-22T09:00:00.000Z",
"updatedAt": "2026-11-22T09:05:00.000Z",
"version": 2
}For coding agents
Claude Code, Codex, Cursor, and other agents that work in a terminal publish with curl. Paste this into your agent's instructions, or let it read this page.
- Check that CONVIKA_API_KEY is set. If it isn't, ask the user to create a key at https://app.convika.com/settings#api-keys and export it.
- Build the page if it has a build step and zip the build folder. Send it as the file field of POST /pages, then show the user the previewUrl in the answer.
- When the user says to go live, send POST /pages/{id}/publish with the id from the first answer. The url in its answer is the live URL.
- For later changes, send PUT /pages/{id} and publish again, so the URL stays the same.
Limits
- The API follows your plan exactly as the dashboard does: live pages, pages kept, new pages a day, and publishes a day are your plan's.
- A page is up to 4 MB, with everything a .zip puts inside it. A request is up to 10 MB.
- Each key sends up to 60 requests a minute. Past that the API answers 429 with a Retry-After header that says when to send the next one.
Errors
Every error is JSON with a stable error code and a message that says what to do next: {"error": "…", "message": "…"}.
| Code | Status | What to do |
|---|---|---|
| missing_api_key | 401 | Send Authorization: Bearer with your key. |
| invalid_api_key | 401 | Create a new key in Settings, API keys, and use that one. |
| cookie_not_accepted | 401 | Send the request without cookies, with your API key only: from a script or a terminal, not a browser. |
| rate_limited | 429 | Wait the seconds in Retry-After, then send the request again. |
| not_found | 404 | Check the page id with GET /pages. |
| not_html | 400 | Send the whole HTML, from <html> to </html>. |
| html_too_large | 413 | Link to large images by URL so the page fits in 4 MB. |
| bundle_no_html | 422 | Put the page's index.html in the .zip. |
| bundle_unbuilt | 422 | Build the project, then send its dist, build, or out folder. |
| live_page_limit | 403 | Unpublish a live page, or move to a plan with more live pages. The message lists the pages that are live. |
| site_limit_reached | 403 | Your plan's pages are all in use. Update one with PUT, or move to a plan that keeps more. |
| publish_daily_limit | 429 | Publish again after 00:00 UTC, or move to a plan with more publishes a day. |
Your keys
- A key is shown once, when you create it. Convika stores only a hash of it.
- Name each key for where it runs (GitHub Actions, your laptop), and see when each was last used in Settings.
- Revoke a key in Settings and it stops working at once. The pages it published stay live.
- A key opens the publishing API only. Your billing, your members, and your key list stay behind your dashboard login.
Questions
Is the Convika API free?
Yes. API keys and the REST API are on every plan, Free included. Your plan's page limits are the same from the API as from the dashboard.
Can I update a page without changing its URL?
Yes. Send PUT /pages/{id} and then POST /pages/{id}/publish. The new version goes live at the same URL, and the earlier versions stay in the page's history.
Can I publish from GitHub Actions or another CI?
Yes. Save your key as a secret named CONVIKA_API_KEY, then add a step after your build that sends the page with curl: PUT /pages/{id} with the file, then POST /pages/{id}/publish. Any CI that runs curl works.
Does a folder with CSS, JavaScript, and images work?
Yes. Send the folder as a .zip. Convika finds index.html and puts the CSS, JavaScript, images, and fonts it uses inside the page, up to 4 MB in all.
What does a page get after it's published?
A live URL on Cloudflare's network, a form inbox, visitor stats (where visitors came from and what they clicked), version history with rollback, and your own domain when you connect one.
Publish your first page from the terminal
Create a key, send your page, and share the URL.
Get my API key free