Catalogs API

When building a map with Waygo, you can add as much of your own Content onto the map as needed, such as exhibitors, sessions, stages, speakers, meeting rooms, and more - each with their own custom parameters. All of these Content objects get stored into Catalogs.

A Catalog is a collection of Content objects of a common type, like an Exhibitors Catalog, Sessions Catalog, or Meeting Rooms Catalog.

By organizing your Content into Catalogs, you can make use of the Attachments API (documentation coming soon) - referencing a Catalog ID to place all of its Content onto a map at once, saving you from having to add each Content onto the map manually.

Additionally, Catalogs have a schema property that ensures each Content type has the necessary fields to match your incoming data, so no modifications to the format of your original data are required.

On this page, we'll explore the Catalog API that let you programmatically manage your Catalogs.

ENDPOINTS

GET /catalogs/v1
POST /catalogs/v1
GET /catalogs/v1/:id
PUT /catalogs/v1/:id
DELETE /catalogs/v1/:id
PUT /catalogs/v1/:id/schema
POST /catalogs/v1/csv
PUT /catalogs/v1/:id/csv
GET /catalogs/v1/:id/csv
GET /catalogs/v1/:id/content

The catalog object

Properties

Name
catalog_id
Type
string
Description
Unique identifier for the catalog.
Name
title
Type
string
Description
The display name of the catalog.
When content is selected on a Waygo map, the catalog's title is displayed directly under the selected content's name, so it is important to choose a title that clearly describes the category of content in the catalog.
As an example, a good name for catalog containing exhibitor content would simply be "Exhibitors".
Name
is_landmark_catalog
Type
bool
Description
A flag that indicates if the content in the catalog should be used as reference points for navigation guidance when placed on maps.
Name
description
Type
string | null
Description
The optional description of the catalog.
Name
data_schema
Type
object
Description
A dictionary defining the schema for content in this catalog. Each key is a field name and each value defines that field's type. This schema determines what fields can be set when creating or updating content in the catalog.
Name
content_title_key
Type
string | null
Description
The key in data_schema that contains the title of the content. Set to 'Title' by default.
Name
content_description_key
Type
string | null
Description
The key in data_schema that contains the description of the content. Set to null by default.
Name
content_display_img_key
Type
string | null
Description
The key in data_schema that contains the display image of the content. Set to null by default.
Name
content_external_id_key
Type
string | null
Description
The key in data_schema that contains the external IDs of the content. Set to null by default.
Name
updated_at
Type
timestamp
Description
Timestamp of when the catalog was last updated.
Name
created_at
Type
timestamp
Description
Timestamp of when the catalog was created.

The catalog object

{
  "catalog_id": "hSIhXBhNe8X1d8Et",
  "title": "Exhibitors",
  "is_landmark_catalog": false,
  "description": "Exhibitors for Comic Con San Diego 2025",
  "data_schema": {
    "external_id": "string",
    "Title": "string",
    "description": "text", 
    "booth_number": "string",
    "website": "url",
    "logo": "image"
  },
  "content_title_key": "Title",
  "content_description_key": "description",
  "content_display_img_key": "logo",
  "content_external_id_key": "external_id",
  "updated_at": 705103200,
  "created_at": 692233200
}

GET/catalogs/v1

List catalogs

This endpoint allows you to retrieve a paginated list of your account's catalogs. By default, a maximum of twenty catalogs are shown per request.

Optional attributes

Name
skip
Type
integer
Description
The number of catalogs to skip
Name
limit
Type
integer
Description
Limit the number of catalogs returned.
Name
sort
Type
list[string]
Description
Sort catalogs by any catalog property. Use property name for ascending order (e.g. 'created_at' for oldest first) or prepend with minus for descending order (e.g. '-created_at' for newest first). String fields are sorted alphabetically.

GET /catalogs/v1

API KEY SCOPE

catalogs:read

curl "https://api.waygomaps.com/catalogs/v1?sort=-created_at&sort=title&skip=20&limit=10" \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"

Response

