API docs

Run your ARK servers from your own website or Discord bot: give items, dinos and kits, hand out points, moderate players, talk in chat, and hear about what happens in game.

Everything is plain HTTPS and JSON. The examples below use curl and JavaScript, but any language works. The full list of endpoints is at the bottom of this page, and machine-readable at GET /v1/openapi.json.

Quick start

1. Ask the account owner for a key. They make it in the app, under Permissions → API.
2. Check it works:

curl https://www.control-ark.com/v1/me -H "Authorization: Bearer ark_k_xxxxxxxx"

1. Find a player, then give them something:

curl "https://www.control-ark.com/v1/players?gamertag=SomeGuy123" -H "Authorization: Bearer $ARK_KEY"

curl -X POST https://www.control-ark.com/v1/players/2535400000000001/items \
  -H "Authorization: Bearer $ARK_KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"blueprint":"/Game/PrimalEarth/CoreBlueprints/Resources/PrimalItemResource_MetalIngot.PrimalItemResource_MetalIngot","quantity":500}]}'

That's it. The player gets the ingots and a chat message saying they arrived.

Getting a key

The account owner makes keys in the app, under Permissions → API. Each key has:

• What it can do: deliveries, points, player actions, moderation and so on. Tick only what your code needs.
• Servers: all of the account's servers, or some of them.
• IP addresses (optional, under Advanced): where calls must come from. Use this whenever your bot runs on a fixed server.

Everything else (which player, which dino, its level and stats, whether a kit costs points) goes in each call.

The key (ark_k_…) is shown once. Keep it on your server, never in a web page or a public repository: anyone who has it can do what it allows.

A key can't teleport anyone, use spectator, move or control the bots, or send console commands of its own.

How calls work

Send the key with every call:

Authorization: Bearer ark_k_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bodies are JSON, sent with Content-Type: application/json.

Players are named by XUID

Everything you do to a player goes to /v1/players/{xuid}/…. You only need their XUID: the API finds which of your servers they're on, and their character there, by itself.

Don't know the XUID? Search for them:

GET /v1/players?gamertag=SomeGuy123
GET /v1/players?name=rex          (gamertag or character name contains "rex")
GET /v1/players?tribe=Herd&online=true

Each player comes back once, with a row for every server they've played on (each server has its own character):

{
  "xuid": "2535400000000001",
  "gamertag": "SomeGuy123",
  "firstSeen": "2026-10-01T18:22:04.000Z",
  "lastSeen": "2026-10-29T14:03:11.000Z",
  "online": true,
  "servers": [
    { "serverId": "cm2…", "server": "PvE Island", "name": "Rexy", "implant": 123456789,
      "tribe": "The Herd", "tribeId": 1234567890, "online": true, "lastSeen": "2026-10-29T14:03:11.000Z" }
  ]
}

The filters are server, online, xuid, implant, gamertag (exact, any case), name, tribe, tribeId and page. Use any number of them together.

In-game actions need the player to be on right now. If they aren't, you get 409 player_offline. If someone is on more than one of your servers and you want a particular one, add "server": "<server id>" to the body. Your server ids are in GET /v1/servers.

Answers

Every action answers with an id. Keep it if you want to check on the call later.

Every refusal looks like this:

{ "error": { "code": "player_offline", "message": "that player isn't on any of this key's servers right now" } }

Limits

Each key may make 120 reads and 30 in-game actions a minute. Every answer has X-RateLimit-Limit and X-RateLimit-Remaining. Up to 50 deliveries per key can be on their way at once. Calls that can't be undone have a daily cap per key: 20 inventory clears, 5 tribe destroys and 6 wild dino wipes.

Retrying safely

Send Idempotency-Key: <something unique> with every action, such as your order number or the Discord message id. If you send the same key again (after a timeout, say), you get the first answer back with Idempotency-Replay: true, and nothing is done twice. A refused call (player_offline, for example) isn't stored, so you can retry it with the same key later.

Examples

Items

POST /v1/players/2535400000000001/items
{ "items": [
    { "blueprint": "/Game/PrimalEarth/CoreBlueprints/Resources/PrimalItemResource_MetalIngot.PrimalItemResource_MetalIngot",
      "quantity": 1000, "stackSize": 200 },
    { "blueprint": "/Game/PrimalEarth/CoreBlueprints/Weapons/PrimalItem_WeaponRifle.PrimalItem_WeaponRifle",
      "quality": 10, "asBlueprint": true },
    { "itemId": 121, "quantity": 2 }
] }

Dinos

A level 150 Rex in a cryopod:

