FAQ

Setup and basics

Q: Can I use the same Integration for multiple projects?

Yes, a single Integration can be connected to multiple projects. However, you need to set up the connection for each project separately.

Q: What’s the difference between an integration token and an API key?

An integration token is used with Integration API (read, write and management operations). An API key is used with Public API to access a private project. They serve different purposes, so use whichever fits your situation.

Q: What’s the base URL for the API?

API	Base URL
Integration API	https://api.cms.reearth.io/api/{workspace}/projects/{project}/
Public API	https://api.cms.reearth.io/api/p/{workspace}/{project}/

Working with items

Q: I created an item, but I can’t retrieve it via Public API. Why?

Items created via Integration API are Draft by default. To make one retrievable via Public API, you need to publish it using the endpoint below. See Publishing data with Integration API for details.

POST /{workspace}/projects/{project}/models/{model}/items/{itemId}/publish

Q: Where can I check a field’s key?

Opening a model’s schema settings in the Re:Earth CMS management console shows each field’s key. You can also retrieve the schema from the following endpoint.

GET /{workspace}/projects/{project}/models/{model}/schema.json

Q: What’s the maximum number of items I can retrieve at once?

Up to 100 items per request. Use the perPage parameter to set the count (default: 50). If you need more than 100 items, use the page parameter to paginate through them.

Q: Can I filter items by specific conditions?

With Integration API, you can use the POST /items/filter endpoint to apply condition filters. It supports a variety of condition types — text, number, date/time, status, and more — and multiple conditions can be combined with and / or. Public API has no filtering feature; use Integration API if you need to narrow down results. See Filtering items with Integration API for details.

Public API

Q: When can I access data without authentication?

If a project is set to public, you can access Public API without authentication. For a private project, you can gain access by attaching an API key to the Authorization header.

Q: I retrieved GeoJSON, but features is empty.

features will be empty if the model doesn’t have a GeoJSON Geometry field defined. Check the model’s schema settings in the CMS management console to confirm a geometry field has been added.

Webhook

Q: I set up a Webhook, but notifications aren’t arriving. What do I need to check?

Check the following.

1. Is the Webhook URL set correctly?
2. Does the URL start with http:// or https://?
3. Is the receiving server accepting POST requests?
4. Does the receiving server return a 2XX response within 10 seconds?
5. Is the target event enabled in the Webhook’s settings?

If you’re testing in a local environment, use a tunneling tool such as ngrok to prepare a URL that’s accessible from the outside.

Q: Where can I check a Webhook’s payload?

For testing purposes, issuing a temporary URL at webhook.site lets you check received payloads in real time in your browser.

Caution

The free tier of webhook.site deletes data after 7 days, and request contents can be viewed by other users. We recommend against using it in production.

Troubleshooting errors

Q: I get a 401 Unauthorized response.

Check that the Authorization header is set correctly.

Authorization: Bearer <your_integration_token>

A space is required between Bearer and the token. If the error persists even though the token is correct, try regenerating the token.

Q: I get a 400 Bad Request response.

This is returned when the request body’s structure is invalid. Check the following.

• Does each field’s key in fields match the field key on the CMS side?
• Does each field’s type in fields match the field’s type?
• Is the JSON syntax correct (commas, quotes, nesting)?

Q: I get a 404 Not Found response.

Check that the workspace / project / model ID or alias in the URL is correct. Also, for Public API, check that the model is set to public.