How to connect a REST API

In TeleportHQ you can show data from any web service that returns JSON by connecting it as a REST API data source. Open Data Sources → Add Data Source → REST API, enter the URL, add headers or authorization if the API needs them, click Fetch data from API to check the response, and click Save Data Source. You can also cache the API's answers on your published site, or ask the AI Assistant to connect a public API for you.

Before you start#

• You need the API's address (its URL), for example https://api.example.com/events.
• If the API needs a key or login, have it ready. TeleportHQ stores what you type in the Authorization tab as a project Secret when you save.
• The API must return JSON. A list of items (an array) works best for lists and details pages.
• You can add as many REST APIs to a project as you need. Connecting one doesn't turn a TeleportHQ website into a web app.

Steps#

1. In the left sidebar, click Data Sources (the database icon).
2. In the Data Sources panel, click + (tooltip Add Data Source).
3. Click the REST API card. A panel titled REST API opens with the section Setup REST API Connection.
4. In Data Source Name, type a name, for example Upcoming events. Use letters, numbers, spaces and underscores. Leave it empty to get an automatic name.
5. In HTTP Method, keep GET to read data. Choose POST, PUT, PATCH or DELETE only if the API documentation asks for it.
6. In URL, paste the API address, for example https://api.example.com/events. If you leave out https://, TeleportHQ adds it.
7. Add headers, parameters, a body or authorization if the API needs them (see the next sections).
8. Click Fetch data from API.

9. The View Data section shows the response. When it looks right, click Save Data Source below it. If this is the project's first data source, a window titled IMPORTANT appears; click I understand.

Add headers, parameters or a body to a REST API request#

Below the URL, the TeleportHQ REST API form has tabs:

• Headers: click Add Header, then type a key and value, for example Accept and application/json.
• Parameters (for GET and DELETE): click Add Parameter to add a query parameter, for example limit and 20. It is added to the URL as ?limit=20.
• Body (for POST, PUT and PATCH, in place of Parameters): choose a Body Type (json, raw or x-www-form-urlencoded) and type the body.

Rows with an empty key or an empty value are left out when you fetch and save.

Add authorization to a REST API request#

If the API needs a login, open the Authorization tab in the TeleportHQ REST API form and choose an Authorization Type:

• No Auth: the API is public.
• API Key: paste your key in API Key. TeleportHQ sends it in an X-API-Key header, in the editor and on your published site.
• Bearer Token: paste your token in Token. TeleportHQ sends it as Authorization: Bearer <token>.
• Basic Auth: fill in Username and Password.

Each field has a plug button (tooltip Link to project secret) to use a value you already saved as a project Secret instead of typing it.

The API Key type always sends the key in an X-API-Key header. When the API's documentation names another header for the key, such as api-key, add that header in Headers instead, with your key as its value.

Cache the API's answers on your published site#

TeleportHQ can keep a copy of a REST API's answer on your published site, so the site doesn't call the API for every visitor. Use it for an API with a rate limit or a slow answer, for example a weather feed.

1. In the TeleportHQ REST API panel, find the Caching section below the setup.
2. Turn on Cache API responses.
3. In Cache for, choose how long a copy is used: 30 seconds, 1 minute, 5 minutes (the default), 15 minutes, 1 hour, 6 hours or 24 hours.
4. For another duration, choose Custom… and type it in Duration (seconds), between 5 seconds and 24 hours.
5. Click Save Data Source.

The panel explains it: "The published site calls this API at most once per duration and answers every request in between from the cached response. Changes made in the API show up once the duration runs out." Caching applies to your published site. On a saved REST API, changing the caching settings shows Save Data Source without a new fetch.

Let the AI Assistant connect a public API#

The TeleportHQ AI Assistant can add a REST API data source for you when the API is public. Ask it, for example: "connect https://api.example.com/events as a data source". It calls the URL once to test it, saves the data source and tells you where the lists are in the answer, so it can show them on a page next.

• No keys in chat. The AI Assistant refuses a URL, header or parameter that looks like a key, token or password, and saves nothing. Add those APIs yourself in the Data Sources panel, where the key is stored as a Secret.
• No duplicates. If the project already has a REST API with the same URL, the AI Assistant uses that one.

See What can the TeleportHQ AI Assistant do?.

Check that it worked#

The View Data section shows "N items • M properties" and a preview of the first rows. Switch between Table and Raw to see the data as a table or as JSON, or click View Data to see all rows. After saving, the REST API appears as a card in the Data Sources panel. Next, show the items in a list.

Troubleshooting#

"Connection failed" The API returned an error or couldn't be reached. Read the details under the message. Check the URL, method and authorization, and try the same request in the API's documentation or test tool.

"Please enter a valid URL" The URL has a typo or a space. Paste the full address again.

"Name must be at least 3 characters" or "Name can only contain letters, numbers, underscores and spaces" Change the Data Source Name, for example to Upcoming events.

The preview shows one item instead of a list The API wraps the list inside another field, for example { "results": [ … ] }. That works: when you bind a list (Array Mapper) to this data source, pick the inner field, results, as its source. Your published site then pages through that inner list the same way.

The API answers in the editor, but not on my published site If the source uses the API Key type, publish your site again. Older publishes send the key as Authorization: ApiKey …, while the editor sends X-API-Key; a new publish sends it the way the editor does.

My published site shows old data from the API Cache API responses is on, so the site reuses its copy until Cache for runs out. Choose a shorter duration, save and publish, or turn caching off.

Good to know#

• Keys and passwords become Secrets. When you save, TeleportHQ moves what you typed in the Authorization tab into project Secrets named like DATA_SOURCE_UPCOMING_EVENTS_TOKEN. Values typed in Headers are not moved. See Keep passwords and API keys safe.
• Data is fetched again when you open the data source, so you always see the current response. To change a saved REST API, change the field, click Fetch data from API, then Save Data Source.
• A REST API that returns a list can power details pages, one page per item. See Create a page for each item.
• List caching (on the list itself) can't be cleared automatically for a REST API. Cached lists update only when their cache time runs out.