> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Flespi

> Connect Flespi IoT telematics to CloudThinker for GPS device management, fleet telemetry, and IoT data analysis

Connect your Flespi account to enable CloudThinker agents to manage GPS devices, monitor telemetry, inspect channels and streams, and operate fleet infrastructure through the Flespi MCP server.

***

## Supported Platforms

| Platform              | Support                               |
| --------------------- | ------------------------------------- |
| **Flespi Free**       | 1,000 AI credits/month                |
| **Flespi Commercial** | 1,000 AI credits/month + paid overage |

***

## Setup

CloudThinker connects to Flespi via their official MCP server using a Flespi API token.

<Steps>
  <Step title="Create a Flespi Account">
    Sign up at [flespi.io](https://flespi.io/#/) if you don't have an account.
  </Step>

  <Step title="Generate an API Token">
    In the flespi panel, navigate to **Tokens** in the left menu and click the **"+"** button:

    * **Name**: `CloudThinker Agent`
    * **Type**: Standard (development) or ACL (production)
    * **TTL**: Set expiration — e.g., `7776000` (90 days). Flespi requires all tokens to have a TTL or expiration date.

    Copy the 64-byte token immediately.
  </Step>

  <Step title="Add Connection in CloudThinker">
    Navigate to **Connections → Flespi** and enter the token you just generated.
  </Step>

  <Step title="Test Connection">
    Click **Test** to verify the connection. The status will show as **Connected**.
  </Step>
</Steps>

<Warning>
  Flespi uses `FlespiToken` — not `Bearer` — as the authorization prefix. CloudThinker handles this automatically, but keep it in mind if debugging API calls manually.
</Warning>

***

## Connection Details

| Field            | Description                 | Example       |
| ---------------- | --------------------------- | ------------- |
| **Flespi Token** | Flespi API token (64 bytes) | `7Bf3...xK9z` |

***

## Token Configuration

### Token Types

| Type         | Access Level                                                                                       | When to Use                  |
| ------------ | -------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Standard** | Full CRUD on all Telematics entities (devices, channels, streams, plugins, geofences, calculators) | Development and testing      |
| **ACL**      | Granular — deny-all by default, grant per module/method/item                                       | **Production recommended**   |
| **Master**   | Full admin including platform APIs                                                                 | **Never use with AI agents** |

### Token Expiration

Flespi **requires** all tokens to expire. Set at least one:

* **`ttl`** — seconds of inactivity before expiration (resets on each API call)
* **`expire`** — Unix timestamp for hard expiration

<Tip>
  For long-running integrations, use `ttl` (e.g., 7776000 = 90 days). The timer resets on every API call, so active tokens won't expire unexpectedly.
</Tip>

### Recommended ACL Permissions (Production)

**Read-only (minimum):**

| Module           | Methods | Purpose                                  |
| ---------------- | ------- | ---------------------------------------- |
| `gw/devices`     | GET     | Device list, status, telemetry, messages |
| `gw/channels`    | GET     | Channel list, configuration, status      |
| `gw/streams`     | GET     | Stream list, health, delivery stats      |
| `gw/calculators` | GET     | Calculator configurations                |
| `ai`             | POST    | Required for MCP tool calls              |

**Read-write (if write operations needed):**

| Module        | Methods                | Purpose                |
| ------------- | ---------------------- | ---------------------- |
| `gw/devices`  | GET, POST, PUT         | Create/update devices  |
| `gw/channels` | GET, POST, PUT         | Create/update channels |
| `gw/streams`  | GET, POST, PUT, DELETE | Full stream management |

<Info>
  ACL tokens deny everything by default. Only explicitly granted permissions are allowed. A token with POST on `gw/devices` will **not** have GET unless also granted.
</Info>

***

## Agent Capabilities

Once connected, agents can:

| Capability             | Description                                                                  |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Device Management**  | List devices, view status, read telemetry and message history                |
| **Channel Monitoring** | Inspect channel configuration, status, and connected protocols               |
| **Stream Health**      | Monitor stream delivery stats and health                                     |
| **Fleet Telemetry**    | Query GPS positions, speed, fuel, and sensor data across devices             |
| **Geofences**          | View and manage geofence zones and triggers                                  |
| **Calculators**        | Inspect calculator configurations for trip detection, fuel consumption, etc. |

### Example Prompts

```bash theme={null}
@alex list all flespi devices and their last known positions
@alex check stream health and identify any delivery failures
@alex query telemetry for device 12345 over the last 24 hours
@alex show all active channels and their connected protocol types
@alex list geofences and check which devices are inside zone "warehouse-01"
```

***

## MCP Tools

### Free Tools (0 credits)

| Tool                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `search-api-methods` | Discover flespi REST API methods by natural language query |
| `get-api-schema`     | Retrieve full Swagger schema for a specific API method     |
| `flespi-api-read`    | Execute a read-only GET request to the flespi REST API     |
| `flespi-api-write`   | Execute a write operation (POST/PUT/PATCH/DELETE)          |

### Paid Tools

| Tool                          | Credits | Description                                                            |
| ----------------------------- | ------- | ---------------------------------------------------------------------- |
| `search-flespi-documentation` | 5       | Search flespi platform documentation                                   |
| `search-device-documentation` | 10      | Search device/protocol manufacturer docs                               |
| `generate-flespi-expression`  | 2       | Generate flespi expressions for selectors, calculators                 |
| `generate-pvm-code`           | 10      | Generate PVM (Protocol Virtual Machine) code                           |
| `consult-flespi-account`      | 30      | Delegate complex analysis to flespi AI expert with account read access |

### AI Credits

| Plan       | Free Credits/Month | Overage                       |
| ---------- | ------------------ | ----------------------------- |
| Free       | 1,000              | Blocked until next month      |
| Commercial | 1,000              | €1 per 100 additional credits |

Monitor usage via the **AI tile** in the flespi panel, the `GET /ai/logs` API, or MQTT topic `flespi/log/ai/#`.

***

## Troubleshooting

<Accordion title="Invalid or expired access token">
  * Token may have expired — check TTL and expiration settings in flespi panel
  * Create a new token and update the connection in CloudThinker
  * Expired tokens are **automatically deleted** by flespi
</Accordion>

<Accordion title="Action is not permitted by ACL">
  * Your ACL token lacks the required module + HTTP method combination
  * Update the token ACL to grant the needed permission
  * Remember: ACL is deny-all by default — each permission must be explicitly granted
</Accordion>

<Accordion title="HTTP 403 on AI tools">
  * Monthly AI credits are exhausted
  * Free plan: wait for next month. Commercial plan: check overage settings
  * Monitor credit usage via `GET /ai/logs` or event code `1710`
</Accordion>

<Accordion title="HTTP 429 rate limit">
  * flespi calculates combined API + MQTT + traffic usage per minute
  * Reduce request frequency or batch operations
  * The highest-usage token gets blocked first; other tokens continue working
</Accordion>

<Accordion title="Using token from unauthorized location">
  * IP whitelist is configured on the token but your server IP is not included
  * Update the token's IP whitelist in flespi panel: **Token settings → IPs whitelist**
</Accordion>

***

## Security Best Practices

* **Dedicated token** — create a separate token for CloudThinker; don't share across integrations
* **ACL for production** — use ACL tokens with minimum required permissions
* **Set TTL** — 90 days recommended; auto-renews on active use
* **Never use Master tokens** — Master tokens have full platform access including billing and subaccounts
* **IP whitelist** — optionally restrict the token to your server IP
* **Rotate regularly** — create new tokens and update connections periodically

***

## References

* [Flespi Token Management](https://flespi.com/kb/tokens-access-keys-to-flespi-platform)
* [Flespi AI Integration Guide](https://flespi.com/kb/flespi-ai-integration)
* [ACL Permissions Guide](https://flespi.com/blog/take-control-of-token-access-permissions-with-flexible-acls)
* [Flespi REST API Docs](https://flespi.io/docs/#/gw/)

***

## Related

<CardGroup cols={2}>
  <Card title="MCP Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/mcp.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c89b6087a9d233901dea5e354452eff6" href="/guide/connections/mcp" width="24" height="24" data-path="images/icons/mcp.svg">
    Custom MCP integrations
  </Card>

  <Card title="Kubernetes Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/kubernetes.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=7c03292954ff635a1994623a5c39971b" href="/guide/connections/kubernetes" width="24" height="24" data-path="images/icons/kubernetes.svg">
    Container orchestration for IoT workloads
  </Card>
</CardGroup>