Magpie API Documentation

Introduction

Welcome to the Magpie API documentation. Magpie is a B2B distribution platform for tours, activities, and attractions — connecting operators with resellers like OTAs, DMOs, and travel agents.

This API provides programmatic access to supplier account data, product catalogues, and content on the Magpie platform. It's designed for resellers, booking systems, and integration partners who need to pull structured product and company information.

The API is organised into three sections:

OCTO Core — Industry-standard fields following the OCTO specification. These are the fields any OCTO-compatible system expects: accounts, products, options, and units.

Magpie Extended (MP+) — Additional fields beyond the OCTO standard that provide richer operational detail: guest restrictions, group sizing, difficulty levels, and more.

Content Feed API — Bulk endpoints for retrieving complete datasets in multiple formats (JSON, JSON-LD, Markdown, and others). Ideal for populating catalogues, feeding CMS or AI systems, or syncing data.

For V1 API documentation, visit this page.

Authentication

All OCTO Core and MP+ endpoints require an API key. You can find your key under Profile → Settings in your Magpie dashboard.

Option 1 — Header (recommended)

Include the X-Api-Key header with every request:

HTTP Request

GET /api/accounts/{accountId} HTTP/1.1
Host: magpie.travel
Accept: application/json
X-Api-Key: your_api_key_here

Option 2 — Query Parameter

Alternatively, pass the key as a query parameter:

URL

https://magpie.travel/api?api_key=your_api_key_here

If the API key is missing or invalid, the API returns a 401 Unauthorized response.

Account

The Account resource describes a supplier (operator) on the Magpie platform — their company information, contact details, social profiles, locations, and media.

GET /api/accounts/{accountId}

Example Response

200 OK — application/json

{
  "account": {
    "id": "d7a11efb-da83-4715-b8b3-f2c2ce74f81e",
    "name": "Skyline Sightseeing",
    "telephone": "+1-555-123-4567",
    "website": "https://www.skylinesightseeing.com",
    "description": "Skyline Sightseeing is a renowned sightseeing tour agency...",
    "category": "Tour Operator",
    "secondaryCategory": "Transportation",
    "logo": "https://assets.magpie.travel/accounts/logos/skyline.png",
    "timeZone": "America/Los_Angeles",
    "banner": "https://assets.magpie.travel/accounts/banners/skyline-banner.jpg",
    "email": "[email protected]",
    "locale": "en-US",
    "linkedinHandle": "skylinesightseeing",
    "facebookHandle": "Skyline",
    "instagramHandle": "skysightseeing",
    "xHandle": "skylinetours",
    "youtubeHandle": "skylinechannel",
    "tiktokHandle": "skylinetours",
    "tripadvisorHandle": "skyline-sightseeing",
    "googleHandle": "skylinesightseeing",
    "tradeUrl": "https://trade.skylinesightseeing.com",
    "tradeEmail": "[email protected]",
    "requirements": "Having the tourists, investing in our company...",
    "productDescription": "Travel Guides, Tours, Escorted tours and more",
    "bookingSystemsId": ["TourOpp", "Tripnect"],
    "faqs": [
      {
        "question": "What time do buses start in the morning",
        "answer": "Buses start at 9am and stop at 5pm during the week, and 6pm on weekends."
      },
      {
        "question": "How often do buses run",
        "answer": "Buses run every 15-30 mins."
      },
      {
        "question": "Are tickets to attractions included in the tour",
        "answer": "No, the tour does not include entrance fees to attractions."
      }
    ],
    "media": [
      {
        "src": "https://res.cloudinary.com/example/image/logo.png",
        "type": "image/png",
        "rel": "LOGO",
        "title": "Company Logo",
        "caption": "Official logo of the tour company",
        "copyright": "© 2025 Tour Company"
      }
    ],
    "locations": [
      {
        "title": "99 Jefferson Street, San Francisco, CA 94133, USA",
        "shortDescription": null,
        "type": "BUSINESS_ADDRESS",
        "place": {
          "latitude": 37.807864,
          "longitude": -122.413939,
          "streetAddress": "99 Jefferson Street",
          "addressLocality": "San Francisco",
          "addressRegion": "California",
          "postalCode": "94133",
          "addressCountry": "United States"
        }
      }
    ]
  }
}

