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

# Quickstart

> Subscribe to a county, load its datasets and stay current

<Info>
  Data Feeds is in early access. [Contact us](mailto:support@ploti.ai) to set up
  a subscription; the API and sync client described here open to early access
  customers first.
</Info>

This walks through the whole sync loop with the REST API. The [sync client](/docs/platforms/sync-client) runs the same loop for you with one command.

<Steps>
  <Step title="Create an API key">
    In Ploti, open **Settings, API keys** and create a key with the `feeds` scope. Store it where you keep secrets.

    ```bash theme={null}
    export PLOTI_API_KEY=pk_live_...
    ```
  </Step>

  <Step title="Find the places you cover">
    ```bash theme={null}
    curl https://api.ploti.ai/v1/places?state=FL \
      -H "Authorization: Bearer $PLOTI_API_KEY"
    ```

    ```json theme={null}
    {
      "places": [
        {
          "id": "us-fl-12095",
          "name": "Orange County",
          "state": "FL",
          "kind": "county",
          "datasetCounts": { "permits": 6, "zoning": 3, "code_enforcement": 2 }
        }
      ],
      "nextCursor": null
    }
    ```
  </Step>

  <Step title="Subscribe">
    ```bash theme={null}
    curl -X POST https://api.ploti.ai/v1/subscriptions \
      -H "Authorization: Bearer $PLOTI_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: orange-permits-1" \
      -d '{
        "name": "Orange County permits",
        "places": ["us-fl-12095"],
        "topics": ["permits"],
        "delivery": { "type": "pull" }
      }'
    ```
  </Step>

  <Step title="Load the snapshots">
    The manifest lists every dataset in the subscription with links to its current snapshot, and the event cursor it is current as of.

    ```bash theme={null}
    curl https://api.ploti.ai/v1/subscriptions/sub_8f3k2m/manifest \
      -H "Authorization: Bearer $PLOTI_API_KEY"
    ```

    ```json theme={null}
    {
      "subscriptionId": "sub_8f3k2m",
      "generatedAt": "2026-10-18T14:02:11Z",
      "eventCursor": "evt_0000018f2a9c",
      "datasets": [
        {
          "datasetId": "ds_orange_fl_building_permits",
          "title": "Building permits",
          "place": "us-fl-12095",
          "topic": "permits",
          "version": 42,
          "schemaVersion": "2.1",
          "files": {
            "snapshot": [
              {
                "url": "https://files.ploti.ai/...part-0000.parquet",
                "format": "geoparquet",
                "rows": 184220,
                "bytes": 21933012,
                "sha256": "9b1f..."
              }
            ],
            "schema": { "url": "https://files.ploti.ai/...schema.json", "format": "json", "rows": 0, "bytes": 4120, "sha256": "c03a..." },
            "expiresAt": "2026-10-18T15:02:11Z"
          }
        }
      ]
    }
    ```

    Load each snapshot into a table, keyed on `_ploti_record_id`. Save `eventCursor`.
  </Step>

  <Step title="Apply events">
    Read the events after your cursor, apply each in order, and save the id of the last one you applied.

    ```bash theme={null}
    curl "https://api.ploti.ai/v1/subscriptions/sub_8f3k2m/events?after=evt_0000018f2a9c" \
      -H "Authorization: Bearer $PLOTI_API_KEY"
    ```

    | Event | What to do |
    | - | - |
    | `dataset.updated` | Fetch the version, apply its changes file: upsert or delete by `_ploti_record_id`. |
    | `dataset.schema_changed` | Additive: add the new columns. Breaking: review, then migrate your table. |
    | `dataset.added` | Load the new dataset's snapshot. |
    | `dataset.resync_required` | Replace the table with the version's snapshot. |
    | `dataset.removed` | Stop expecting updates for that dataset. |
  </Step>

  <Step title="Get told instead of polling">
    Add a [webhook](/docs/platforms/events#webhooks) for the subscription's events. Use it as the signal to read the event log; the log stays the source of truth.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.