# Navigating maps and workspaces

## Workspaces and API tokens

Workspaces are the place where users in the same organization collaborate and share maps. A user may form part of several workspaces but, at the very least, always forms part of one.

API tokens are created per-workspace. If you wish to interact with several workspaces via the Felt API, you must create a different API token for each one.

## Working with maps

### Creating a new map

Creating a new map is as simple as making a `POST` request to the maps endpoint.

{% tabs %}
{% tab title="curl" %}

```bash
# Your API token should look like this:
# FELT_API_TOKEN="felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
FELT_API_TOKEN="<YOUR_API_TOKEN>"

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps" \
  -d '{"title": "My newly created map"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

# Your API token should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"

r = requests.post(
  "http://felt.com/api/v2/maps",
  json={"title": "My newly created map"},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
map_id = r.json()["id"]

print(r.json())
```

{% endtab %}

{% tab title="felt-python" %}

```python
import os

from felt_python import create_map

# Setting your API token as an env variable can save
# you from repeating it in every function call
os.environ["FELT_API_TOKEN"] = "<YOUR_API_TOKEN>"

response = create_map(
    title="My newly created map",
    lat=40,
    lon=-3,
    public_access="private",
)
map_id = response["id"]
```

{% endtab %}
{% endtabs %}

Notice in the response the `"id"` property. Every map has a unique ID, which is also a part of the map's URL. Let's take note of it for future API calls.

Also part of the response is a `"url"` property, which is the URL to your newly-created map.

### Getting a map's details

Performing a `GET` request to a map URL will give you useful information about that map, including title, URL, layers, thumbnail URL, creation and visited timestamps.

{% tabs %}
{% tab title="curl" %}

```bash
curl -L \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}"
```

{% endtab %}

{% tab title="Python" %}

```python
r = requests.get(
  f"http://felt.com/api/v2/maps/{map_id}",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())
```

{% endtab %}

{% tab title="felt-python" %}

```python
from felt_python import get_map

get_map(map_id)
```

{% endtab %}
{% endtabs %}

### Deleting a map

To remove a map from your workspace, simply perform a `DELETE` request to the map's URL:

{% tabs %}
{% tab title="curl" %}

```bash
curl -L \
  -X DELETE \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}"
```

{% endtab %}

{% tab title="Python" %}

```python
r = requests.delete(
  f"http://felt.com/api/v2/maps/{map_id}",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
```

{% endtab %}

{% tab title="felt-python" %}

```python
from felt_python import delete_map

delete_map(map_id)
```

{% endtab %}
{% endtabs %}

### Moving a map

To move a map to a different folder or project, send a POST request to the map's move URL:

{% tabs %}
{% tab title="curl" %}

```bash
curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/move" \
  -d '{"project_id": "${PROJECT_ID}"}'
```

{% endtab %}

{% tab title="Python" %}

```python
r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/move",
  json={"project_id": project_id},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())
```

{% endtab %}

{% tab title="felt-python" %}

```python
from felt_python import move_map

move_map(map_id, project_id)
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.felt.com/rest-api/navigating-maps-and-workspaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.