POST /v1/players/2535400000000001/dinos
{ "method": "cryo",
  "dinos": [{ "blueprint": "/Game/PrimalEarth/Dinos/Rex/Rex_Character_BP.Rex_Character_BP", "level": 150 }] }

An Argentavis with exact stats and colours, and a breeding pair of Ankylos, dropped next to the player:

POST /v1/players/2535400000000001/dinos
{ "method": "unclaim",
  "dinos": [
    { "blueprint": "/Game/PrimalEarth/Dinos/Argentavis/Argent_Character_BP.Argent_Character_BP",
      "wildPoints": [40, 40, 0, 40, 40, 0, 0, 0], "tamedPoints": [0, 0, 0, 0, 0, 0, 0, 0],
      "colors": [12, 0, 0, 55, 0, 0] },
    { "blueprint": "/Game/PrimalEarth/Dinos/Ankylo/Ankylo_Character_BP.Ankylo_Character_BP", "level": 120, "pair": true }
  ] }

method is cryo (in a cryopod, handed to the player) or unclaim (the bot stands beside the player, spawns the dino there and unclaims it so they can claim it). Up to 10 dinos per call. The answer is 202, so follow it:

GET /v1/jobs/cm2abc…
{ "id": "cm2abc…", "action": "deliver.dinos", "status": "done", "dinos": { "done": 2, "total": 2 }, … }

Kits

GET /v1/kits
[{ "name": "starter", "cost": 100, "items": [{ "name": "Metal Pick", "blueprint": "…", "quantity": 1 }], "dinos": [] }]

POST /v1/players/2535400000000001/kit
{ "kit": "starter", "chargePoints": true }

chargePoints (default false) takes the kit's cost from the player's points. ignoreRules: true skips the kit's own limits and cooldowns.

Several things at once

batch runs up to 10 commands for one player, in order. Each one is checked and counted as its own call, so the key needs every scope they use.

POST /v1/players/2535400000000001/batch
{ "commands": [
    { "command": "kit", "kit": "vip" },
    { "command": "points.add", "amount": 1000, "reason": "VIP purchase" },
    { "command": "message", "message": "Thanks for supporting the server!" }
  ],
  "stopOnError": true }

The answer has one result per command:

{ "xuid": "2535400000000001", "results": [
    { "command": "kit", "status": 200, "answer": { "id": "…", "status": "done", "kit": "vip", … } },
    { "command": "points.add", "status": 200, "answer": { "balance": 1500, … } },
    { "command": "message", "status": 200, "answer": { … } }
] }

With stopOnError, the commands after a refusal are skipped.

Player actions

POST /v1/players/2535400000000001/experience   { "amount": 50000 }
POST /v1/players/2535400000000001/tek-engrams  {}
POST /v1/players/2535400000000001/ascension    { "type": "boss", "boss": "Manticore", "difficulty": "alpha" }
POST /v1/players/2535400000000001/kill         {}
POST /v1/players/2535400000000001/mindwipe     {}
POST /v1/players/2535400000000001/tribe        { "tribeId": 1234567890 }
POST /v1/players/2535400000000001/color        { "colors": { "0": 12, "3": 55 } }
POST /v1/players/2535400000000001/imprint      { "anyTamed": false }

For color and imprint, the bot goes to the player and works on their tribe's nearest dino (for imprint, the nearest baby). Ask the player to stand next to it.

Moderation

POST   /v1/players/2535400000000001/kick       { "reason": "AFK" }
POST   /v1/players/2535400000000001/ban        { "reason": "cheating" }
DELETE /v1/players/2535400000000001/ban
POST   /v1/players/2535400000000001/whitelist

Bans and the whitelist work whether the player is on or not, on every one of the key's servers (or only on server, if you give one).

Points from a Discord bot

const ARK = "https://www.control-ark.com/v1";
const headers = { authorization: `Bearer ${process.env.ARK_KEY}`, "content-type": "application/json" };

// /vote reward: 500 points, once per Discord interaction even if it's retried.
const res = await fetch(`${ARK}/players/${xuid}/points/add`, {
  method: "POST",
  headers: { ...headers, "idempotency-key": interaction.id },
  body: JSON.stringify({ amount: 500, reason: "Voted" }),
});
const out = await res.json();
await interaction.reply(res.ok ? `New balance: ${out.balance}` : `Couldn't: ${out.error.message}`);

A shop order on your website

// Give the order, wait for the dinos, then mark it paid out.
const order = await fetch(`${ARK}/players/${xuid}/dinos`, {
  method: "POST",
  headers: { ...headers, "idempotency-key": `order-${orderId}` },
  body: JSON.stringify({ method: "cryo", dinos: [{ blueprint: REX, level: 150 }] }),
}).then((r) => r.json());