Account Fields

Field	Type	Description
`id`	uuid	Unique identifier for the account
`name`	string	Company name
`telephone`	string	Primary contact telephone number
`website`	string	Company website URL
`description`	text	Detailed description of the company
`category`	string	Primary business category
`secondaryCategory`	string	Secondary business category
`logo`	string	URL to company logo image
`banner`	string	URL to company banner image
`timeZone`	string	Company's primary time zone (IANA format)
`email`	string	Primary contact email address
`locale`	string	Default locale (IETF BCP 47 tag)
`linkedinHandle`	string	LinkedIn profile name
`facebookHandle`	string	Facebook profile name
`instagramHandle`	string	Instagram profile name
`xHandle`	string	X (Twitter) profile name
`youtubeHandle`	string	YouTube channel name
`tiktokHandle`	string	TikTok profile name
`tripadvisorHandle`	string	TripAdvisor listing name
`googleHandle`	string	Google Business Profile name
`tradeUrl`	string	URL for trade/B2B portal
`tradeEmail`	string	Contact email for trade partners
`requirements`	string	Requirements to work with this supplier
`productDescription`	string	Summary of products offered
`bookingSystemsId[]`	array	External booking system identifiers
`faqs[]`	array	Frequently asked questions
`faqs[].question`	string	The question text
`faqs[].answer`	string	The answer text
`media[]`	array	Media files (images, video) at stable URLs
`media[].src`	string	Publicly accessible URL of the media file
`media[].type`	string	MIME type (e.g., `image/jpeg`, `video/mp4`, `external/youtube`)
`media[].rel`	string	Relationship to the content: `LOGO`, `COVER`, `GALLERY`
`media[].title`	string/null	Title of the media
`media[].caption`	string/null	Caption providing context
`media[].copyright`	string/null	Copyright or usage restrictions
`locations[]`	array	Geographical locations for the account
`locations[].title`	string/null	Name of the location
`locations[].shortDescription`	string/null	Brief description
`locations[].type`	string	Role of the location (see Location Types)
`locations[].place`	object	Geospatial and postal address data
`locations[].place.latitude`	float	Latitude in decimal degrees
`locations[].place.longitude`	float	Longitude in decimal degrees
`locations[].place.streetAddress`	string/null	Street address
`locations[].place.addressLocality`	string/null	City or locality
`locations[].place.addressRegion`	string/null	State or region
`locations[].place.postalCode`	string/null	Postal or ZIP code
`locations[].place.addressCountry`	string/null	Country

Product

The Product resource describes an experience available for sale — a tour, activity, attraction entry, or package. It includes everything a reseller needs: content (title, descriptions, media), logistics (locations, duration, availability type), commercial terms (pricing, cancellation, restrictions), and delivery details.

Get Single Product

GET /api/products/{productId}

Example Response

200 OK — application/json

