Bark Documentation

Bark is a free, lightweight tool for sending push notifications to your own iPhone. It relies on Apple Push Notification service (APNs) to ensure timely, stable, and reliable delivery. Because it uses system push services and push extensions, the app does not need to run in the background, meaning it does not consume device battery.

Bark consists of two main components:

1. Bark (iOS App): The client used to receive custom push notifications.
2. bark-server: The backend service that receives user push requests and forwards them to Apple APNs.

Decide whether to use the public service or host your own bark-server based on your required Queries Per Second (QPS):

• QPS < 200: You can continue using the public service (https://api.day.app).
• QPS > 200: It is recommended to set up your own server. High load on the public server may lead to future traffic restrictions.
• QPS > 3000: It is strongly recommended to set up your own server and include the --max-apns-client-count parameter during deployment to handle the load.

To ensure timely and high-volume delivery, choose your server type based on your expected Queries Per Second (QPS):

• QPS < 200: You can continue using the public service (https://api.day.app).
• QPS > 200: It is recommended to self-host a server. High load on public servers may lead to future traffic limits.
• QPS > 3000: You should definitely self-host. When deploying, it is recommended to add the --max-apns-client-count parameter to your deployment configuration.

1. Download the executable for your platform from the Bark Server Releases or compile from source.
2. Make the binary executable using chmod +x.
3. Run the server. By default, it uses the /data directory for storage. Use the -data flag to specify a custom directory and -addr to specify the listening address.

chmod +x bark-server_linux_amd64
./bark-server_linux_amd64 -addr 0.0.0.0:8080 -data ./bark-data

When manually constructing Bark API URLs, special characters in the {push_content} (such as /, +, or links) can cause the request to fail or return a 404 error because the routing becomes invalid.

Requirement: Always apply URL encoding to your parameters before concatenating them into the URL. It is recommended to URL-encode parameters regardless of whether they contain special characters.

Example of incorrect vs correct construction:

If your content is a/b/c/:

• Incorrect: https://api.day.app/key/a/b/c/ (Results in a 404 error)
• Correct: https://api.day.app/key/a%2Fb%2Fc%2F

Note: If you use a mature HTTP library, these parameters are typically handled automatically.

Batch pushing is supported via JSON requests. If using the public https://api.day.app server, there is a limit of 10 devices per request. Self-hosted servers have no limit. Note that bark-server must be updated to at least v2.1.9 to support this feature.

Required JSON payload fields:

• title: The title of the notification.
• body: The body content of the notification.
• sound: The sound file name (e.g., minuet).
• group: The group identifier for the notification.
• device_keys: An array of strings containing the device keys to receive the push.

curl -X "POST" "https://api.day.app/push" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{ 
  "title": "Title",
  "body": "Body",
  "sound": "minuet",
  "group": "test",
  "device_keys": ["key1", "key2", ... ]
}'

To protect push content from being intercepted by Bark or Apple APNs servers, you can enable custom push encryption within the app settings:

1. Open the Bark app home screen.
2. Locate “推送加密” (Push Encryption).
3. Click on 加密设置 (Encryption Settings).
4. Select your preferred encryption algorithm.
5. Enter your custom KEY as required.
6. Click complete to save your custom key.

To send a notification, first open the Bark app and copy your unique test URL. You can then send a GET or POST request to that URL. The URL structure follows these patterns:

• /:key/:body
• /:key/:title/:body
• /:key/:title/:subtitle/:body

Where title is bolded, subtitle is the subtitle, and body is the main content. For multi-line content in the body, use the newline character \n. For POST requests, use the same parameter names.

You can provide a URL Scheme to allow users to change their Bark server address with a single click. Use the bark://addServer scheme with the address parameter.

bark://addServer?address=https%3A%2F%2Fapi.day.app

To prevent privacy leaks at the server level (where request logs might be visible to server administrators), you can take the following actions:

1. Self-host the backend: Deploy your own backend service using the open-source code and enable HTTPS. See the deploy.md guide for instructions.
2. Use Encrypted Pushes: Use encrypted pushes with custom keys to encrypt the content of your notifications.

Bark can be used as a Model Context Protocol (MCP) server for AI tools. Replace {key} in the URLs with your actual Bark device key.

VS Code Configuration

Add the following to your VS Code settings:

Claude Code Configuration

Use the CLI command or add to your mcpServers configuration.

// VS Code
{
  "servers": {
    "bark": {
      "type": "http",
      "url": "https://api.day.app/mcp/{key}"
    }
  }
}

# Claude Code CLI
claude mcp add bark --transport http https://api.day.app/mcp/{key}

Before building, ensure your environment meets the following requirements:

• Golang: version 1.18 or higher
• Go Modules: Enable via GO111MODULE=on
• Go Proxy: Set GOPROXY=https://goproxy.cn
• Task Runner: Install go-task