GTM Schedule API

Export GTM events to calendars, marketing tools, and other systems. Designed for portability — get GTM data to where your team actually works.

Base URL: https://api.vell.ai/api/v1 Authentication: Bearer token (OAuth) or feed token (ICS) Prefix: /gtm-schedule

---

Endpoints

List Events

GET /gtm-schedule/events

Parameter	Type	Required	Default	Description
start_date	date	Yes	—	Start of date range
end_date	date	Yes	—	End of date range (must be >= start_date)
event_types	array	No	—	Filter by event type
channels	array	No	—	Filter by channel
campaign_id	integer	No	—	Filter by campaign
page	integer	No	1	Page number
per_page	integer	No	50	Items per page (max: 100)

Response:

{
  "data": [
    {
      "id": "evt_123",
      "type": "gtm_event",
      "attributes": {
        "title": "Product Launch Webinar",
        "description": "Live demo of new features",
        "scheduled_at": "2026-03-15T14:00:00Z",
        "end_at": "2026-03-15T15:00:00Z",
        "all_day": false,
        "timezone": "America/New_York",
        "event_type": "webinar",
        "event_type_label": "Webinar",
        "channel": "zoom",
        "color": "#4A90D9",
        "icon": "video"
      },
      "links": {
        "self": "/api/v1/gtm-schedule/events/evt_123",
        "ics": "/api/v1/gtm-schedule/events/evt_123/ics"
      }
    }
  ],
  "meta": {
    "total": 24,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  },
  "links": {
    "ics_download": "/api/v1/gtm-schedule/export?format=ics&start_date=...",
    "csv_download": "/api/v1/gtm-schedule/export?format=csv&start_date=..."
  }
}

Get Single Event

GET /gtm-schedule/events/{id}

Download Event as ICS

GET /gtm-schedule/events/{id}/ics

Returns an ICS file (Content-Type: text/calendar) for adding a single event to your calendar.

---

Export Events

GET /gtm-schedule/export

Parameter	Type	Required	Description
format	string	Yes	ics, csv, or json
start_date	date	Yes	Start of date range
end_date	date	Yes	End of date range
event_types	array	No	Filter by event type
channels	array	No	Filter by channel
campaign_id	integer	No	Filter by campaign

ICS format: Downloads a .ics file with all matching events. CSV format: Downloads a .csv file. JSON format: Returns JSON with data and meta fields.

---

Get Available Filters

GET /gtm-schedule/filters

Returns the available filter values for event types and channels.

Response:

{
  "event_types": ["webinar", "blog_post", "email_campaign", "social_post", "product_launch"],
  "channels": ["zoom", "linkedin", "email", "blog", "twitter"]
}

---

Calendar Subscriptions

Subscribe your calendar app (Google Calendar, Outlook, Apple Calendar) to a live ICS feed that auto-updates.

Create Subscription

POST /gtm-schedule/subscription

Parameter	Type	Required	Description
filters	object	No	Persistent filter configuration

Response:

{
  "subscription_url": "https://api.vell.ai/api/v1/gtm-schedule/feed.ics?token=abc123...",
  "token": "abc123...",
  "filters": null,
  "instructions": {
    "google_calendar": "Open Google Calendar > Other calendars > From URL > Paste the subscription URL",
    "outlook": "Open Outlook > Add Calendar > From Internet > Paste the subscription URL",
    "apple_calendar": "Open Calendar > File > New Calendar Subscription > Paste the subscription URL"
  }
}

Regenerate Token

POST /gtm-schedule/subscription/regenerate

Invalidates the old token and generates a new one. Update your calendar subscription with the new URL.

ICS Feed (Public)

GET /gtm-schedule/feed.ics?token=YOUR_FEED_TOKEN

No OAuth required

The ICS feed uses token-based authentication so calendar apps can subscribe without OAuth. The token is unique per user.

Parameter	Type	Required	Default	Description
token	string	Yes	—	64-character feed token
event_types	array	No	From subscription	Override event type filter
lookahead_days	integer	No	90	Days ahead to include (max: 365)

---

Use Cases

Sync GTM Calendar to Google Calendar

1. Create a subscription: POST /gtm-schedule/subscription
2. Copy the subscription_url
3. In Google Calendar: Other calendars > From URL > Paste
4. Events auto-sync as they're added or modified

Export Campaign Timeline to CSV

1. Get available filters: GET /gtm-schedule/filters
2. Export filtered events: GET /gtm-schedule/export?format=csv&start_date=2026-01-01&end_date=2026-12-31&campaign_id=42
3. Import the CSV into your project management tool

Build a Campaign Dashboard

1. Fetch events for the month: GET /gtm-schedule/events?start_date=2026-03-01&end_date=2026-03-31
2. Group by event_type and channel for visual breakdowns
3. Link each event's ics URL for one-click calendar adds