{
  "product": {
    "id": "1fb7a9bc-3479-43a3-afe3-a788e508feba",
    "internalName": "Hop-On Hop-Off of San Francisco",
    "reference": "HoHo-SF1",
    "locale": "en",
    "timeZone": "America/Los_Angeles",
    "allowFreesale": false,
    "availabilityRequired": true,
    "instantConfirmation": true,
    "instantDelivery": true,
    "availabilityType": ["OPENING_HOURS", "START_TIME"],
    "deliveryMethods": ["TICKET", "VOUCHER"],
    "deliveryFormats": ["QRCODE", "PDF_URL"],
    "redemptionMethod": ["DIGITAL", "MANIFEST"],
    "title": "San Francisco Bus Tour - 2 Day Hop-On Hop-Off",
    "shortDescription": "Discover San Francisco with our Hop On - Hop Off Bus Tour...",
    "description": "Get ready for an unforgettable journey as our open-top buses...",
    "features": [
      { "type": "INCLUSION", "shortDescription": "2 Day Ticket" },
      { "type": "EXCLUSION", "shortDescription": "Tips & gratuities" },
      { "type": "HIGHLIGHT", "shortDescription": "Explore iconic sights and neighborhoods" },
      { "type": "CANCELLATION_TERM", "shortDescription": "Full refund if cancelled 24hrs before." }
    ],
    "faqs": [
      {
        "question": "What time do buses start?",
        "answer": "Buses start at 9am and stop at 5pm weekdays, 6pm weekends."
      }
    ],
    "media": [
      {
        "src": "https://res.cloudinary.com/example/image/cover.jpg",
        "type": "image/jpeg",
        "rel": "COVER",
        "title": "Tour Cover Image",
        "caption": "San Francisco Bus Tour panoramic view",
        "copyright": "© 2025 Tour Company"
      }
    ],
    "locations": [
      {
        "title": "2800 Leavenworth St, San Francisco, CA 94133",
        "shortDescription": null,
        "type": "START",
        "place": {
          "latitude": 37.807018,
          "longitude": -122.418756,
          "streetAddress": "2800 Leavenworth Street",
          "addressLocality": "San Francisco",
          "addressRegion": "California",
          "postalCode": "94133",
          "addressCountry": "United States"
        }
      }
    ],
    "categoryLabels": ["wheelchair-accessible", "skip-the-line"],
    "durationMinutesFrom": 2880,
    "durationMinutesTo": null,
    "commentary": [
      { "format": "IN_PERSON", "language": "en" },
      { "format": "RECORDED_AUDIO", "language": "es" }
    ],
    "defaultCurrency": "USD",
    "availableCurrencies": [],
    "pricingPer": [],
    "options": [
      {
        "id": "1fb7a9bc-3479-43a3-afe3-a788e508feba",
        "name": "2-Day Pass",
        "description": "Standard 2-day hop-on hop-off pass",
        "units": [
          {
            "id": "adult",
            "type": "ADULT",
            "pricingFrom": [{
              "original": 5999,
              "retail": 5999,
              "net": 4999,
              "currency": "USD",
              "currencyPrecision": 2
            }]
          }
        ]
      }
    ]
  }
}

Get Products List

Retrieve a paginated list of products with support for filtering by product IDs, version type, and version name. This endpoint supports language negotiation via the Accept-Language header.

GET /api/products/getProducts

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 10)
`product_ids`	string	Comma-separated list of product IDs to filter (optional)
`version_type`	string	Filter by version type. Supported values vary by configuration (optional)
`version_name`	string	Filter by version name (optional)

Request Headers

Header	Description
`Accept-Language`	Preferred language (IETF BCP 47 tag). Only one language allowed. Example: `en` or `es`
`X-Api-Key`	Your API key for authentication

Response Headers

Header	Description
`Available-Languages`	Comma-separated list of available languages for the returned products

Example Request

HTTP Request

GET /api/products/getProducts?page=1&per_page=10 HTTP/1.1
Host: magpie.travel
Accept: application/json
Accept-Language: en
X-Api-Key: your_api_key_here

Example Request with Filters

HTTP Request - Filter by Product IDs

GET /api/products/getProducts?product_ids=ID1,ID2,ID3&page=1 HTTP/1.1
Host: magpie.travel
Accept: application/json
Accept-Language: en
X-Api-Key: your_api_key_here

HTTP Request - Filter by Version

GET /api/products/getProducts?version_type=primary&version_name=v2&page=1 HTTP/1.1
Host: magpie.travel
Accept: application/json
Accept-Language: es
X-Api-Key: your_api_key_here

Example Response

200 OK — application/json

