actual-http-api

You can use the provided budget_backup.sh script to back up your Actual budget to a specific destination.

To use the script, you must update the following variables within budget_backup.sh:

• ACTUAL_BUDGET_URL: The URL of your Actual server.
• ACTUAL_BUDGET_API_KEY: Your API key.
• ACTUAL_BUDGET_SYNC_ID_LIST: A list of sync IDs for the budgets you wish to back up.

After configuring the variables, grant execution permissions and run the script. You can schedule this via cron (Linux/macOS) or Task Scheduler (Windows) for automated daily backups.

# Update these in budget_backup.sh
ACTUAL_BUDGET_URL="..."
ACTUAL_BUDGET_API_KEY="..."
ACTUAL_BUDGET_SYNC_ID_LIST=("...")

# Run the script
chmod +x budget_backup.sh
./budget_backup.sh

There are two ways to run the project locally:

Option 1: Docker Compose

Run using the provided configuration:

docker-compose up -d

You can adjust environment variables in the docker-compose.yml file or via an .env file.

Option 2: Node.js

Install dependencies and start the server directly:

npm install
npm start
# or
node server.js

Note: The project automatically loads a .env file in the project root when NODE_ENV is not set to production.

You can deploy the service using a publicly published Docker image. This provides a REST interface to your Actual Budget server. By default, the service exposes Swagger UI at http://localhost:5007/api-docs/.

docker run -d --name actualhttpapi \
  -v "$PWD/data:/data:rw" \
  -p 5007:5007 \
  -e ACTUAL_SERVER_URL="http://actual-server:5006/" \
  -e ACTUAL_SERVER_PASSWORD="your-actual-password" \
  -e API_KEY="your-api-key" \
  jhonderson/actual-http-api:26.2.0

To deploy actual-http-api as a Docker container on Fly.io, use the provided fly.toml configuration.

Before deploying, you must set the following required secrets in your Fly console or via the fly secrets CLI:

• ACTUAL_SERVER_PASSWORD
• API_KEY

Most API endpoints are scoped to a specific budget using a budgetSyncId path parameter. This ID is the Synchronization ID found in Actual Budget under Settings → Show advanced settings → Sync ID.

To access these resources, you must include the budgetSyncId in the URL path. For example, if your sync ID is abc-123, your base path for resources like accounts or transactions would be /budgets/abc-123/accounts or /budgets/abc-123/transactions.

Security Note: If you are using an end-to-end encrypted budget, you must provide the encryption password in the budget-encryption-password HTTP header.

GET /budgets/:budgetSyncId/accounts
Header: budget-encryption-password: <your-password>

You can deploy the actual-http-api using Docker Compose. The service maps port 5007 and requires a local ./data directory for persistent storage. You must provide environment variables to connect to your Actual Budget server and secure the API.

version: '3.3'
services:
    actual-http-api:
        container_name: actualhttpapi
        volumes:
            - './data:/data:rw'
        ports:
            - '5007:5007'
        environment:
            - 'ACTUAL_SERVER_URL=http://localhost:5006/'
            - 'ACTUAL_SERVER_PASSWORD=my-actual-server-password'
            - 'API_KEY=my-strong-api-key'
        restart: on-failure
        image: jhonderson/actual-http-api:latest

The POST /v1/budgets/import endpoint allows you to import an Actual export or a YNAB4/YNAB5 file.

Important Behavior:

• Content-Type: Must be application/zip or application/octet-stream.
• New Sync ID: Importing an existing budget does not overwrite it. The Actual library clears the server identity on import, so the budget is uploaded as a new file with a new sync id. The original budget remains untouched. You must use the syncId returned in the response to interact with the newly imported budget.

curl -X POST 'http://localhost:5007/v1/budgets/import?type=actual' \
  -H 'x-api-key: your-api-key' \
  -H 'Content-Type: application/zip' \
  --data-binary '@2026-09-06-My-Budget.zip'

Remove a tag from a budget.

Endpoint: DELETE /budgets/{budgetSyncId}/tags/{tagId}

Response: Returns a JSON object with a success message.

Example Response:

{
  "message": "Tag deleted"
}

Reopen an account that was previously closed.

PUT /budgets/{budgetSyncId}/accounts/{accountId}/reopen