> ## 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.

# Subscriptions and delivery

> Choose what you receive and where Ploti delivers it

<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>

A subscription is the set of datasets you receive and where they go.

## What a subscription covers

```json theme={null}
{
  "name": "Central Florida",
  "places": ["us-fl-12095", "us-fl-12117"],
  "topics": ["permits", "code_enforcement"],
  "datasetIds": ["ds_fl_statewide_contractor_licenses"],
  "delivery": { "type": "pull" }
}
```

* `places`: every dataset in each county, now and later. A dataset Ploti adds to one of them joins the subscription and sends `dataset.added`.
* `topics`: only these topics within `places`. Every topic when left out.
* `datasetIds`: datasets to include on their own, from any county in your coverage.

Places must be in your workspace's coverage. Changing a subscription with `PATCH` sends `dataset.added` and `dataset.removed` for the datasets that join or leave.

## Pull

With `"delivery": { "type": "pull" }`, you fetch files yourself with signed links from the [manifest](/docs/platforms/quickstart) and from each version. Nothing is written anywhere on your side until you ask.

## Push to your bucket

Ploti can write each version's files into your own bucket as soon as they publish.

<Tabs>
  <Tab title="Amazon S3">
    Create a role in your account that Ploti can assume, with `s3:PutObject` on the bucket and prefix, then:

    ```json theme={null}
    {
      "delivery": {
        "type": "s3",
        "bucket": "acme-public-records",
        "prefix": "ploti/",
        "region": "us-east-1",
        "roleArn": "arn:aws:iam::123456789012:role/ploti-delivery"
      }
    }
    ```
  </Tab>

  <Tab title="Google Cloud Storage">
    Grant Ploti's service account `roles/storage.objectCreator` on the bucket, then:

    ```json theme={null}
    {
      "delivery": {
        "type": "gcs",
        "bucket": "acme-public-records",
        "prefix": "ploti/",
        "serviceAccount": "delivery@ploti-feeds.iam.gserviceaccount.com"
      }
    }
    ```
  </Tab>
</Tabs>

Ploti writes this layout under your prefix:

```text theme={null}
{prefix}{datasetId}/
  versions/{version}/
    schema.json
    snapshot/part-0000.parquet
    snapshot/part-0001.parquet
    changes/part-0000.parquet
    manifest.json
  current.json
```

`manifest.json` lists the version's files with row counts and checksums. `current.json` names the latest version delivered, written last, so a reader that sees it can trust the files it names are complete.

`GET /v1/subscriptions/{id}/deliveries` lists what was written, when, and any failures. Events are sent once a version is delivered, so `dataset.updated` means the files are already in your bucket.

## Other destinations

Delivery is not limited to the options above. Every destination receives the same files (snapshots, changes, schemas and manifests), so adding one is a matter of writing them somewhere new. If you ingest into a warehouse, a database or another store, [tell us](mailto:support@ploti.ai) and we will deliver there.

## Formats

| Format | Use |
| - | - |
| GeoParquet (default) | Warehouses, DuckDB, pandas, Spark. Geometry as WKB, EPSG:4326. |
| CSV | Spreadsheets and simple loaders. Geometry as WKT. |


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