API and MCP

Quick start

1. 1

   Create a project in the panel and get a key on the API keys tab. The tqk_… key is shown only once.

2. 2

   Connect Tuqo to your AI as an MCP connector, or work directly with REST.

3. 3

   Create a site and upload a source archive: it builds automatically and goes live on <subdomain>.tuqo.ru.

Project API key

Every request is authorized with the header Authorization: Bearer tqk_…. A key belongs to one project, and every operation is scoped to that project. We store only an argon2 hash of the key and a public prefix for display; the key itself cannot be recovered. If you lose it, issue a new one.

Access levels

• readonly read only: lists and statuses
• editor create sites, deploy, attach domains, roll back; cannot delete sites or domains
• full full access, including deleting sites and domains and changing a site's address

MCP for AI agents

Tuqo runs an MCP server (JSON-RPC 2.0) at https://mcp.tuqo.ru/mcp. Add it as a connector in your AI model, and the agent manages deploys from plain-language requests. Over MCP everything is in English: tool descriptions, errors and publish recommendations. Build logs follow the language of the site owner's account.

Connecting

URL and authorization header (for MCP clients with HTTP transport and custom headers):

{
  "mcpServers": {
    "tuqo": {
      "url": "https://mcp.tuqo.ru/mcp",
      "headers": { "Authorization": "Bearer tqk_xxx_yyy" }
    }
  }
}

Web chats such as claude.ai and ChatGPT connect over OAuth with just the URL, no key needed. Setup for each client is on the Connect an AI page.

Tools

A request by hand (JSON-RPC tools/call):

curl -X POST https://mcp.tuqo.ru/mcp \
  -H "Authorization: Bearer tqk_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "create_site",
      "arguments": { "name": "Landing page", "subdomain": "myproject" }
    }
  }'

REST API

Base URL: https://api.tuqo.ru. Requests and responses are JSON, except for raw uploads: a deploy archive (binary tar.gz or zip), a blob, a lead magnet file or a logo.

The machine-readable spec is OpenAPI 3.1 (tuqo.dev/openapi.json): use it for client generators, ChatGPT Actions and schema checks. The MCP server card with the full list of tools is at mcp.tuqo.ru/.well-known/mcp.json.

The /git rows connect a repository for auto-deploy on push; providers and webhook setup are on the Git CD page.

Errors

An error comes back with an HTTP status and a JSON body {"message": "…"}. The message text follows the request language: send Accept-Language: en for English, otherwise it is Russian. Branch on the status code, not on the text.

• 400 invalid data: the body or a parameter failed validation
• 401 the key is missing, invalid, revoked or expired
• 402 the feature or limit needs a paid plan or add-on
• 403 the key lacks the required scope
• 404 not found, or it belongs to another project (the two look the same)
• 409 state conflict: subdomain taken, storage quota, a deploy that cannot be activated…
• 429 rate limit: deploys per day, build minutes, DNS checks

Deploys: formats and statuses

Upload a .tar.gz or .zip archive (up to 50 MB). It can contain:

• npm project sources: Tuqo builds them on Node 20 with npm ci (or npm install when there is no package-lock.json) and npm run build, then takes the output from dist/, build/ or out/.
• A ready static site: put the files (with index.html) at the root of the archive. This is how you publish the output of any stack or language built locally.

Supported stacks

Built automatically out of the box (output in dist/build/out):

Static output only: SSR and server functions do not run. The output folder is looked up in this order: dist, build, out, .vitepress/dist, .output/public, _site, public, site, storybook-static, so Gatsby and Eleventy build automatically too. For stacks where static output needs a separate command (Nuxt → nuxi generate, Storybook), nested output (Angular) and non-Node tools (Hugo, Jekyll, MkDocs), build locally and upload the ready static files (the “ready static site” option above). That works for any stack.

Deploy over REST (the body is the binary archive):

curl -X POST https://api.tuqo.ru/api/v1/sites/$SITE/deploys \
  -H "Authorization: Bearer tqk_xxx_yyy" \
  -H "Content-Type: application/gzip" \
  --data-binary @dist.tar.gz

Over MCP, the same archive goes as base64 in the source_base64 argument of deploy_site. When the build succeeds, the deploy goes live automatically.

Deploy statuses

• queued the deploy is waiting in the build queue
• building the build is running (npm ci or npm install, then npm run build)
• ready built, but not live yet
• active live: served on the site's subdomain
• failed the build failed (details in get_logs / the error field)
• superseded replaced by a newer live deploy

Large sites: manifest deploy

A single request is capped by body size (an archive or a file set: up to 50 MB). For heavy sites (lots of photos or video) and efficient repeat deploys, use a manifest deploy: files are uploaded one by one, addressed by content (sha256), with no giant request, and files that match between deploys are not uploaded again (editing text leaves images alone).

