Time zones

TL;DR

Two ways to give a time

publishAt takes either form, on Schedule a post, Change a scheduled post and Schedule a post from a template:

A local time is the clock on the wall: the same 09:00 in Athens is 07:00 UTC in winter and 06:00 UTC in summer, and Flung follows the change for you. Send a local time when a person said "9am"; send an instant when your own system already has one.

timeZone is an IANA name, such as Europe/Athens, America/New_York, Australia/Sydney or Asia/Kathmandu. Abbreviations such as EET and bare offsets such as +02:00 are not zones, and are refused with 422 and the code invalid_time_zone. With an instant, timeZone changes nothing about when the post goes; it names the zone publishAtLocal is written in.

The caller's zone

When a request names no timeZone, Flung reads a local time in the first of these that is set:

A person's zone is set the first time they sign in, from where they sign in from, and they can change it at any time; a zone they chose is never replaced. Who is calling answers the zone a call would use, where it came from (timeZoneSource: user, workspace or default), and the time now in UTC (now) and there (nowLocal):

1curl -X GET 'https://api.flung.dev/v1/me' \2  --header "Authorization: Bearer $FLUNG_API_KEY"

1import { Flung } from '@flung.dev/sdk'2
3const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })4const result = await flung.me.get()

1const response = await fetch('https://api.flung.dev/v1/me', {2  method: 'GET',3  headers: {4    'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`,5  },6})7if (!response.ok) throw new Error((await response.json()).error.message)8const result = await response.json()

Suggest posting times uses the caller's zone too when you leave out its timeZone, and each time it suggests carries that zone's offset, ready for publishAt.

What comes back

Every post, from creating, changing, reading and listing it, and in webhook payloads, says its time three ways:

Show a person publishAtLocal, and compare and sort by publishAt.

When the clocks change

Twice a year, many zones skip an hour or repeat one. In Athens the clocks go from 03:00 to 04:00 on the last Sunday of March, and from 04:00 back to 03:00 on the last Sunday of October.

A warnings entry has a code and a message for a person, and appears only on the answer that created or changed the post. To pick the second 03:30 of a repeated hour, send it with its offset, 2026-10-25T03:30:00+02:00.

AI agents

The MCP server works the same way, so an agent never does time-zone arithmetic. Its scheduling tools take publishAt as the local time the person said, and timeZone only when they named a place ("9am Athens time"). The answer gives publishAt in UTC with publishAtLocal and timeZone, so the agent can confirm the time back in the person's own words. The get_time tool says the person's zone and the time there now, for turning "tomorrow morning" into a date. See schedule_post and get_time in the tool reference.

In the portal

On the Account page, the Time zone field shows the zone dates are written in for you, with its offset from UTC and the time there now. It says when it was set from your location; choose another at any time. A workspace's owners set its default zone, for its API keys, in the workspace's settings. Every date and time in the portal is shown in your zone, with the zone's short name where the time matters. To move a scheduled post, open it on the Activity page and choose Change time: pick the new time in your zone, and the field shows it in UTC too before you save.