Toggl API Compatibility

OpenTickly speaks the same API as Toggl. Scripts, CLIs, and agents written for Toggl can talk to your OpenTickly instance once you change the URL and the token. We follow three Toggl APIs: Track v9, Reports v3, and Webhooks v1.

Base URLsCopy Anchor Link

Replace https://your-instance.example with the public URL of your OpenTickly server.

If clients reach your instance over the internet, put it behind HTTPS. The Docker container itself only serves plain HTTP, so HTTPS is usually handled by a reverse proxy such as Nginx or Caddy.

Get an API tokenCopy Anchor Link

Sign in to the OpenTickly web app, open your avatar menu, choose Profile, and find API Token. Treat the token like a password: don't commit it to git, paste it into issues, or print it in logs.

Authentication works the same as Toggl: HTTP Basic auth with the token as the username and the literal string api_token as the password:

curl --user "${OPENTICKLY_API_TOKEN}:api_token" \
  https://your-instance.example/api/v9/me

Set OPENTICKLY_API_TOKEN in your shell first. If you get your user info back, the token works.

Switch an existing tool to OpenTicklyCopy Anchor Link

Most tools only need two changes:

1. Replace the Toggl API address with your OpenTickly address from the table above.
2. Use your OpenTickly API token instead of your Toggl one.

For toggl-cli:

toggl auth <YOUR_API_TOKEN> \
  --api-type opentoggl \
  --api-url https://your-instance.example/api/v9

If a third-party app has Toggl's address built in and no setting to change it, it can't be pointed at OpenTickly.

Test before you switchCopy Anchor Link

Test the requests your tool actually makes, not the whole API. Before you rely on it:

1. Read the current user with GET /api/v9/me.
2. List your workspace, projects, tags, and recent time entries.
3. Create and stop a test time entry.
4. Run the same report query your script uses.
5. If you use webhooks, create a test subscription and delete it afterwards.
6. Check error handling, pagination, dates, and time zones.

Not every Toggl endpoint behaves identically yet. If something works on Toggl but not on OpenTickly, open a GitHub issue with the request and the response you got.

For scripts that run on their own, keep the URL and token out of your code, use an account that only has access to the workspaces it needs, and reset the token if it leaks.