[
    {
        "catalog_id": "hSIhXBhNe8X1d8Et",
        "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
        "title": "Exhibitors",
        "desciption": "Exhibitors for Comic Con San Diego 2025",
        "data_schema": {
            "external_id": "string",
            "Title": "string",
            "description": "text", 
            "booth_number": "string",
            "website": "url",
            "logo": "image"
        },
        "content_title_key": "Title",
        "content_description_key": "description",
        "content_display_img_key": "logo",
        "content_external_id_key": "external_id",
        "updated_at": 705103200,
        "created_at": 692233200
    },
    {
        "catalog_id": "hSIhXBhNe8X1d8Et",
        // ...
    }, 
    // ...
]

POST/catalogs/v1

Create a catalog

You have the option of either creating a catalog from scratch using this endpoint, or creating a catalog from a CSV file if you have external data you want to add to your maps.

Required attributes

Name
title
Type
string
Description
The title for the catalog.

Optional attributes

Name
catalog_id
Type
string
Description
The ID for the Catalog. Must be unique in the context of the associated account. If not included in the request, a unique Catalog ID will be generated.
Name
description
Type
string
Description
The description of the catalog.
Name
data_schema
Type
object
Description
The schema of the content in the catalog. Initialized as {} if not provided.
Name
is_landmark_catalog
Type
bool
Description
Flag for whether the catalog is a landmark catalog. Defaults to false.
Name
content_title_key
Type
string
Description
The key in data_schema that contains the title of the content. Set to Title by default.
Name
content_description_key
Type
string
Description
The key in data_schema that contains the description of the content. Set to description by default.
Name
content_display_img_key
Type
string
Description
The key in data_schema that contains the display image of the content. Set to logo by default.
Name
content_external_id_key
Type
string
Description
The key in data_schema that contains the external IDs of the content. Set to external_id by default.

POST /catalogs/v1

API KEY SCOPE

catalogs:write

curl https://api.waygomaps.com/catalogs/v1 \
    -X POST \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9" \
    -d '{
      "title": "Exhibitors",
      "description": "Exhibitors for Comic Con San Diego 2025",
      "is_landmark_catalog": false
    }'

Response

{
    "catalog_id": "hSIhXBhNe8X1d8Et",
    "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
    "title": "Exhibitors",
    "desciption": "Exhibitors for Comic Con San Diego 2025",
    "data_schema": {},
    "is_landmark_catalog": false,
    "content_title_key": null,
    "content_description_key": null,
    "content_display_img_key": null,
    "content_external_id_key": null,
    "updated_at": 705103200,
    "created_at": 692233200
}

GET/catalogs/v1/:id

Retrieve a catalog

This endpoint allows you to retrieve a catalog by providing its Catalog ID. Note that this does not return the content in the catalog, only the catalog object itself.

GET /catalogs/v1/:id

API KEY SCOPE

catalogs:read

curl https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"

Response

{
  "catalog_id": "hSIhXBhNe8X1d8Et",
  "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
  "title": "Exhibitors",
  "desciption": "Exhibitors for Comic Con San Diego 2025",
  "data_schema": {
    "external_id": "string",
    "Title": "string",
    "description": "text", 
    "booth_number": "string",
    "website": "url",
    "logo": "image"
  },
  "is_landmark_catalog": false,
  "content_title_key": "Title",
  "content_description_key": "description",
  "content_display_img_key": "logo",
  "content_external_id_key": "external_id",
  "updated_at": 705103200,
  "created_at": 692233200
}

PUT/catalogs/v1/:id

Update a catalog

This endpoint allows you to perform an update on a Catalog. Note that this does not update the content in the catalog, only the Catalog object's data itself.

Only the attributes included in the request will be updated in the Catalog object, ie. whichever attributes are not included in the request will not be changed.

If you want to update the Catalog's schema, you can use the Patch catalog schema endpoint instead.

Optional attributes

