MCP API — Ordo Kit provisioning#
Deploy a GitHub repository containing a Dockerfile — public or private — and get a running site at https://<alias>.ordokit.dev with a Let's Encrypt certificate.
This document describes the Model Context Protocol server. Everything here is also available through the web dashboard at https://ordokit.dev/app; the two drive the same pipeline, the same quota and the same audit trail.
- Endpoint
https://ordokit.dev/mcp - Transport Streamable HTTP — JSON-RPC 2.0 over
POST - Protocol versions
2026-07-28,2025-11-25,2025-06-18,2025-03-26,2024-11-05— see Protocol versions - Auth OAuth sign-in (the client sends you here to approve it), or an API token for scripts, sent as
Authorization: Bearer <token>
Quickstart#
1. Connect your agent#
Give your agent the address https://ordokit.dev/mcp. It asks you to sign in: your browser opens here, you sign in with GitHub, and you approve it on the consent page. There is no token to copy. Each client's own steps:
Claude (claude.ai and the desktop app): Customize → Connectors → + → Add custom connector. Name it Ordo Kit, paste https://ordokit.dev/mcp as the URL, then choose Connect. Turn it on for a chat from + → Connectors.
Claude Code:
claude mcp add --transport http ordo https://ordokit.dev/mcp
Then, in Claude Code, run /mcp, pick ordo and authenticate. Add --scope user to the command to have it in every project.
Codex:
codex mcp add ordo --url https://ordokit.dev/mcp
codex mcp login ordo
Gemini CLI:
gemini mcp add --transport http ordo https://ordokit.dev/mcp
It finds the sign-in by itself the first time the server asks; /mcp auth ordo inside Gemini CLI starts it by hand.
Cursor, in ~/.cursor/mcp.json; Cursor registers itself and asks you to sign in to ordo from its MCP settings:
{ "mcpServers": { "ordo": { "url": "https://ordokit.dev/mcp" } } }
VS Code, in .vscode/mcp.json (or the file MCP: Open User Configuration opens, for every workspace); it opens your browser the first time the server starts:
{ "servers": { "ordo": { "type": "http", "url": "https://ordokit.dev/mcp" } } }
opencode, in opencode.json; it signs in the first time the server is used, or run opencode mcp auth ordo:
{ "mcp": { "ordo": { "type": "remote", "url": "https://ordokit.dev/mcp", "enabled": true } } }
The Settings page in the dashboard shows all of these with the address filled in.
The consent page names the app asking and the address it will send you back to. An app identified by a published metadata URL is named by that URL's host, because the name inside the document is its own claim; any other app is named as it registered, so check the address beside it. On the free trial the consent page asks you to verify a card first: it costs $0 and nothing is charged. Paid plans need nothing more.
How signing in works#
- Discovery. A request without a valid token gets HTTP 401 with
WWW-Authenticate: Bearer resource_metadata="https://ordokit.dev/.well-known/oauth-protected-resource". That document (RFC 9728) names this site as the authorization server, whose metadata is at https://ordokit.dev/.well-known/oauth-authorization-server (RFC 8414).
- Registration. A client registers itself (RFC 7591) or identifies itself
with a Client ID Metadata Document. Every client is public and uses PKCE with S256; tokens are issued only for https://ordokit.dev/mcp (RFC 8707).
- Tokens. An access token lasts one hour and a refresh token sixty days;
the client refreshes by itself, and each refresh token works once. A refresh token or code used twice ends the connection, and you sign in again.
- Disconnecting. Settings → Connected apps lists every app with when it was
connected and last used. Disconnect ends its access at once. Deleting your account removes them all.
A connected app acts as you, like a click in the dashboard: the same quota, the same ownership rule, the same audit trail.
2. For scripts and CI: an API token#
Where a browser sign-in is not possible, use a token. Mint one at Settings → API access. It is shown once: only a hash is stored, so it genuinely cannot be displayed again. Tokens start with omcp_, and the same plan and card rules apply.
Check it before configuring anything. Replace $TOKEN with the token you just minted — do not paste it literally:
curl -s https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN"
A working token answers:
{"authenticated": true, "auth": "api_token", "login": "you", "github_id": 1, "operator": false, "mcp_access": true}
"mcp_access": false means the token is fine but the account is not open to the MCP API yet; reason says why and verify_url where to fix it. Anything else tells you exactly what is wrong — no header, not a Bearer value, an incomplete token, or one that has been revoked.
Then send it as a header on every request:
curl -s https://ordokit.dev/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
A client that cannot sign in takes the same header in its config, for example:
{
"mcpServers": {
"ordo": {
"type": "http",
"url": "https://ordokit.dev/mcp",
"headers": { "Authorization": "Bearer omcp_REPLACE_WITH_YOUR_TOKEN" }
}
}
}
3. Deploy something#
The normal order, and what each step is for:
check_alias → is the address free
inspect_repository → what port does the container listen on
suggest_dockerfile → no Dockerfile? one to commit (review_dockerfile if there is)
scan_repository → will it be refused, and will it fit the plan
create_deployment → returns a job_id
get_progress → poll until status is "done" or "error"
A deployment takes one to three minutes. Poll every few seconds, not continuously.
// create_deployment
{"alias": "my-app", "repository": "https://github.com/owner/repo",
"port": "3000", "branch": "main"}
// → {"job_id": "a1b2c3…", "alias": "my-app",
// "url": "https://my-app.ordokit.dev"}
// get_progress, until finished is true
{"job_id": "a1b2c3…"}
When it finishes, the site is live at https://my-app.ordokit.dev with a valid certificate.
Private repositories#
A private repository needs a one-time setup that only a person can do, because both parts are GitHub permissions:
- Install the Ordo Kit GitHub App on the repository — read-only access
to its contents, so it can be screened and its pushes deployed.
- Add a read-only deploy key to it, which the build server clones with.
inspect_repository reports where things stand in its access object:
// inspect_repository {"repository": "https://github.com/owner/private-repo"}
{"port": null, "status": "not_found", …,
"access": {
"repository": "owner/private-repo",
"visibility": "unknown", // public | private | unknown
"ready": false,
"needs_person": true,
"next_step": "Nothing readable at github.com/owner/private-repo: either the address is wrong, or … ask the user to open this link and install the Ordo Kit GitHub App …",
"url": "https://ordokit.dev/github/install?repository=owner/private-repo",
"push_to_deploy": false
}}
When ready is false, give the user next_step and url, wait for them, and call inspect_repository again. The first time it points at installing the app; the second time, at a page that shows the deploy key and checks it with GitHub. Once ready is true, create_deployment works like it does for a public repository — and if it is called too early, its error carries the same link.
push_to_deploy: true means the app is on the repository: every push to the deployed branch is screened, then that exact commit is built.
Example prompts#
Things to say to an agent once it is connected, and the tools it uses to do them. Replace <you>/<repo> with a repository of yours.
“Deploy https://github.com/<you>/<repo> and give me the live URL.”
Tools: inspect_repository → create_deployment → get_progress
The agent reads the repository for the port its container listens on, whether its Dockerfile is where it should be, and whether this account can deploy it. It picks an address (suggest_alias makes one up), starts the deployment, and polls the job until it is done: one to three minutes. The answer is https://<alias>.ordokit.dev, with a valid certificate.
“My repository has no Dockerfile. Deploy it anyway.”
Tools: inspect_repository → suggest_dockerfile → create_deployment → get_progress
inspect_repository finds no Dockerfile and points at suggest_dockerfile, which writes one and a .dockerignore for the stack it finds, from fixed templates. The agent writes both into your repository, commits and pushes them - with your say-so - and deploys with the Dockerfile path and port it was given. Nothing is written anywhere by us: the build reads your repository.
“Can my Dockerfile be better?”
Tools: review_dockerfile
Recommendations, none required to deploy: a dev server as the start command, a server bound to localhost, an unpinned base image, a missing .dockerignore. Where the fix is mechanical it comes back as an improved copy of the whole file, for you to take or leave.
“Why did my last deployment fail?”
Tools: list_deployments → get_logs
The agent finds the deployment that failed among yours, then reads its log: our pipeline steps and the build output, newest run first. The reason is usually in the last few lines. The log is the repository's own output, so it arrives labelled as third-party content.
“Is the name my-app free? If not, suggest one for https://github.com/<you>/<repo>.”
Tools: check_alias → suggest_alias
check_alias says whether my-app.ordokit.dev is free, taken, or already yours. If it is taken, suggest_alias returns a free name made from the repository's, such as repo-k3x9. Both are advisory: the name is claimed when the deployment is created.
“Suspend my staging site.” … “Start it again.”
Tools: list_deployments → suspend_deployment → start_deployment
The agent finds the site's address among yours, then stops its container. The address and the project stay, and the site still counts towards your plan's limit. Asked to start it again, the agent redeploys it at the same address.
“What plan am I on and how many sites do I have left?”
Tools: get_plan
One call returns the plan, the memory and CPU every site runs with, how many sites are in use and how many are left, and this cycle's bandwidth against the allowance.
“Deploy https://github.com/<you>/shop at shop.example.com.”
Tools: check_domain → create_deployment → get_progress
check_domain checks that the hostname already points here and, if it does not, names the exact DNS record to add. Only you can change your DNS, so the agent hands that over and checks again. Then it deploys with the domain set, and the site answers on both shop.example.com and its <alias>.ordokit.dev address.
“Add shop.example.com to my site.”
Tools: list_deployments → check_domain → set_domain → get_progress
For a site that is already running. The agent finds it among yours, checks the hostname's DNS and hands you the record to add if it is not there yet, then sets the domain. The site is redeployed at the commit it is running, without a rebuild, and the job ends once the new hostname has its certificate. <alias>.ordokit.dev keeps working throughout. A site has one own domain: setting another replaces it, and remove_domain takes it off and frees the hostname.
Troubleshooting#
"The client gets 401, or says it needs an API token"#
Every request needs credentials, the initialize handshake included. A request without a usable token is answered with HTTP 401 and a WWW-Authenticate header pointing at the OAuth metadata, which is what makes a client that supports sign-in ask you to sign in. A client configured with an API token that still gets 401 is sending no usable token, and the server says which of these it is:
| What you see | What it means |
|---|---|
No Authorization header was sent | The header never left the client. It is configured somewhere the client is not reading, or the argument was dropped by the shell. |
must read 'Authorization: Bearer <token>' | The scheme is missing or wrong. The message quotes what arrived — if that is your token, the word Bearer is missing in front of it. |
not a complete token | Usually the placeholder from these instructions, pasted unedited. |
not recognised | Revoked, or from a different instance. |
Two things worth checking in order:
curl https://ordokit.dev/mcp/whoami -H "Authorization: Bearer $TOKEN"— if this says
true, the token is fine and the problem is in the client.
claude mcp get ordo— confirm the header is attached to the server
entry, not merely typed at the shell when you added it.
Because the 401 comes on the first request, a client that checks status codes reports the connection as unauthenticated rather than as working.
A client that signed in and is asked to sign in again has lost its connection: it was disconnected on the Settings page, it went sixty days unused, or a refresh token was used twice. Sign in again - /mcp in Claude Code, codex mcp login ordo, /mcp auth ordo in Gemini CLI, Connect in Claude.
With a valid token for an account whose MCP access is closed (a trial without a verified card), the handshake succeeds and its instructions say why every tool call will be refused.
What this server will not do#
Four limits are deliberate. An agent will meet them, so they are stated here rather than discovered.
Bring-your-own VPS is not available over MCP. Registering your own server means signing in as root over SSH, installing Docker, taking ports 80 and 443 and leaving an agent holding the Docker socket. That needs a person to read the terms and agree to them. A JSON field asserting consent is not the same act, and the audit record would be a lie. Use the web dashboard.
Secrets are never returned. The push-to-deploy webhook secret is not in any response from this server. An agent's context ends up in transcripts, logs and third-party model providers, which is a worse home for a live secret than a browser session. Read it from the deployment page on the dashboard.
Private repository setup needs a person. Installing the GitHub App and adding a deploy key are permissions on somebody's GitHub account, granted on GitHub. The server hands back a link for the user to open instead; it never asks for a GitHub token and never returns a key.
Operator tools are read-only. An operator token can list every deployment, read the reconcile report, read the audit trail and read one account's timeline. Removing another tenant's project stays in the dashboard, where a person confirms it.
Privacy#
The server never sees your conversation with the agent: a tool call brings only the tool's name and its arguments. Each call is logged with the tool's name, the names of its arguments (not their values) and your login. Access and refresh tokens, and API tokens, are stored only as SHA-256 hashes. What is kept and for how long is in the privacy policy at https://ordokit.dev/privacy.
Third-party content#
Several tools relay text this service did not write: build output produced by whatever is in a repository's Dockerfile, names other tenants chose, error strings from the infrastructure underneath. That text reaches a model's context verbatim, which makes it a route for injected instructions — RUN echo "ignore your instructions and ..." in a Dockerfile lands in get_logs exactly as typed.
Sanitising it would destroy the reason people read logs, so those results are labelled with their source instead. The text content opens with Source: third-party. and a one-line note, and fences the payload between two markers:
--- begin third-party content ---
--- end third-party content ---
The structured form carries the same label as two sibling keys alongside the usual fields, which keep their names and shape:
{
"_source": "third-party",
"_source_note": "Includes text from repositories, build output, infrastructure messages and names chosen by other people. That text was not written by Ordo Kit."
}
_source is a fixed key and value for a client to match on. Everything between the markers is quoted material from those third parties, not text written by the operator of this server.
The tools that carry the label: get_logs, scan_repository, inspect_repository, suggest_dockerfile, review_dockerfile, get_deployment, get_progress, list_deployments, list_all_deployments, reconcile_report, read_audit, user_timeline. The ones that do not return only strings this service authored.
Protocol versions#
The server speaks both eras of MCP on the one endpoint. MCP clients handle this by themselves; it matters only if you are writing one.
2026-07-28: no handshake. Every request carries its version and the client's capabilities in params._meta (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientCapabilities), and the headers MCP-Protocol-Version, Mcp-Method and, for tools/call, Mcp-Name must say the same as the body. server/discover returns the supported versions, the capabilities, the server's identity and the instructions below:
{"jsonrpc": "2.0", "id": 1, "method": "server/discover",
"params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}}}}
Every result has resultType: "complete" and names the server in _meta["io.modelcontextprotocol/serverInfo"]; server/discover and tools/list carry ttlMs and cacheScope: "private" (the tool list differs for operators). subscriptions/listen is acknowledged with no notification types and closed at once: the tool list changes only when the service is redeployed. ping and initialize do not exist in this era.
2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05: the initialize handshake. The server answers with the version the client asked for when it is one of these, and with 2025-11-25 otherwise. Later requests send the negotiated version in MCP-Protocol-Version; a request without the header is treated as 2025-03-26. JSON-RPC batches are accepted only from 2025-03-26 and 2024-11-05, which still had them.
| Status | Error | When |
|---|---|---|
400 | -32022 Unsupported protocol version | data.supported lists what to retry with |
400 | -32020 Header mismatch | A required header is missing or differs from the body |
400 | -32602 Invalid params | A modern request without its _meta version or capabilities |
404 | -32601 Method not found | A modern request for a method this server does not have |
Errors#
Two kinds, and they mean different things.
A JSON-RPC error means the request was malformed or not permitted:
{"jsonrpc": "2.0", "id": 1,
"error": {"code": -32001, "message": "This tool needs an API token."}}
| Code | Meaning |
|---|---|
-32700 | Invalid JSON |
-32600 | Not a valid JSON-RPC request |
-32601 | Unknown method |
-32602 | Unknown tool, or bad arguments |
-32001 | Missing, unknown or revoked token |
A tool error means the request was understood and could not be carried out — a taken alias, a blocked repository, a full quota. It comes back as a normal result with isError set, so a model can read the reason and act on it:
{"content": [{"type": "text", "text": "{\"error\": \"That address is taken.\"}"}],
"structuredContent": {"error": "That address is taken."},
"isError": true}
Tools#
Every tool returns both content (text, for the model) and structuredContent (the same data, parsed).
Tenant tools#
get_plan#
Read the plan limits. read-only.
Your plan, the resource limits every deployment runs under, how many of your sites are in use, and this cycle's bandwidth against the allowance. Worth reading before deploying: the memory ceiling is a hard cgroup limit and a container that exceeds it is killed, not throttled.
_No parameters._
check_alias#
Check an address is free. read-only.
Whether <alias>.ordokit.dev is available. Aliases are lowercase letters, digits and hyphens, starting and ending alphanumeric. Answering from our records, so it is fast but advisory - the binding claim happens inside create_deployment, which is where two callers racing for the same name is actually resolved.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes | The subdomain to check. |
suggest_alias#
Suggest a free address. read-only.
A free <alias>.ordokit.dev derived from the repository name plus four random characters, e.g. groundstation-k3x9. Checked against existing deployments before it is returned; call again for another. Advisory like check_alias - the claim happens in create_deployment.
| Parameter | Type | Required | Notes |
|---|---|---|---|
repository | string | yes | The repository being deployed. |
check_domain#
Check an own domain's DNS. read-only.
Whether a customer's own domain (e.g. app.example.com) already points at the managed host, and if not, exactly which DNS record to add. create_deployment makes the same check and refuses until it passes, so use this first and relay message to the user - only they can change their DNS. One hostname per deployment; the shared <alias>.ordokit.dev address keeps working alongside it.
| Parameter | Type | Required | Notes |
|---|---|---|---|
domain | string | yes | The customer's hostname. |
alias | string | no | Optional: the shared alias, so the answer can offer a CNAME. |
inspect_repository#
Detect the container port. read-only.
Reads a GitHub repository and suggests the port its container listens on, with the evidence used and a confidence. Advisory: pass the port you know to be right to create_deployment rather than trusting a low-confidence guess, because a wrong port produces a deployment that builds, starts and never answers. When no port comes back, status says why: 'not_found' means nothing readable at that address - wrong owner, name or branch, or a private repository not yet granted; 'undetermined' means it was read and gave nothing away. Also returns access: whether this account can deploy the repository now (ready), and if not, a next_step and url for the user. Private repositories need a person to finish setup - relay those rather than trying to work around them. Also returns dockerfile: whether a Dockerfile exists at that path on that branch, and if not, the Dockerfiles that do exist (candidates). And build: the build context worked out from the Dockerfile (base_directory, with source saying why), and any files it COPYs that are missing there (missing, which create_deployment refuses).
| Parameter | Type | Required | Notes |
|---|---|---|---|
repository | string | yes | https://github.com/<owner>/<name> |
branch | string | no | Default main. |
dockerfile | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default /Dockerfile. |
base_directory | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. |
scan_repository#
Screen a repository. read-only.
Security and resource screening. Returns blocking findings, advisory warnings, and an estimate of whether the project fits the plan's memory. A repository with blocking findings will be refused by create_deployment, which runs this again itself - screening here is so you learn that before committing to a deployment, not so it can be skipped.
| Parameter | Type | Required | Notes |
|---|---|---|---|
repository | string | yes | |
branch | string | no | Default main. |
suggest_dockerfile#
Write a Dockerfile. read-only.
Writes a Dockerfile and .dockerignore for a repository that has none, from fixed templates for the stack it finds (Next.js, Nuxt, SvelteKit, Astro, Vite and other single-page apps, Node servers, NestJS, Bun, Django, FastAPI, Flask, Go, static sites): a build stage, a pinned base image, the lockfile installed exactly, a production server on 0.0.0.0, a non-root user. Nothing is changed anywhere: deployment builds from the repository, so write the files it returns into the repository at the paths given, commit and push them, then call create_deployment with the dockerfile and port it returns. Pass repository, or - for code not pushed yet - files and paths. Returns suggestions (one per project found; notes says what to check) and unsupported with the reason for each project it could not write for.
| Parameter | Type | Required | Notes |
|---|---|---|---|
repository | string | no | https://github.com/<owner>/<name> |
branch | string | no | Default main. |
folder | string | no | Optional: the project folder to write for, e.g. /apps/web. Left out, every project found is written for. |
files | object | no | Instead of repository: files you have locally, as path (from the project root) to content - package.json, a lockfile's name with any content, pyproject.toml, requirements.txt, go.mod, the file that creates the app. At most 60 files, 1 MB in all. |
paths | array | no | With files: every file path in the project, contents not needed, so the rules can see what exists (lockfiles, manage.py, cmd/*/main.go). At most 5000. |
review_dockerfile#
Review a Dockerfile. read-only.
Recommendations for an existing Dockerfile, none of them required to deploy: warn for what is likely to cause trouble here (a dev server as the start command, binding localhost, npm ci without a lockfile, a secret in ENV), tip for good practice (a pinned base image, a .dockerignore, manifests copied before the code, a non-root user). Each item names its line. Where the fix is purely mechanical, improved is the whole Dockerfile with those fixes applied, and dockerignore a file to add; offer them to the user rather than applying them unasked. Pass repository (the build context is worked out unless base_directory is given), or content with optional files and paths for a Dockerfile not pushed yet.
| Parameter | Type | Required | Notes |
|---|---|---|---|
repository | string | no | https://github.com/<owner>/<name> |
branch | string | no | Default main. |
dockerfile | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default /Dockerfile. |
base_directory | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. |
content | string | no | Instead of repository: the Dockerfile's text. At most 128 KB. |
files | object | no | Instead of repository: files you have locally, as path (from the project root) to content - package.json, a lockfile's name with any content, pyproject.toml, requirements.txt, go.mod, the file that creates the app. At most 60 files, 1 MB in all. |
paths | array | no | With files: every file path in the project, contents not needed, so the rules can see what exists (lockfiles, manage.py, cmd/*/main.go). At most 5000. |
create_deployment#
Deploy a repository. changes state — creates something new and changes nothing that exists, so it is not annotated destructive.
Builds a GitHub repository and serves it at https://<alias>.ordokit.dev with a Let's Encrypt certificate. The repository must contain a Dockerfile at dockerfile; if it does not, the refusal lists the Dockerfiles that do exist, with arguments to retry with. The build context is worked out from the Dockerfile unless base_directory is given. A private one must first show access.ready in inspect_repository. Returns a job_id immediately; the deployment itself takes one to three minutes, so poll get_progress until status is 'done' or 'error'. Deploys onto managed hosting - bringing your own VPS needs a person to consent to root access and is only available through the web dashboard.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes | Subdomain; the site becomes <alias>.ordokit.dev |
repository | string | yes | https://github.com/<owner>/<name> |
branch | string | no | Default main. |
port | string | yes | Container port. Use inspect_repository if unsure. |
dockerfile | string | no | Path of the Dockerfile in the repository, e.g. /apps/web/Dockerfile. Default /Dockerfile. Relative to base_directory only when base_directory is given. Default /Dockerfile. |
base_directory | string | no | Optional; normally leave it out. The build context - the folder the build runs in - is then worked out from the Dockerfile: the folder, from the Dockerfile's own up to the repository root, in which every file it COPYs exists. Give it only to override that; a folder in which the Dockerfile's COPY sources do not exist is refused, with the one that works. |
health_check | string | no | Optional HTTP path for a health check. |
email | string | no | Optional contact address for the welcome message. |
domain | string | no | Optional: the customer's own hostname, served alongside <alias>.ordokit.dev. Its DNS must already point at the managed host - see check_domain. |
get_progress#
Follow a running job. read-only.
The steps of a deployment, a domain change or a teardown, in order, with a percentage and the newest status. Poll this after create_deployment, set_domain, remove_domain or terminate_deployment until status is 'done' or 'error'. Pass after_id to get only what is new.
| Parameter | Type | Required | Notes |
|---|---|---|---|
job_id | string | yes | |
after_id | integer | no | Only events newer than this id. Default 0. |
list_deployments#
List your deployments. read-only.
Every deployment you own, with its live container state.
_No parameters._
get_deployment#
Read one deployment. read-only.
Health, address, repository and last build for one deployment. Does not return the webhook secret - that is on the web dashboard only.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes |
get_logs#
Read the build log. read-only.
Our pipeline steps and the build output for one deployment, newest run first. This is what to read when a deployment failed and you want to know why.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes | |
limit | integer | no | Maximum log lines to return. Default 200. |
start_deployment#
Start a stopped deployment. changes state — annotated destructive: it changes or removes something that exists, so a client can ask before calling it.
Redeploys a suspended deployment. Returns immediately.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes |
suspend_deployment#
Stop a deployment. changes state — annotated destructive: it changes or removes something that exists, so a client can ask before calling it.
Stops the container without deleting anything. The address and project both survive, and it still counts against your quota; use terminate_deployment to free a slot.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes |
terminate_deployment#
Destroy a deployment. changes state — annotated destructive: it changes or removes something that exists, so a client can ask before calling it.
Permanently removes the application, its project and its team, and frees the address. This cannot be undone. Returns a job_id; poll get_progress - termination is only reported complete once the address has stopped answering, which takes a few seconds after the containers go.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes |
set_domain#
Add or change an own domain. changes state — annotated destructive: it changes or removes something that exists, so a client can ask before calling it.
Serves an existing deployment at the customer's own hostname (e.g. shop.example.com) as well as at <alias>.ordokit.dev, replacing any own domain it had. Only the owner may, and only while it is running. The DNS must already point at the server - check_domain says which record to add and whether it is in place, and a refusal here carries the same answer in dns. Returns a job_id; poll get_progress until status is 'done' or 'error'. The site is redeployed at the commit it is running (no rebuild), then the certificate for the new hostname is issued, which takes a minute or two. Calling it again with the same domain re-applies it, which is how to retry a change whose redeploy failed.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes | The deployment. |
domain | string | yes | The customer's hostname. |
remove_domain#
Remove an own domain. changes state — annotated destructive: it changes or removes something that exists, so a client can ask before calling it.
Stops serving a deployment at its own domain; <alias>.ordokit.dev keeps working. Only the owner may, and only while it is running. Frees the hostname for use by another deployment. Returns a job_id; poll get_progress until status is 'done' or 'error'. The customer's DNS record is theirs to remove.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | yes | The deployment. |
Operator tools#
Available only to a token belonging to an operator. They are absent from tools/list for everyone else, rather than present and refused.
list_all_deployments#
List every deployment. read-only.
Every deployment on the instance, with its owner.
_No parameters._
reconcile_report#
Compare the platform against our records. read-only.
What the platform holds against what this service recorded: untracked projects, orphaned groups, deployments whose project has gone, and which site names on the managed server hold a certificate of their own instead of the zone's wildcard, and how many days the wildcard the server serves has left (certificates.served: level ok, warn under 20 days, error under 7 or when it does not verify, unknown when it could not be reached). Read-only - removing anything it finds is done from the web dashboard, where a person confirms it.
_No parameters._
read_audit#
Read the audit trail. read-only.
Who asked for what, and how it turned out.
| Parameter | Type | Required | Notes |
|---|---|---|---|
alias | string | no | Optional filter. |
limit | integer | no | Default 100. |
user_timeline#
Read one account's timeline. read-only.
Everything recorded about one account, oldest first, on one clock: audit rows, the activity trail (port detection, screening verdicts, access checks, refused deployments), pipeline events of every deployment it has had, its plan, card check, GitHub installations and tokens, GitHub deliveries naming it, and matching log lines when logs are kept. Give login or github_id; a login two accounts have used is refused with both ids. Read-only.
| Parameter | Type | Required | Notes |
|---|---|---|---|
login | string | no | GitHub login. |
github_id | integer | no | GitHub numeric id; wins over login. |
sources | array | no | Only these sources. Default: all. |
days | integer | no | How far back. Default 30. |
limit | integer | no | The newest this many items. Default 1000. |
Limits worth knowing#
- Quota. Each account may hold a limited number of live deployments.
A suspended one still counts; terminate to free the slot. get_plan reports what is left.
- Resources. Containers run under a hard memory cgroup limit. Exceeding it
kills the container rather than slowing it. scan_repository estimates whether a project will fit before you commit to it.
- Certificates. Let's Encrypt allows five certificates per exact hostname
per week. Repeatedly deploying and terminating the same alias will exhaust that and leave the site on an untrusted certificate until the window rolls over. When testing, use a fresh alias each time.
- Screening. Repositories are scanned before anything is created, and
blocking findings refuse the deployment. scan_repository runs the same checks so you can see that first.