Treasure Master Hack

The REST API lets you integrate the search into your own tooling or run a custom client. All endpoints are HTTPS only.

Base URL

https://api.tm.micro500.org

Authentication

All API requests require an API credential. Create one on your API Credentials page (type: REST API). You'll receive an auth token in the form client_id:client_secret.

Pass the token as a Bearer header:

Authorization: Bearer <your_token>

Hosts

A host represents a machine submitting work. You must create a host before requesting workunits.

POST /hosts

Create a new host.

curl -X POST https://api.tm.micro500.org/hosts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "my-machine"}'

Returns: {"host_id": 1, "display_name": "my-machine", ...}

GET /hosts

List all your hosts.

curl https://api.tm.micro500.org/hosts \
  -H "Authorization: Bearer <token>"

GET /hosts/{host_id}

Get a specific host.

PATCH /hosts/{host_id}

Update a host's display name.

curl -X PATCH https://api.tm.micro500.org/hosts/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "new-name"}'

DELETE /hosts/{host_id}

Archive a host (stops it from receiving new work).

Workunits

POST /workunits/request

Request one or more workunits for a host.

curl -X POST https://api.tm.micro500.org/workunits/request \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"host_id": 1, "task_type_id": 1, "count": 1}'

Returns an array of workunit objects, each including:

workunit_id — token used for submission
task_metadata — contains chunk_id, range_start
workunit_size — number of keys to check (e.g. 16777216)
seed — 64-char hex string for challenge generation
report_deadline — Unix timestamp by which results must be submitted

GET /workunits

List your workunits. Optional query params: host_id, status.

curl "https://api.tm.micro500.org/workunits?host_id=1&status=sent" \
  -H "Authorization: Bearer <token>"

GET /workunits/{workunit_id}

Get a specific workunit.

POST /workunits/{workunit_id}/submit

Submit a result file for a workunit. The body is the raw binary result file. Optional query param: cpu_time (seconds as float).

curl -X POST "https://api.tm.micro500.org/workunits/<id>/submit?cpu_time=12.5" \
  -H "Authorization: Bearer <token>" \
  --data-binary @result.bin

Returns: {"status": "ok"}

DELETE /workunits/{workunit_id}

Cancel a workunit you won't be able to complete.

Result file format

See the GitHub repository for the binary result file specification and reference implementations.

Questions?

Ask on Discord or open an issue on GitHub.