Name
catalog_id
Type
string
Description
The ID for the Catalog. Must be unique in the context of the associated account.
Name
title
Type
string
Description
The title of the Catalog. Please not that this is displayed directly under Content's name, when selected on the map, so it is important tochoose a encompassing but descriptive title.
Name
description
Type
string
Description
The description of the Catalog.
Name
is_landmark_catalog
Type
bool
Description
Flag for whether the catalog is a landmark catalog, which defines whether the content in the catalog should be used to guide navigation on the map.
Name
content_title_key
Type
string
Description
The key in data_schema that contains the title of the content.
Name
content_description_key
Type
string
Description
The key in data_schema that contains the description of the content. Set to null by default.
Name
content_display_img_key
Type
string
Description
The key in data_schema that contains the display image of the content. Set to null by default.
Name
content_external_id_key
Type
string
Description
The key in data_schema that contains the external IDs of the content. Set to null by default.

PUT /catalogs/v1/:id

API KEY SCOPE

catalogs:write

curl -X PUT https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n39q9h0ph9324hf9h4vksh9h2f9h03hl" \
  -d title="Exhibitors 2025" \
  -d content_display_img_key="logo" \
  -d content_external_id_key="external_id"

Response

{
  "catalog_id": "exhibitors-comic-con-san-diego-2025",
  "account_id": "n39q9h0ph9324hf9h4vksh9h2f9h03hl",
  "title": "Exhibitors 2025",
  "desciption": "Exhibitors for Comic Con San Diego 2025",
  "data_schema": {
    "external_id": "string",
    "Title": "string",
    "description": "text", 
    "booth_number": "string",
    "website": "url",
    "logo": "image"
  },
  "is_landmark_catalog": false,
  "content_title_key": "Title",
  "content_description_key": null,
  "content_display_img_key": "logo",
  "content_external_id_key": "external_id",
  "updated_at": 720387408,
  "created_at": 692233200
}

DELETE/catalogs/v1/:id

Delete a catalog

This endpoint allows you to delete a catalog from your account, which will also delete all Content objects in the Catalog, as well as any Attachments referencing the Catalog.

Be extremely cautious using this endpoint on any Catalog. You must check to see if any Content in this Catalog has been added to any active map, as deleting its Catalog will make the Content inaccessible on the map.

DELETE /catalogs/v1/:id

API KEY SCOPE

catalogs:delete

curl -X DELETE https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"

PUT/catalogs/v1/:id/schema

Patch catalog schema

This endpoint allows you to perform an update on a Catalog's data_schema using JSON Patch operations. This allows for granular modifications to the schema structure without needing to send the entire schema.

The request body should contain an array of JSON Patch operations. Each operation has the following structure:

{
  "op": "add" | "remove" | "replace",
  "path": "/path/to/property",
  "value": "{text | string | url | image | int | float | boolean | date | datetime | time | email | phone}"
}

PUT /catalogs/v1/:id/schema

API KEY SCOPE

catalogs:write

curl -X PUT https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK/schema \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n39q9h0ph9324hf9h4vksh9h2f9h03hl" \
  -H "Content-Type: application/json" \
  -d '[
  {"op": "add", "path": "/secondary_image", "value": "image"},
  {"op": "remove", "path": "/booth_number"},
  ]'

Response

{
  "catalog_id": "exhibitors-comic-con-san-diego-2025",
  "account_id": "n39q9h0ph9324hf9h4vksh9h2f9h03hl",
  "title": "Exhibitors 2025",
  "desciption": "Exhibitors for Comic Con San Diego 2025",
  "data_schema": {
    "external_id": "string",
    "Title": "string",
    "description": "text", 
    "website": "url",
    "logo": "image",
    "secondary_image": "image"
  },
  "is_landmark_catalog": false,
  "content_title_key": "Title",
  "content_description_key": null,
  "content_display_img_key": "logo",
  "content_external_id_key": "external_id",
  "updated_at": 720387408,
  "created_at": 692233200
}

POST/catalogs/v1/csv

Create a catalog with CSV

You have the option of either creating a catalog from an existing CSV file using this endpoint, or creating a catalog from scratch, depending on your needs. When creating a Catalog from an existing CSV file, the Catalog's data_schema is automatically generated to match the CSV's headers.

Required attributes

Name
file
Type
object
Description
The CSV file to be uploaded. Must use a valid CSV file, and must set the file type to text/csv in the request.

Optional attributes

