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

# Create a subscription

> Receive every dataset in the named places, optionally only some
topics, plus any datasets named directly. Datasets Ploti adds to
those places later join the subscription on their own, each with a
`dataset.added` event. Takes an `Idempotency-Key` header.




## OpenAPI

````yaml /platforms/openapi.yaml post /v1/subscriptions
openapi: 3.1.0
info:
  title: Ploti Data Feeds API
  version: 1.0.0
  description: |
    Early access: contact support@ploti.ai to set up a subscription.

    Public records from the places your workspace covers, delivered to your
    own systems. Subscribe to counties, load each dataset's snapshot once,
    then apply each new version's changes as Ploti publishes them.

    Every call acts as the workspace member who holds the API key. Lists that
    page take `limit` and `cursor` and return `nextCursor`, null on the last
    page. Fields are camelCase. A refusal is
    `{ "error": { "code", "message", "links" } }`.
servers:
  - url: https://api.ploti.ai
security:
  - bearerAuth: []
tags:
  - name: Places
    description: The counties a workspace can subscribe to.
  - name: Datasets
    description: What each dataset holds, where it comes from and how it is shaped.
  - name: Versions
    description: Each published version of a dataset, its files and its changes.
  - name: Subscriptions
    description: The places, topics and datasets you receive, and where they are delivered.
  - name: Events
    description: An ordered, replayable log of what changed in a subscription.
paths:
  /v1/subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create a subscription
      description: |
        Receive every dataset in the named places, optionally only some
        topics, plus any datasets named directly. Datasets Ploti adds to
        those places later join the subscription on their own, each with a
        `dataset.added` event. Takes an `Idempotency-Key` header.
      operationId: createSubscription
      parameters:
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
            example:
              name: Central Florida permits
              places:
                - us-fl-12095
                - us-fl-12117
              topics:
                - permits
                - code_enforcement
              delivery:
                type: pull
      responses:
        '201':
          description: The subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '422':
          description: A place outside the coverage, or an unknown topic or dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        A retry with the same key returns the first answer instead of creating
        twice.
      schema:
        type: string
        maxLength: 255
  schemas:
    SubscriptionInput:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        places:
          type: array
          items:
            type: string
          description: Place ids. Every dataset in each place.
        topics:
          type: array
          items:
            type: string
          description: Only these topics within `places`. Every topic when left out.
        datasetIds:
          type: array
          items:
            type: string
          description: Datasets to include on their own, in any covered place.
        delivery:
          $ref: '#/components/schemas/DeliveryTarget'
        format:
          type: string
          enum:
            - geoparquet
            - csv
          default: geoparquet
          description: The format pushed deliveries are written in.
    Subscription:
      type: object
      required:
        - id
        - name
        - places
        - topics
        - datasetIds
        - delivery
        - datasetCount
        - createdAt
      properties:
        id:
          type: string
        name:
          type: string
        places:
          type: array
          items:
            type: string
        topics:
          type: array
          items:
            type: string
        datasetIds:
          type: array
          items:
            type: string
        delivery:
          $ref: '#/components/schemas/DeliveryTarget'
        format:
          type: string
          enum:
            - geoparquet
            - csv
        datasetCount:
          type: integer
        lastEventId:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              examples:
                - not_found
                - outside_coverage
                - not_distributable
                - cursor_expired
            message:
              type: string
            links:
              type: object
              additionalProperties:
                type: string
                format: uri
    DeliveryTarget:
      description: |
        Where a subscription's files are delivered. More destination types
        are added as customers need them; each receives the same files.
      oneOf:
        - type: object
          title: Pull
          required:
            - type
          properties:
            type:
              const: pull
        - type: object
          title: Amazon S3
          required:
            - type
            - bucket
            - roleArn
          properties:
            type:
              const: s3
            bucket:
              type: string
            prefix:
              type: string
            region:
              type: string
            roleArn:
              type: string
              description: A role in your account that Ploti assumes to write.
        - type: object
          title: Google Cloud Storage
          required:
            - type
            - bucket
            - serviceAccount
          properties:
            type:
              const: gcs
            bucket:
              type: string
            prefix:
              type: string
            serviceAccount:
              type: string
              description: Grant Ploti's service account write access to the bucket.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key from Settings, API keys, with the `feeds` scope.

````

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