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

# Aspire (Landscape FSM)

> Connect Aspire to your Agents for read-only access to your landscape & field service data

## Overview

The [Aspire](https://youraspire.com) integration gives your agents **read-only** access to your Aspire field-service-management tenant. Agents can query Properties, Opportunities, Work Tickets, Invoices, Contacts, Companies, Routes, Services, and the rest of Aspire's data via OData filters — to answer operational questions, reconcile records, and feed analysis, without ever modifying anything in Aspire.

The integration is read-only by design for the initial release: the underlying client only exposes `GET`, so agents cannot create, update, or delete Aspire records.

<Note>
  This is **Aspire by youraspire.com** (landscape & field service management) — not Microsoft .NET Aspire and not the Aspire fintech product.
</Note>

## Prerequisites

* An **Aspire** account with API access
* An Aspire **Client ID** and **Secret**, generated under **Account Settings > API Keys** in Aspire
* An Aster **admin** to connect the integration (the connection is shared org-wide)

## Setup Guide

<Steps>
  <Step title="Generate API credentials in Aspire">
    In Aspire, go to **Account Settings > API Keys** and create a key. Copy the **Client ID** and **Secret**.
  </Step>

  <Step title="Connect Aspire in Aster Agents">
    Navigate to **Control Hub > Integrations**, locate the **Aspire** card, click **Connect**, and paste the Client ID and Secret. Aster validates them against Aspire (token exchange + a tenant lookup) and echoes back your tenant's legal name on success. Aster handles token exchange and refresh from there.
  </Step>

  <Step title="Add Tools to Your Agent">
    Edit your agent and enable **Aspire Get Schema** and **Aspire Query**. The agent discovers the available collections and fields at runtime, then queries them.
  </Step>
</Steps>

## Available Tools

* **Aspire Get Schema** (`aspire_get_schema`) — Introspects Aspire's live OpenAPI spec to discover the available resource collections and their fields. Agents call this first to look up collection and field names instead of hard-coding them.
* **Aspire Query** (`aspire_query`) — OData-style read against any whitelisted Aspire collection (`Properties`, `Opportunities`, `WorkTickets`, `Invoices`, `Contacts`, `Companies`, `Jobs`, `Services`, …). Supports `$select`, `$filter`, `$expand`, `$orderby`, and `$top`/`$skip` paging. Auto-paginates up to a configurable row cap; **large result sets spill to a CSV attachment** while the inline payload is truncated to a token budget, so big pulls don't balloon the agent's context.

<Note>
  **Read-only.** This release exposes reads only — agents cannot create, update, or delete Aspire records. The HTTP client only permits `GET`; write capability is intentionally not wired up.
</Note>

## Example Prompts

Once connected, agents can answer questions like:

* "List active Opportunities over \$5,000, newest first."
* "How many open Work Tickets do we have by Route this week?"
* "Pull every Property for the Smith account with its service plan."
* "Export all Invoices from last quarter for analysis." (the full set spills to a CSV the agent can process in Python)

## Notes & Limitations

* **Read-only** — no writes in this release, by design.
* **Page size cap** — Aspire hard-caps `$top` at 1000 rows server-side; the tool auto-paginates to reach larger totals.
* **No webhooks** — Aspire has no push/webhook mechanism, so agents poll. For scheduled monitoring, match your task cadence to how fresh you need the data.
* **Single environment** — Aspire has no sandbox; credentials point at your live tenant. Because the integration is read-only, that's safe by construction.

## Security Considerations

* **Org-level connection** — one admin connects once for the whole organization. The Secret and tokens are stored server-side and redacted when the connection is read back in the UI.
* **Read-only by construction** — the client cannot mutate your Aspire tenant.
* **Grant the Aspire tools only to agents that need them.**
* **Rotate credentials** periodically from Aspire's API Keys screen and reconnect.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection rejected on setup">
    * Double-check the Client ID and Secret were copied exactly from **Account Settings > API Keys** in Aspire.
    * Confirm API access is enabled on your Aspire account.
  </Accordion>

  <Accordion title="A query returns no rows">
    * Run **Aspire Get Schema** to confirm the exact collection name and field names — they're case-sensitive OData identifiers.
    * Loosen your `$filter`; an over-narrow expression can legitimately match nothing.
  </Accordion>

  <Accordion title="Large pull feels slow or truncated inline">
    * Aspire pages at 1000 rows, so big collections take several sequential calls. The full set is written to a CSV attachment; the inline preview is intentionally truncated to keep the agent's context small. Have the agent process the CSV (e.g. in `execute_python`) rather than reading every row inline.
  </Accordion>
</AccordionGroup>

## Related Tools

* [Run Code](/tools/execute_python) — process large Aspire result sets (the CSV spillover attachment) with pandas.