Preferences

Preferences are settings for the whole workspace. There are two:

Read them

curl https://api.reelspan.com/v1/preferences \
  -H "Authorization: Bearer $REELSPAN_API_KEY"

import { Reelspan } from 'reelspan';

const reelspan = new Reelspan();
const { preferences } = await reelspan.request('GET', '/v1/preferences');

from reelspan import Reelspan

reelspan = Reelspan()
preferences = reelspan.request("GET", "/v1/preferences")["preferences"]

{ "success": true, "preferences": { "weekStartDay": 1, "timezone": null } }

Any key can read them, whatever its scopes. GET /v1/me returns the same preferences.

Change them

Send only what changes. The answer has all the preferences as saved:

curl -X POST https://api.reelspan.com/v1/preferences \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/New_York"}'

await reelspan.request('POST', '/v1/preferences', { json: { timezone: 'America/New_York' } });

reelspan.request("POST", "/v1/preferences", json_body={"timezone": "America/New_York"})

{ "success": true, "preferences": { "weekStartDay": 1, "timezone": "America/New_York" } }

Send "timezone": null to go back to UTC. An unknown zone gets 400 INVALID_REQUEST, and a weekStartDay other than 0 or 1 gets 400. Changing preferences needs a key with the profiles scope.

The default time zone

With a timezone preference, a post that sends scheduled_date without its own timezone is scheduled in the workspace's zone. With the preference above, this post goes out at 9:00 in New York:

curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "title=Launch day" \
  -F "scheduled_date=2026-12-01T09:00:00" \
  -F "[email protected]"

• A timezone sent with the post always wins.
• A scheduled_date with its own offset (2026-12-01T09:00:00-05:00 or …Z) is that exact moment, whatever the zones say.
• Only new posts use the preference. Rescheduling a post with PATCH /v1/scheduled/{job_id} keeps the zone it was scheduled in, and a retry later without timezone uses UTC.

See Scheduling and repeats for the rest of scheduling.