Quickstart

Five minutes from zero to a running Minecraft server you control over the API. Pick the path that fits you: raw curl, the TypeScript SDK, or the CLI dev-loop.

Servers are metered + scale-to-zero: you're billed per GB-second only while a server is awake. A server you create but never start costs nothing. See Billing.

1. Get an API key

Sign up

Create an account at truetick.gg/signup (opens in a new tab). New accounts get a small starting credit, so you can try the steps below before topping up.

Create a key

Go to Dashboard → API keys (opens in a new tab), click Create key, and select the scopes you need. For this quickstart, grant servers:read, servers:write, and console.

Keys look like ttk_… and are shown once — copy it now. See Authentication for the full scope catalog.

export TRUETICK_API_KEY="ttk_your_key_here"

Every request carries this key in the x-api-key header. The base URL is https://api.truetick.gg.

2. Create a server

A server needs a name, RAM, a core (e.g. PAPER), and a Minecraft version. The server id and hostname are derived from the name (My SMP → my-smp → my-smp.truetick.gg).

With curl you supply the derived fields explicitly. Grab your accountId from /v1/whoami first:

ACCOUNT_ID=$(curl -s -H "x-api-key: $TRUETICK_API_KEY" \
  https://api.truetick.gg/v1/whoami | jq -r .accountId)
 
curl -X POST https://api.truetick.gg/v1/servers \
  -H "x-api-key: $TRUETICK_API_KEY" \
  -H "content-type: application/json" \
  -d "{
    \"id\": \"my-smp\",
    \"name\": \"my-smp\",
    \"hostname\": \"my-smp.truetick.gg\",
    \"container\": \"mc_my-smp\",
    \"addr\": \"\",
    \"accountId\": \"$ACCOUNT_ID\",
    \"ramMb\": 4096,
    \"type\": \"PAPER\",
    \"version\": \"1.21.1\",
    \"plan\": \"metered\",
    \"region\": \"na\"
  }"

Creating a server does not start it — it lands in a stopped, scale-to-zero state. No charge yet.

3. Wake it

Bring the server online. (A player joining my-smp.truetick.gg:25565 would also wake it automatically — that's wake-on-join. Programmatically, you call start.)

curl -X POST https://api.truetick.gg/v1/servers/my-smp:start \
  -H "x-api-key: $TRUETICK_API_KEY"

Cold start is typically ~12 s for a vanilla/Paper server (longer for modded). Poll the server until state is running.

4. Run a console command

Once running, send any RCON command:

curl -X POST https://api.truetick.gg/v1/servers/my-smp:command \
  -H "x-api-key: $TRUETICK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"command": "say Hello from the API!"}'

Requires the console scope. Returns { "output": "<rcon reply>" }.

5. Read the logs

Fetch a recent snapshot, or follow the live stream.

# Snapshot of the last 100 lines
curl -s -H "x-api-key: $TRUETICK_API_KEY" \
  "https://api.truetick.gg/v1/servers/my-smp/logs?tail=100"
 
# Live stream over Server-Sent Events (Ctrl-C to stop)
curl -N -H "x-api-key: $TRUETICK_API_KEY" \
  "https://api.truetick.gg/v1/servers/my-smp/logs/stream?tail=50"

See Stream logs for the SSE frame format and stream limits.

6. Stop (or tear down)

When you're done, stop the server to halt metered billing, or delete it entirely.

# Stop (data preserved, billing stops)
curl -X POST https://api.truetick.gg/v1/servers/my-smp:stop \
  -H "x-api-key: $TRUETICK_API_KEY"
 
# Delete (permanent)
curl -X DELETE https://api.truetick.gg/v1/servers/my-smp \
  -H "x-api-key: $TRUETICK_API_KEY"

The CLI dev-loop (for plugin/mod authors)

If you're building a plugin or mod, the CLI has a tighter loop than raw lifecycle calls. init provisions an ephemeral metered dev server and writes truetick.toml; deploy builds, uploads the jar over SFTP, restarts, and confirms the jar loaded by scanning the log:

truetick login                                          # device flow, or --key ttk_…
cd my-plugin
truetick init --create --name "Dev" --ram 4096 --type PAPER --yes
truetick deploy                                         # build → upload → restart → confirm
truetick dev                                            # redeploy on every rebuild + tail logs
truetick down --yes                                     # delete the ephemeral dev server

Full reference: CLI · recipe: Deploy a plugin.

Next steps

Authentication — keys, scopes, rate limits, the CLI device flow
Concepts — the server model, lifecycle, billing, and the honesty metrics
Guides — ephemeral CI servers, plugin deploys, log streaming, agents
API Reference — all 60 endpoints, rendered from the OpenAPI spec

Introduction Authentication