Astra API

Companion API Setup

Astra's Local Integration API lets a program on the same computer observe playback and, with your permission, control selected parts of Astra. It is intended for launchers, widgets, automations, creative tools, and other companion apps.

This page covers setup and permissions. Developers implementing a client should use the current Local Integration API documentation, where the complete v2 contract and v1 compatibility notes are maintained.

Enable the API

Open Settings > Integrations > Local API, then enable Local Integration API. Astra shows:

• Local API Endpoint: the loopback address used by clients. The default is http://127.0.0.1:38401.
• Local API Key: the secret a client must present.
• Local API Port: any available port from 1024 through 65535.

The service listens on 127.0.0.1, so other computers and phones cannot connect to this endpoint over your network. Use Phone Remote for a paired phone connection.

Choose permissions

Observation is available whenever the API itself is enabled. The other capabilities are separate switches:

Setting	What a client may do
External Playback Controls	Operate playback and supported current-track actions.
Library Search	Search a bounded view of the Astra library. It does not expose a raw catalog or audio files.
Favorites & Playlist Changes	Change favorites and supported playlist data.

Only enable a capability when the client actually needs it. A request outside the enabled permissions is rejected rather than silently granted.

Connect a companion app

1. Enable the API and any needed permissions.
2. Copy the endpoint and key from Astra.
3. Paste them into the companion app.
4. Keep the key in that app's secure credential storage if it offers one.

Treat track references returned by Astra as opaque identifiers. A client should not display or interpret them as file paths.

Key and port safety

The API key is equivalent to access under the permissions you enabled. Do not paste it into screenshots, issue reports, or untrusted scripts.

Choose Regenerate if a key was exposed or a client should lose access. All clients using the old key stop authenticating immediately; update the ones you still trust with the new key.

Changing the port also changes the endpoint. Clients keep trying the old address until you update their configuration.

Local API versus phone pairing

These features share some permission ideas but are not the same connection:

• Local API: manual endpoint and master key, loopback only, for software on this computer.
• Phone Remote: HTTPS over your local network, a short-lived pairing request, and a separately revocable identity for each phone.

Do not copy the Local API key into the Phone Remote unless a legacy or third-party controller explicitly requires it. Astra's current browser and mobile pairing flow creates its own device credentials.

Troubleshooting

• Connection refused: enable the API, confirm the port shown in Astra, and make sure another program is not using it.
• Unauthorized: copy the key again. If it was regenerated, the old value cannot be reused.
• A command is forbidden: enable the matching permission in Astra.
• A phone cannot reach 127.0.0.1: that address means the phone itself. Use Phone Remote instead.
• A client expects /v1/...: Astra keeps v1 compatibility, but new integrations should follow the v2 documentation.