{
  "products": [
    {
      "id": "1fb7a9bc-3479-43a3-afe3-a788e508feba",
      "title": "San Francisco Bus Tour - 2 Day Hop-On Hop-Off",
      "locale": "en",
      "shortDescription": "Discover San Francisco...",
      "defaultCurrency": "USD"
      // ... other product fields ...
    },
    {
      "id": "2bc8b1cd-4580-54b4-bge4-b899f619fcfb",
      "title": "Golden Gate Bridge Walking Tour",
      "locale": "en",
      "shortDescription": "Guided walk across the iconic bridge...",
      "defaultCurrency": "USD"
      // ... other product fields ...
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 5,
    "total_count": 47,
    "next_page": 2,
    "prev_page": null
  }
}

Language Negotiation
If a product is not available in the requested language, the API will return the product in the default language (typically English). Check the locale field in each product to see which language was returned.

Error Responses

Status Code	Error	Description
`400`	Bad Request	Multiple languages in `Accept-Language` header or invalid `version_type`
`404`	Not Found	No products found with the specified `version_name`
`401`	Unauthorized	Missing or invalid API key

400 Bad Request — Multiple Languages

{
  "error": "Only one language is allowed in Accept-Language header"
}

400 Bad Request — Invalid Version Type

{
  "error": "Invalid version_type"
}

404 Not Found — Version Name

{
  "error": "No products found with version_name: 'v3'"
}

Product Fields

Field	Type	Description
`id`	string	Unique product identifier in Magpie
`internalName`	string	The supplier's internal name for this product
`reference`	string/null	Optional supplier reference code
`locale`	string	Content language (IETF BCP 47 tag)
`timeZone`	string	Product time zone (IANA identifier)
`allowFreesale`	boolean	Whether bookings can be made without querying availability first
`availabilityRequired`	boolean	Whether an `availabilityId` is required when creating a booking
`instantConfirmation`	boolean	Whether bookings are confirmed immediately
`instantDelivery`	boolean	Whether tickets are delivered immediately upon confirmation
`availabilityType[]`	array	`START_TIME` (fixed departures) or `OPENING_HOURS` (visit anytime during operating hours)
`deliveryMethods[]`	array	`TICKET` (per unit) or `VOUCHER` (per booking)
`deliveryFormats[]`	array	Ticket formats: `QRCODE`, `CODE128`, `AZTECCODE`, `PDF_URL`, `PKPASS_URL`
`redemptionMethod[]`	array	`MANIFEST` (name on list), `DIGITAL` (scan on mobile), `PRINT` (physical printout)
`title`	string	Customer-facing product name
`shortDescription`	string/null	Brief customer-facing description
`description`	string/null	Detailed product description
`features[]`	array	Array of feature objects (see Feature Types)
`features[].type`	string	Feature type enum value
`features[].shortDescription`	string/null	Description of the feature
`faqs[]`	array	Product-specific frequently asked questions
`faqs[].question`	string	The question text
`faqs[].answer`	string	The answer text
`media[]`	array	Media files at stable URLs
`media[].src`	string	Publicly accessible media URL
`media[].type`	string	MIME type of the media file
`media[].rel`	string	`LOGO`, `COVER`, or `GALLERY`
`media[].title`	string/null	Title of the media
`media[].caption`	string/null	Caption providing context
`media[].copyright`	string/null	Copyright or usage restrictions
`locations[]`	array	Locations associated with the product
`locations[].title`	string/null	Location name
`locations[].shortDescription`	string/null	Brief description
`locations[].type`	string	Role of the location (see Location Types)
`locations[].place`	object	Geospatial and postal address data
`categoryLabels[]`	array	Category labels (see Category Labels)
`durationMinutesFrom`	integer	Minimum duration in minutes
`durationMinutesTo`	integer/null	Maximum duration if flexible; `null` if fixed
`commentary[]`	array	Commentary/guide options available
`commentary[].format`	string	`IN_PERSON`, `RECORDED_AUDIO`, `WRITTEN`, or `OTHER`
`commentary[].language`	string	Language code (IETF BCP 47)
`defaultCurrency`	string	Default currency (ISO 4217)
`availableCurrencies[]`	array	Supported currencies (ISO 4217)
`pricingPer[]`	array	`UNIT` or `BOOKING`
`options[]`	array	Product variations (see Options)

Options

Options represent variations of a product — for example, a "1-Day Pass" vs a "2-Day Pass", or "Morning Tour" vs "Sunset Tour". Every product has at least one option.

Option Fields

Field	Type	Description
`id`	string	Unique identifier for this option
`name`	string	Customer-facing name (e.g., "2-Day Package")
`reference`	string/null	Optional supplier reference code
`description`	string/null	Detailed description of this option
`units[]`	array	Pricing categories within this option (see Units)

Units

Units represent pricing categories within an option — such as Adult, Child, or Senior. Each unit has its own pricing.

Pricing note Prices are expressed in the smallest currency unit (e.g., cents for USD). A value of 5999 with currencyPrecision: 2 means $59.99.

Unit Fields

Field	Type	Description
`id`	string	Unique identifier for this unit
`type`	string	Unit type (see Unit Types below)
`option_id`	string	ID of the parent option
`pricingFrom[]`	array	Pricing information
`pricingFrom[].original`	integer	Original price in smallest currency unit
`pricingFrom[].retail`	integer	Customer-facing retail price
`pricingFrom[].net`	integer/null	Net price (before markup), or `null`
`pricingFrom[].currency`	string	ISO 4217 currency code
`pricingFrom[].currencyPrecision`	integer	Decimal places for the currency (e.g., 2 for USD)

Unit Types

Value	Description
`ADULT`	Standard adult pricing
`CHILD`	Younger participants, usually with age restrictions
`YOUTH`	Adolescents/teenagers, between child and adult
`SENIOR`	Older participants, typically with age minimums
`STUDENT`	Valid student identification required
`FAMILY`	Package for a defined group (e.g., 2 adults + 2 children)
`INFANT`	Very young participants (usually under 2–3 years), often free
`GROUP`	Block pricing for a specified number of participants
`MILITARY`	Active or retired military with valid ID
`RESIDENT`	Local residents with proof of residency

Feature Types

Each product can have multiple features that describe what's included, what's excluded, key highlights, and important terms. Each feature has a type and a shortDescription.

Type	Description	Examples
`INCLUSION`	What is included in the experience	"Hotel pickup included", "Lunch provided"
`EXCLUSION`	What is NOT included	"Gratuities not included", "Admission tickets separate"
`HIGHLIGHT`	Key selling points or unique aspects	"Skip-the-line access", "Small-group expert-guided tour"
`PREBOOKING_INFORMATION`	Critical info customers must know before booking	"Minimum age 12", "Moderate fitness level required"
`PREARRIVAL_INFORMATION`	Instructions and tips before arrival	"Bring photo ID", "Wear warm clothing"
`REDEMPTION_INSTRUCTION`	How to redeem the booking	"Present mobile voucher at entrance", "Check-in at kiosk"
`ACCESSIBILITY_INFORMATION`	Accessibility features or limitations	"Wheelchair accessible", "Not suitable for mobility impairments"
`BOOKING_TERM`	Terms related to booking and payment	"Full payment at booking", "Confirmation within 24 hours"
`CANCELLATION_TERM`	Cancellation and refund policies	"Full refund if cancelled 72hrs before", "No refunds within 24hrs"
`RESTRICTIONS`	Conditions or limitations guests must adhere to	"Max weight 250 lbs", "No pets", "No alcohol before activity"
`REQUIREMENTS`	Mandatory conditions or documentation	"Valid driver's license", "Signed waiver needed"
`ADDITIONAL_INFORMATION`	Supplementary details	"Bring sunscreen", "Weather may affect itinerary"

Location Types

Value	Description
`START`	Starting point or meeting location where customers gather before the activity
`END`	Final point or drop-off location where the activity concludes
`BUSINESS_ADDRESS`	Official business address of the service provider
`GOOGLE_BUSINESS_PROFILE`	Location from the provider's Google Business Profile
`REDEMPTION`	Location where customers exchange tickets or collect passes before the experience
`POINT_OF_INTEREST`	Notable location customers may see or pass by (used for sightseeing)

Category Labels

Value	Description
`private-tours`	Exclusive tours with no other participants
`multi-day`	Products spanning multiple days, typically with accommodation
`wheelchair-accessible`	Accessible for wheelchair users
`accommodation-included`	Lodging included in the package
`food-included`	Meals included during the experience
`drinks-included`	Beverages included during the experience
`skip-the-line`	Priority access or expedited entry

Magpie Extended (MP+)

MP+ fields provide additional operational and logistical detail beyond the OCTO standard. They help resellers create richer product listings and set accurate customer expectations around group sizes, difficulty levels, guest restrictions, and more.

Where do MP+ fields appear? These fields are returned as part of the Product response body, alongside the OCTO Core fields documented above. They are not a separate endpoint — when you call GET /api/products/{productId}, both OCTO and MP+ fields are included in the response.

MP+ endpoints use the same API key authentication as OCTO Core.

Extended Fields

Booking & Confirmation

Field	Type	Description
`confirmationNecessary`	boolean	Customer is required to confirm before travel
`startDate`	date	Date when the product starts operating
`endDate`	date	Date when the product stops operating
`redemptionType`	string	How tickets are redeemed: held at office, or voucher scanned/collected

Group & Capacity

Field	Type	Description
`bookingMinPax`	integer	Minimum guests per booking
`bookingMaxPax`	integer	Maximum guests per booking
`maxGroupSize`	integer	Maximum group size on the product

Activity Details

Field	Type	Description
`category`	string	Product category (e.g., "Tours & Sightseeing")
`guideType`	string	Tour Guide, Host, Greeter, Instructor, or Driver
`tripDifficulty`	string	Easy, Moderate, or Challenging
`emergencyPhone`	string	Emergency phone number for guests

Guest Restrictions

Field	Type	Description
`ageRestrictionType`	string	Type of age restriction (e.g., MinAge)
`ageRestrictionValue`	integer	Age value in years
`heightRestrictionType`	string	Minimum or Maximum height restriction
`heightRestrictionValue`	integer	Height restriction value
`heightRestrictionUnit`	string	`cm` or `inches`
`weightRestrictionType`	string	Minimum or Maximum weight restriction
`weightRestrictionValue`	integer	Weight restriction value
`weightRestrictionUnit`	string	`Kg` or `Lbs`

Guest Requirements

Field	Type	Description
`dressCode`	string	Dress code requirements for guests
`foodIncluded`	string	Description of food included in the product
`drinksIncluded`	string	Description of drinks included in the product

MP+ Example (within a Product response)

MP+ fields within a Product response

{
  "product": {
    "id": "1fb7a9bc-3479-43a3-afe3-a788e508feba",
    "title": "San Francisco Bus Tour",

    // ... OCTO Core fields ...

    "confirmationNecessary": false,
    "category": "Tours & Sightseeing",
    "redemptionType": "voucher",
    "guideType": "Instructor",
    "tripDifficulty": "Easy",
    "emergencyPhone": "+1-555-911-0000",
    "bookingMinPax": 1,
    "bookingMaxPax": 15,
    "maxGroupSize": 15,
    "ageRestrictionType": "MinAge",
    "ageRestrictionValue": 12,
    "dressCode": "Comfortable shoes and clothes",
    "foodIncluded": "Snacks available for purchase. Breakfast included.",
    "drinksIncluded": "Soft drinks or tea. Alcoholic drinks available for purchase."
  }
}

Content Feed API

The Content Feed API provides optimised endpoints for retrieving complete account and product data in bulk. Instead of fetching individual resources one by one, you can retrieve multiple accounts or products in a single request, in your preferred format.

This is ideal for populating or syncing a product catalogue, feeding data into a CMS, search index, or AI system, generating documentation or reports, and bulk data exports for analytics.

Authentication

The Content Feed API currently uses the same API key as OCTO Core and MP+ endpoints, provided via the X-Api-Key header.

Note Authentication for the Content Feed API may move to a separate key in the future. Check this section for updates.

Get Accounts

Retrieve complete account data for one or more suppliers in a single request.

GET /api/content-feed/accounts

Query Parameters

Parameter	Default	Description
`account_ids`	optional	Comma-separated account IDs
`format`	`json`	Export format (see Supported Formats)
`content_type`	`company_info`	`company_info` for basic data, `all` for full data including products and reviews
`page`	`1`	Page number for pagination
`per_page`	`50`	Items per page (max: 100)

Example Requests

Get company info (JSON)

GET /api/content-feed/accounts?content_type=company_info&account_ids=ID1,ID2
Host: magpie.travel
X-Api-Key: your_api_key_here

Get all data (JSON-LD format)

GET /api/content-feed/accounts?content_type=all&format=jsonld&account_ids=ID1
Host: magpie.travel
X-Api-Key: your_api_key_here

Get account data (Markdown)

GET /api/content-feed/accounts?content_type=company_info&format=markdown&account_ids=ID1
Host: magpie.travel
X-Api-Key: your_api_key_here

Example Response (JSON)

200 OK — application/json

{
  "accounts": [
    {
      "id": "YOUR_ACCOUNT_ID",
      "name": "Account Name",
      "telephone": "+33 1 23 45 67 89",
      "website": "https://ophorus.com",
      "description": "Premium tour operator in France",
      "category": "Operator",
      "email": "[email protected]",
      "locale": "en",
      "timeZone": "Europe/Paris",
      "logo": "https://example.com/logo.png",
      "reviewRating": "4.8",
      "reviewCount": 245,
      "bookingSystemsId": ["Ventrata", "Viator"],
      "media": [],
      "locations": [],
      "products": [],
      "faqs": [],
      "reviews": []
    }
  ],
  "paginate": {
    "total_accounts": 1250,
    "total_pages": 25,
    "per_page": 50,
    "from": 1,
    "to": 50,
    "current_page_url": "/api/content-feed/accounts?page=1",
    "next_page_url": "/api/content-feed/accounts?page=2",
    "prev_page_url": ""
  },
  "count": 50
}

Example Response (Markdown)

200 OK — application/json

{
  "format": "markdown",
  "content": "# Account: Ophorus Tours in France\n\n## Company Information\n...",
  "count": 1
}

Get Products

Retrieve complete product data for one or more products in a single request.

GET /api/content-feed/products

Query Parameters

Parameter	Default	Description
`product_ids`	optional	Comma-separated product IDs
`version_type`	`Primary`	Filter by version type (e.g., Primary, Language, Website,..)
`version_name`	none	Filter by specific version name
`format`	`json`	Export format (see Supported Formats)
`page`	`1`	Page number for pagination
`per_page`	`20`	Items per page (max: 100)

Example Request

Get multiple products (JSON)

GET /api/content-feed/products?product_ids=ID1,ID2
Host: magpie.travel
X-Api-Key: your_api_key_here

Example Response

200 OK — application/json

{
  "accounts": [
    {
      "id": "YOUR_ACCOUNT_ID",
      "name": "Adventure Tours Co",
      "username": "adventure-tours-co",
      "website": "https://adventuretours.com",
      "products": [
        {
          "id": "YOUR_PRODUCT_ID",
          "title": "Alsace Christmas Markets Private Tour",
          "shortDescription": "Visit Christmas markets in beautiful Alsatian villages",
          "category": "Tours & Sightseeing",
          "duration": "7 hours",
          "currency": "EUR",
          "media": []
        }
      ]
    }
  ],
  "count": 1,
  "paginate": {
    "total_products": 15420,
    "total_pages": 772,
    "current_page": 1,
    "per_page": 20,
    "actual_count": 1,
    "next_page": 2,
    "prev_page": null
  }
}

Note on response structure Products are returned nested inside an accounts array, grouped by the account they belong to. When processing the response, iterate through accounts[].products[] to access individual products.

Supported Formats

Both endpoints accept a format parameter. The response Content-Type is always application/json — for non-JSON formats, the formatted content is returned inside a content string field.

Format	Description	Best for
`json`	Standard JSON	Web APIs, general integration
`jsonl`	Newline-delimited JSON	Streaming, bulk processing, LLM ingestion
`jsonld`	Schema.org JSON-LD	SEO, structured data, semantic web
`json-octo`	OCTO Core specification format	Tourism industry systems (Accounts only)
`markdown`	Human-readable Markdown	Documentation, reports, AI context
`text`	Plain text	Email, simple text systems

Format availability The json-octo format is currently only available for the Accounts endpoint.

Caching

The Content Feed API uses intelligent caching to deliver faster responses. Responses are cached for up to 60 minutes and automatically invalidate when data is modified through the Magpie dashboard or API. If a cache refresh fails, stale data (up to 24 hours old) is served to ensure availability.

Error Handling

Code	Response	Cause
`400`	`{"error": "No account IDs provided"}`	Missing required ID parameter
`400`	`{"error": "Invalid format..."}`	Unsupported `format` value
`400`	`{"error": "Invalid content_type..."}`	Unsupported `content_type` (accounts only)
`401`	Unauthorized	Missing or invalid API key
`404`	`{"error": "No accounts found"}`	No matching records for the given IDs
`500`	Server error	Internal error — retry with exponential backoff