API overview

This page provides general information about the EmuSync local agent API, including how it can be accessed, common error handling behavior, and basic examples of making requests.

The API is intended for advanced users who want to interact with EmuSync programmatically (for example, via scripts or third-party tools).

Documentation for endpoints can be found here:

• Game
• GameSync

Thanks to SidoIndeedo for creating the API documentation!

Agent Overview

The EmuSync agent runs locally on your device as a background service. It exposes a small HTTP API that is used by the EmuSync UI and can also be accessed externally for automation purposes.

The API is only available while the agent is running.

Base URL

All API endpoints are exposed on the following base URL:

http://localhost:5353

All documented endpoints are relative to this base URL.

Authentication

No authentication is required.

The API is only accessible locally and is not exposed over the network.

Request Format

• Requests use standard HTTP methods (GET, POST).
• Route parameters are passed as part of the URL path.
• None of the documented endpoints currently use query string parameters.
• Most POST endpoints do not require a request body.

Response Format

• Successful requests return standard HTTP status codes.

• Some endpoints return JSON responses.

• Some endpoints return no response body on success.

If an endpoint returns JSON, the response structure can be found in the corresponding DTO within the EmuSync codebase.

Common HTTP Status Codes

The following HTTP status codes may be returned by the API:

• 200 OK: The request completed successfully.

• 400 Bad Request: The request was invalid. This can occur due to validation errors or when required configuration (such as a sync source) has not been set up.

• 404 Not Found The requested resource could not be found. This usually indicates that an invalid ID was provided.

• 500 Internal Server Error An unexpected error occurred within the agent. These errors are handled by the global exception handler.

Error Responses

All error responses use a standard JSON error format.

Errors are generated using one of the following mechanisms:

• 400 Bad Request Returned using BadRequestWithErrors.

• 404 Not Found Returned using NotFoundWithErrors.

• 500 Internal Server Error Returned when an unhandled exception is caught by the global exception handler.

The exact structure of the error response may vary depending on the error type.

Example Requests

Example using curl

curl -X POST http://localhost:5353/GameSync/abcdef123456

Example using PowerShell

Invoke-RestMethod -Method Post http://localhost:5353/GameSync/abcdef123456

These examples assume that the EmuSync agent is running and that the provided game ID is valid.

Notes

• The API is not intended to fully replace the EmuSync UI.
• Only a subset of endpoints are documented and considered useful for automation.
• Undocumented endpoints should be considered internal and any endpoint may change without notice.