Easiest: the CLI

It does every step for you and reads bytes from disk (for agents, no tokens spent on base64). Pass the key in the TUQO_API_KEY environment variable (it stays out of your shell history); --wait waits for the deploy to go live and prints the live URL:

TUQO_API_KEY=tqk_xxx_yyy npx @tuqo/cli deploy ./dist --site $SITE --wait

Several sites from one repository (locales, brands): a tuqo.json file at the root ({"sites": {"site/com": "<site_id>", "site/ru": "<site_id>"}}) and a single npx @tuqo/cli deploy. Never store the API key in tuqo.json: the CLI refuses to run if it finds one. More on the CLI page.

Or directly: 3 REST steps

1. Manifest → missing blobs. POST /api/v1/sites/{id}/deploys/check with the body {"files":[{"path":"index.html","sha256":"…"},…]} → {"missing":["sha256",…]}.
2. Upload the blobs. For each missing one: PUT /api/v1/blobs/{sha256}, the body is the raw file bytes (the sha256 of the body must match the path). Up to 50 MB per file.
3. Assemble the deploy. POST /api/v1/sites/{id}/deploys/manifest with the same manifest (path+sha256) → the server assembles the site from the blobs and publishes it. Up to 2000 files; the total size is limited only by your plan's storage quota.

index.html must be at the root. Blobs are deduplicated within the project. The /__tuqo/ path is reserved by the platform (login screens, file delivery): files under it are filtered out on deploy, as are service files like .git/.env. An agent in a browser chat (no file system) deploys heavy media sites exactly this way, through the CLI on the user's machine; a plain web chat suits light sites and text edits.

Edit a live site without re-uploading media

To change text without sending the images again (important for a web agent with no files):

1. GET /api/v1/sites/{id}/manifest (or MCP get_manifest) → an array of {path, sha256} for the current files.
2. Show first, publish later. Pass "activate": false in the deploy body and the build does not replace the live site; POST /api/v1/deploys/{id}/preview (MCP: get_preview_url) gives the link, and /activate publishes it. Details: build preview.
3. Deploy with deploy_files//deploy-files: pass unchanged files as a reference {"path":…,"sha256":…} (no content, so the bytes are not sent) and changed files with ordinary content.

A sha256 reference works only for a blob of your own project. deploy_files takes up to 2000 files; inline content counts toward the 50 MB request body, while a file passed as a blob reference can be up to 50 MB on its own.

Serving: routes, 404.html and cache

How the edge resolves a request for /P (a path without an extension) when there is no file P, in order:

1. Clean URL: /about → serves about.html.
2. Directory index: if about/index.html exists → 301 to /about/ (so relative links work), then the index is served. A path with a slash (/about/) serves about/index.html right away.
3. Custom 404: put 404.html at the root of the deploy; on a miss it is served with status 404 (an honest code for SEO).
4. SPA fallback: with no 404.html, index.html is served with status 200 (client-side routing for React/Vue).

A request for a missing file with an extension (/app.js) returns an honest 404: assets are never replaced with index.html.

Cache headers

• *.html: no-cache, so updates show up immediately.
• Files with a content hash in the name (app.4f3a2b1c.js, Vite/Astro output, the _astro/ folder): max-age=31536000, immutable, cached for a year and invalidated by a new file name.
• Other static files (hero.jpg with a stable name): max-age=300, so an update under the same name arrives within ~5 minutes. Headers cannot be set per file: for immutable caching, put a hash in the name (bundlers do this for you).

Forms (submissions)

Any site in the project can take submissions without a backend of its own. Forms work on every plan, including Free (10 submissions a month); higher plans have a bigger monthly quota, and on any plan you can buy a submission pack. The form posts to a public endpoint; submissions collect in the project panel (the Forms tab), show up in the notification bell and, if you set it up, arrive by email.

Endpoint

POST https://api.tuqo.ru/f/{site_id} accepts application/json, application/x-www-form-urlencoded and multipart/form-data, so a plain HTML form submit and new FormData() work just like JSON. Any other Content-Type → 415 (an explicit error, not a silent 200). No authorization is needed: the endpoint is public and bound to the site's domain.

Getting the endpoint over MCP: the responses of create_site, get_site and list_sites contain a form_endpoint field, a ready URL to embed. It is deterministic: https://api.tuqo.ru/f/<site_id>.

Embedding a form

The panel always has a ready snippet with the anti-spam fields (the Forms tab). The minimal version:

<form onsubmit="event.preventDefault();
  const f=event.target, d=Object.fromEntries(new FormData(f));
  d._submit_time=f.dataset.t; d._request_id=crypto.randomUUID();
  fetch('https://api.tuqo.ru/f/SITE_ID', {
    method:'POST', headers:{'Content-Type':'application/json'},
    body: JSON.stringify(d)
  }).then(()=>{ f.reset(); alert('Message sent'); });" data-t="">
  <input name="name" placeholder="Name" required>
  <input name="email" type="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message"></textarea>
  <input name="_hp_xxx" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
  <script>document.currentScript.closest('form').dataset.t=Date.now()</script>
</form>

Service fields and anti-spam

• _submit_time: when the form was shown (ms, Date.now()). Sending faster than ~3 seconds after that counts as spam. There is no upper bound: the tab can stay open as long as you like.
• _request_id: a request UUID; resending with the same id does not duplicate the submission (idempotency). Optional.
• honeypot: a hidden field named like _hp_xxx (the exact name is in the panel snippet or in get_forms_overview). You can leave it out: without the field a submission goes through normally; it blocks only when filled in (by a bot). If you add it, keep it empty.
• Origin: the request must come from the site's domain (its *.tuqo.ru address or a verified custom domain), otherwise 403. So the form works on the site itself, not from an arbitrary origin.
• Limits: body ≤ 50 KB, up to 30 fields, at most 30 submissions/min per site and 10/min per IP.

Responses

Errors come as {"ok": false, "reason": "…"}. The reason codes are stable English identifiers; the optional hint text is in the site's language.

• 200 submission accepted (or silently dropped by the honeypot or as a repeat: the response looks the same)
• 400 the body could not be parsed with a valid Content-Type (reason: invalid_body), or it has more than 30 fields (reason: too_many_fields)
• 402 intake paused: the limit is used up and the cap on locked submissions is reached (reason: quota_exhausted), or the project is suspended (reason: suspended)
• 403 the request did not come from the site's domain (origin not allowed; reason: origin_required / origin_not_allowed)
• 404 no such site, or it is in the trash (reason: site_not_found)
• 415 unsupported Content-Type: send JSON, urlencoded or multipart (reason: unsupported_content_type)
• 429 rate limit exceeded (reason: rate_limited)

Submissions above the plan's monthly limit are not lost: the content is saved but locked, and it unlocks when you buy a submission pack or upgrade the plan (a new month does not unlock it). Limits by plan are on the pricing page, an overview is on the Forms page.

Reading submissions (for AI agents and automations)

You can read submissions from code, not just receive them: for reports, follow-ups and dashboards. The scope is the project of the API key; the readonly level is enough.

• MCP: get_forms_overview (quotas, balance, sites, counters) and get_form_submissions (site_id?, status? = verified|spam|archive, limit?, offset?).
• REST: GET /api/v1/forms/overview and GET /api/v1/forms/submissions?site=&status=&limit=&offset=.
• Auto-reply (an email to the sender, from the Start plan): MCP get_autoreply / set_autoreply, REST GET|PUT /api/v1/sites/{id}/autoreply. The text supports markup (**bold**, lists, quotes, links) and {{field_name}} placeholders from the submission. The lead magnet file and the delivery page are set up in the panel. More: Auto-reply and lead magnet.

Gated access

You can close a site to outsiders: with a password for the whole site, or with sign-in by an email code for addresses on your list. The check runs in the serving layer and covers every file, not only HTML. The full walkthrough is on the Gated access page; here is what an agent or a script needs.

This is a paid feature: the password needs the Start plan, the email code needs Pro (subscribers only and member sign-up also need Pro), or the matching per-site add-on. Without it, the enabling calls return 402 with the plan that is needed. Removing the lock is free on any plan: we never gate loosening your own restrictions.

Good to know

• — The password is returned in the response when you set it; to see it later, call GET /api/v1/sites/{id}/access/password (the response is sent with no-store).
• — Changing the password or removing the lock signs out everyone who is already in.
• — The address list holds up to 1000 addresses per site; removing an address ends its access immediately.
• — Extending access counts from the current end date, not from today.
• — The login screen logo can be any size up to 1 MB; we shrink it on our side.

The full list of endpoints is in the REST table above (the /access rows); the MCP tools are in the Gated access group on the MCP page.

Custom domains

Attaching a domain takes two steps:

1. 1

   set_custom_domain (or POST /api/v1/sites/{id}/domains) returns a token. In the domain's DNS, add an A record pointing to the platform IP and a TXT record _tuqo-verify with that token.

2. 2

   verify_domain (or POST /api/v1/domains/{id}/verify) once DNS has propagated. Ownership is confirmed by the TXT record; the response also carries A record diagnostics (a_record: ok / found / expected / message). If the A record does not point to the platform, the site will not open on the domain. Calling it again on an already verified domain re-checks the A record. The HTTPS certificate is issued automatically.

DNS does not update instantly: it takes from a few minutes to a few hours. The exact A and TXT values are always shown in the panel on the site's Domains tab.