if (order.error) throw new Error(order.error.message);
let job = order;
while (job.status === "running") {
  await new Promise((r) => setTimeout(r, 3000));
  job = await fetch(`${ARK}/jobs/${order.id}`, { headers }).then((r) => r.json());
}
console.log(job.status === "done" ? "delivered" : `failed: ${job.detail}`);

Server messages

POST /v1/servers/{id}/broadcast   { "message": "Double XP this weekend!" }
POST /v1/tribes/1234567890/message  { "message": "Your vault is open" }

Webhooks

To hear about events, add a webhook with POST /v1/webhooks (scope webhooks), or have the owner add one in the app. The answer includes a secret (whsec_…) that is shown once.

Each event is a POST like this:

{ "id": "evt_…", "type": "delivery.done", "createdAt": "2026-10-29T14:03:11.000Z", "serverId": "…", "data": { … } }

Answer with any 2xx within 5 seconds. A failed post is tried again after 5 and then 30 seconds. A webhook that fails 20 times in a row is paused until it's resumed (PATCH /v1/webhooks/{id} with { "disabled": false }).

Checking the signature

Every post has X-Ark-Signature: t=<unix seconds>,v1=<hex>, where hex is the HMAC-SHA256 of <t>.<raw body> keyed with your secret. Check it, and turn away posts whose t is more than 5 minutes old:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const [, t, sig] = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header ?? "") ?? [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(sig, "hex");
  return got.length === want.length && timingSafeEqual(got, want);
}

Webhook addresses must be https and can't point at private or local networks.

Every endpoint

The scope on the right is what the key needs. The same list, machine-readable, is at /v1/openapi.json.

Your key and servers

Players

Giving things

{
  "items": [
    {
      "blueprint": "/Game/PrimalEarth/CoreBlueprints/Resources/PrimalItemResource_MetalIngot.PrimalItemResource_MetalIngot",
      "quantity": 500,
      "quality": 0,
      "asBlueprint": false,
      "stackSize": 100
    },
    {
      "itemId": 121,
      "quantity": 1
    }
  ]
}

{
  "method": "cryo",
  "dinos": [
    {
      "blueprint": "/Game/PrimalEarth/Dinos/Rex/Rex_Character_BP.Rex_Character_BP",
      "level": 150,
      "count": 1,
      "pair": false,
      "colors": [
        0,
        0,
        0,
        0,
        0,
        0
      ]
    }
  ]
}

{
  "kit": "starter",
  "chargePoints": false,
  "ignoreRules": false
}

Player actions

{
  "amount": 50000,
  "shareWithTribe": false
}

{
  "type": "boss",
  "boss": "Manticore",
  "difficulty": "alpha"
}

{
  "colors": {
    "0": 12,
    "3": 55
  }
}

{
  "anyTamed": false
}

{
  "inventory": true,
  "slotItems": true,
  "equipped": false
}

{
  "message": "Thanks for voting!"
}

{
  "tribeId": 1234567890
}

{
  "commands": [
    {
      "command": "items",
      "items": [
        {
          "blueprint": "/Game/PrimalEarth/CoreBlueprints/Resources/PrimalItemResource_MetalIngot.PrimalItemResource_MetalIngot",
          "quantity": 100
        }
      ]
    },
    {
      "command": "experience",
      "amount": 10000
    },
    {
      "command": "message",
      "message": "Your order is here!"
    }
  ],
  "stopOnError": false
}

Moderation

{
  "reason": "AFK"
}

{
  "name": "Survivor"
}

{
  "reason": "cheating"
}

Points

{
  "amount": 500,
  "reason": "Voted"
}

{
  "amount": 500,
  "reason": "Shop purchase"
}

{
  "from": "2535400000000001",
  "to": "2535400000000002",
  "amount": 100
}

Servers

{
  "message": "Restart in 10 minutes"
}

{
  "message": "Double XP weekend!"
}

{
  "message": "Welcome to the server"
}

{
  "time": "08:00"
}

Tribes

{
  "message": "Your vault is open"
}

{
  "tribe": "Old Name",
  "newName": "New Name"
}

{
  "players": [
    "2535400000000001",
    "2535400000000002"
  ],
  "tribe": "Allies"
}

{
  "server": "server id",
  "what": "structures",
  "confirm": 1234567890
}

Following your calls

Giveaways

Webhooks

{
  "url": "https://example.com/ark-events",
  "events": [
    "player.joined",
    "delivery.done"
  ],
  "serverIds": null
}

{
  "disabled": false
}