---
topic: embarko-json
connector: "deploy_app: embarko.json is one of the files"
api: "POST https://ship.embarko.ai/apps (the file travels in the upload)"
requires: [deploy]
---

[← Guide home](https://embarko.ai/docs)

# The embarko.json file

**On this page:** Steps, Examples, Limits, Errors

> Plain words unless the person is a developer. Never invent a link, name or code. [Rules](https://embarko.ai/docs/prerequisites) Needs first: [deploy](https://embarko.ai/docs/deploy).

embarko.json is an optional file in the app's top folder, next to package.json. Embarko reads it on every deploy. Today it holds one setting: schedules, the timed calls into the app. Most apps never need one.

**Connector:** deploy_app: embarko.json is one of the files

**Done when:** The deploy reply has no embarko.json error or warning, and its schedules facts match the file.

**Steps**

1. Create embarko.json in the app's top folder, next to package.json (or requirements.txt, go.mod...).
2. Write one JSON object. Put the settings in it, such as "schedules" (see schedules).
3. Optional: add "$schema": "https://embarko.ai/schema/embarko.json" so editors can check it.
4. Deploy as usual: skill, HTTP .tar.gz, JSON files list or connector. The file goes with the other files; there is no special field.
5. Read the reply. A 400 names what is wrong; fix the file and deploy again. Read warnings[] and fix those too before telling the person it is done.

**Example: embarko.json with one schedule**

```json
{
  "$schema": "https://embarko.ai/schema/embarko.json",
  "schedules": [
    {
      "cron": "0 9 * * 1-5",
      "path": "/tasks/daily-digest",
      "timezone": "Asia/Kolkata",
      "name": "daily digest"
    }
  ]
}
```

Only "schedules" is used today. Its fields: see schedules.

**Limits**

- Optional. No file means no change.
- The file is the source of truth. A setting changed through the API is set back by the next deploy whose file lists it.
- "schedules" is the app's full set, matched by path. [] removes all. A file without a "schedules" key leaves them as they are.
- Never put secrets in it. It is part of the code and is never private. Use env vars (see env-vars).
- Only the top folder is read. A copy in a subfolder is ignored.
- Only the exact name embarko.json is read. Not .embarko, embarko.yaml, embarko.config.json or embarko.jsonc.
- Plain JSON: no comments, no trailing commas.
- Unknown keys are ignored, with a warning.
- At most 64 KB.

**Errors**

| Code | Status | Retry | What to do |
| --- | --- | --- | --- |
| `invalid_embarko_json` | 400 | No | Not valid JSON (the message gives line and column), not one object, "schedules" is not a list, or over 64 KB. Fix the file and deploy again. |
| `secrets_in_embarko_json` | 400 | No | A key named like secret, token, password, api key, private key or credential, or a value that looks like a key or a URL with ?token=. Remove it and set it as an env var. |
| `invalid_schedules / invalid_cron / schedule_too_frequent / invalid_timezone / invalid_path / duplicate_schedule_path / schedule_limit_reached` | 400 | No | A schedule entry is wrong. The message names it, e.g. "Schedule 1: ...". Fixes: see schedules. |
| `embarko_json_not_at_top (warning)` | 202 | No | Found in a subfolder; only the top folder is read. Move it next to package.json and deploy again. |
| `embarko_json_misnamed (warning)` | 202 | No | A file like .embarko or embarko.yaml was found. Rename it to embarko.json, as JSON, and deploy again. |
| `embarko_json_unknown_keys (warning)` | 202 | No | Keys Embarko does not use were ignored. Remove them, or check the spelling of "schedules". |
| `in_process_timer (warning)` | 202 | No | The code uses a timer library (node-cron, APScheduler...) and the file lists no schedules. Move each job into a route and list it under "schedules". |
| `schedules_unchanged (warning)` | 202 | No | The app has schedules and this upload declares none, so they were kept. To remove them, deploy with "schedules": []. |
| `schedules_on_static_site (warning)` | 202 | No | A static site runs no code, so its schedules were not applied. Deploy it as a server app to use them. |

**Next:** Add embarko.json only if the app needs a setting in it, then deploy and read the reply's warnings.

**Related:** [schedules](https://embarko.ai/docs/schedules) · [env-vars](https://embarko.ai/docs/env-vars) · [errors](https://embarko.ai/docs/errors)

---

[Guide home](https://embarko.ai/docs) · JSON: add .json