Calendar / API Documentation
Back to Calendar

Calendar API

The Calendar app proxies requests to the Zesty.io platform APIs. All protected endpoints require an APP_SID cookie set via the authentication flow.

Authentication Required

Endpoints marked with AUTH require a valid APP_SID cookie. Use the OAuth login or POST /api/token to authenticate first.

Authentication

GET /api/auth/:provider/login

Redirects the user to a Zesty.io OAuth provider login page. After authentication, the user is redirected back to /api/auth/callback.

Path Parameters

:provider OAuth provider. One of: google, azure (Microsoft), github

Example

# Opens Google OAuth login (use in browser)
GET /api/auth/google/login

# Or redirect via curl
curl -v https://calendar.zesty.io/api/auth/google/login
GET /api/auth/callback

Handles the OAuth redirect from Zesty. Captures the token or APP_SID query parameter and sets it as an httpOnly cookie. Redirects to / on success.

Query Parameters

token The authentication token returned by Zesty OAuth (or APP_SID)

Example

# This endpoint is called automatically by the OAuth flow
GET /api/auth/callback?token=abc123xyz
POST /api/token

Stores a Zesty.io authentication token as an httpOnly APP_SID cookie. Use this for manual token-based login.

Request Body

{ "token": "your-zesty-auth-token" }

Response

{ "success": true }

Example

curl -X POST https://calendar.zesty.io/api/token \
  -H "Content-Type: application/json" \
  -d '{"token": "your-zesty-auth-token"}' \
  -c cookies.txt
GET /api/auth/check

Checks if the user has a valid APP_SID cookie set.

Response

{ "authenticated": true }

Example

curl https://calendar.zesty.io/api/auth/check -b cookies.txt
DELETE /api/token

Clears the APP_SID cookie, logging the user out.

Response

{ "success": true }

Example

curl -X DELETE https://calendar.zesty.io/api/token -b cookies.txt

Instance Data AUTH

GET /api/instances AUTH

Returns all Zesty.io instances the authenticated user has access to.

Response

{
  "data": [
    {
      "ZUID": "8-abc123-xyz",
      "name": "My Website",
      "domain": "www.example.com",
      ...
    }
  ]
}

Example

curl https://calendar.zesty.io/api/instances -b cookies.txt
GET /api/instances/:zuid AUTH

Returns details for a single Zesty.io instance, including its randomHashID used to build WebEngine preview URLs.

Path Parameters

:zuid The instance ZUID (e.g., 8-abc123-xyz)

Example

curl https://calendar.zesty.io/api/instances/8-abc123-xyz -b cookies.txt
GET /api/instances/:zuid/audit-logs AUTH

Returns audit trail logs (publishes, saves, and other actions) for a specific instance within a date range. Used to populate the calendar with content events.

Path Parameters

:zuid The instance ZUID (e.g., 8-abc123-xyz)

Query Parameters

startDate Start of date range (ISO 8601 format)
endDate End of date range (ISO 8601 format)

Example

curl "https://calendar.zesty.io/api/instances/8-abc123-xyz/audit-logs?\
startDate=2026-03-01&endDate=2026-03-31" \
  -b cookies.txt
GET /api/instances/:zuid/content/:modelZuid/items/:itemZuid AUTH

Retrieves a specific content item by its model and item ZUID. Returns the item's meta data including web.path used to build preview URLs.

Path Parameters

:zuid The instance ZUID
:modelZuid The content model ZUID (e.g., 6-abc123-xyz)
:itemZuid The content item ZUID (e.g., 7-def456-uvw)

Example

curl https://calendar.zesty.io/api/instances/8-abc123-xyz/content/6-model789/items/7-def456-uvw \
  -b cookies.txt
GET /api/instances/:zuid/publishings AUTH

Returns all content item publish records for an instance. Includes both published and scheduled items, used to populate the Publishing tab on the calendar.

Path Parameters

:zuid The instance ZUID

Example

curl https://calendar.zesty.io/api/instances/8-abc123-xyz/publishings \
  -b cookies.txt
GET /api/instances/:zuid/users AUTH

Returns all users associated with an instance. Used to hydrate audit log entries and publish events with human-readable user names.

Path Parameters

:zuid The instance ZUID

Example

curl https://calendar.zesty.io/api/instances/8-abc123-xyz/users \
  -b cookies.txt

Error Handling

All endpoints return errors in a consistent JSON format:

{ "error": "Description of what went wrong" }

Common Status Codes

400 Bad request — missing required parameters
401 Unauthorized — missing or invalid APP_SID cookie
500 Internal server error — upstream Zesty API failure