# Orbit achievements API — Mac and Apple TV

Public base URL: https://orbit.vainsoft.io
LAN base URL: http://192.168.1.100:6086
Use the selected base for all relative API paths. Proxy details: /api/proxy/guide.

GET /api/bootstrap returns games with id, name, status and other library fields.
GET /api/games/{game_id}/achievements?language=en-US returns the trophy list.
Only prepared games can be read; an unprepared game returns 409.
The API reads local sce_sys/trophy2/trophyNN.ucp packages, including multiple service labels.
It writes a derived metadata cache under state/launcher/achievements and never changes game files.

Examples:
- /api/games/PPSA27623/achievements — Astroneer, 56 definitions.
- /api/games/PPSA14431/achievements — Size Matters, 33 definitions.
- /api/games/PPSA21564/achievements — ASTRO BOT, 50 definitions in this extracted version.
- Add ?language=fr-FR to request another language; packages[].language reports the actual language.
  If it is absent from the game, the package's default language is used.
- Add &download=1 for an attachment response.

Top-level fields: game_id, game_name, packages, trophies, total, users, selected_user,
progress_available, progress_source, unlocked_count, note.

Each trophy includes:
- key: stable service:id string; use this with game_id as the client identity.
- id and service: integer identifiers. Trophy IDs can repeat across service labels.
- name, description, grade (platinum/gold/silver/bronze), hidden, group_id, group.
- icon: relative PNG endpoint, or null. Resolve it against the base URL.
- condition: original local unlock-condition metadata, when present.
- unlocked: true, false, or null.
- unlocked_at: UTC ISO timestamp when present.

Icon endpoint:
GET /api/games/{game_id}/achievements/{service}/{id}/icon
Returns image/png. No source path or archive filename is supplied by the client.

Unlock records are read from Kyty's local state/_Trophies/{game_id}/trophies_{user}_{service}.json.
unlocked=null means that this local user/service has no record. Do not render it as locked.
false means a valid record exists and the trophy is absent from its unlocked set.
No local record currently exists for the tested Astroneer session, so its progress is unknown.
This is not PlayStation Network synchronization.

users lists local user IDs for which valid records exist. selected_user defaults to the first local user.
Supply ?user=ID to choose another local user. Querying an unknown user yields unknown progress.
Poll periodically or on returning to the trophy screen; definitions are cached but unlocks are read fresh.
There is no endpoint for forging or editing unlocks.

Hidden trophy text and icons are included in the JSON. Clients should conceal them by default until the
user chooses to reveal spoilers or the trophy is earned. The browser provides that reveal switch.

Read endpoints do not require X-Orbit-Token. Existing same-origin/host checks apply.
Native clients may omit Origin; use the server's real IP address or hostname.
The guide itself is available at GET /api/achievements/guide.