Name
catalog_id
Type
string
Description
The ID for the Catalog. Must be unique in the context of the associated account. If not included in the request, a unique Catalog ID will be generated.
Name
title
Type
string
Description
The title for the Catalog.
Name
description
Type
string
Description
The description of the Catalog.
Name
is_landmark_catalog
Type
bool
Description
Flag for whether the catalog is a landmark catalog. Defaults to false.

POST /catalogs/v1

API KEY SCOPE

catalogs:write

curl https://api.waygomaps.com/catalogs/v1/csv \
    -X POST \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9" \
    -F file="@exhibitors.csv;type=text/csv" \
    -F title="Exhibitors"

Response

{
    "catalog_id": "hSIhXBhNe8X1d8Et",
    "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
    "title": "Exhibitors",
    "desciption": "",
    "data_schema": {
      "external_id": "string",
      "name": "string",
      "description": "text", 
      "booth_number": "string",
      "website": "url",
      "logo": "image"
    },
    "is_landmark_catalog": false,
    "content_title_key": "name",
    "content_description_key": "description",
    "content_display_img_key": "logo",
    "content_external_id_key": "external_id",
    "updated_at": 692233200,
    "created_at": 692233200
}

PUT/catalogs/v1/:id/csv

Replace catalog contents with CSV

If the Content in a Catalog has changed, and you don't want to manually update each Content object, you can choose to replace the entire Catalog's contents with a new uploaded CSV file. This endpoint will replace the Catalog's contents with the new CSV file, and will also update the Catalog's data_schema to match the CSV's headers.

If a Catalog with the provided Catalog ID does not exist, this endpoint will create a new Catalog with the provided Catalog ID.

If any MapView currently has this Catalog attached (ie. is showing Content from this Catalog), then replacing the Catalog's contents will momentarily break these MapViews until the MapView's tileset has been published to pull the new Content.

Therefore after calling this endpoint, you should immediately call the Publish MapView Tileset endpoint for each MapView that references this Catalog.

Required attributes

Name
file
Type
object
Description
The CSV file to be uploaded. Must use a valid CSV file, and must set the file type to text/csv in the request.
Name
catalog_id
Type
string
Description
The ID for the Catalog. Must be unique in the context of the associated account. If not included in the request, a unique Catalog ID will be generated.

PUT /catalogs/v1/:id/csv

API KEY SCOPE

catalogs:write

curl -X PUT https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK/csv \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9" \
    -F file="@exhibitors-new.csv;type=text/csv"
    -F catalog_id="exhibitors-comic-con-san-diego-2025"

Response

{
    "catalog_id": "hSIhXBhNe8X1d8Et",
    "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
    "title": "Exhibitors",
    "desciption": "",
    "data_schema": {
      "external_id": "string",
      "name": "string",
      "description": "text", 
      "booth_number": "string",
      "website": "url",
      "logo": "image"
    },
    "is_landmark_catalog": false,
    "content_title_key": "name",
    "content_description_key": "description",
    "content_display_img_key": "logo",
    "content_external_id_key": "external_id",
    "updated_at": 692233200,
    "created_at": 692233200
}

GET/catalogs/v1/:id/content

Retrieve all content in catalog

This endpoint allows you to retrieve a list of all the content in a catalog.

GET /catalogs/v1/:id/content

API KEY SCOPE

content:read

curl https://api.waygomaps.com/catalogs/v1/WAz8eIbvDR60rouK/content \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"

Response

[
    {
        "content_id": "cntnt_8fh93h4f983h4f93",
        "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
        "catalog_id": "hSIhXBhNe8X1d8Et",
        "data": {
            "external_id": "string",
            "name": "Marvel Entertainment",
            "description": "Marvel Entertainment, LLC, a wholly-owned subsidiary of The Walt Disney Company, is one of the world's most prominent character-based entertainment companies.", 
            "booth_number": "435",
            "website": "https://www.marvel.com",
            "logo": "https://storage.waygomaps.com/content/marvel_logo.png"
        },
        "created_at": "2021-12-13T00:00:00Z",
        "updated_at": "2022-05-15T00:00:00Z"
    },
    {
        "content_id": "cntnt_93hf93h49f3h49f3",
        // ...
    },
    // ...
]