ProsperStack Properties API

openapi: 3.2.0
info:
  title: ProsperStack API Reference Properties API
  version: v1
  description: 'This is the reference documentation for the ProsperStack API v1. Visit ProsperStack at prosperstack.com.


    For more information on ProsperStack features, see the primary documentation.


    Let us know how we can improve the API, documentation or anything else you need help with at support@prosperstack.com.


    # Introduction


    The ProsperStack API provides a REST-like interface to your ProsperStack data. It uses standard HTTP verbs, accepts JSON-encoded request bodies and provides JSON-encoded responses.


    You can use the ProsperStack API to access your live production data or data from test mode. The API key you use to authenticate requests determines which mode will be used.


    # Authentication


    The ProsperStack API uses API keys to authenticate requests. You can manage your API keys from the ProsperStack API Keys settings page.


    Live mode API keys have the prefix `key_` and test mode API keys have the prefix `key_test_`.


    Authentication uses HTTP basic authentication. Provide your API key as the basic authentication username. You don''t need to provide a password.


    A simple example using cURL:


    ```bash

    curl https://api.prosperstack.com/v1/flow_sessions \

    -u key_LSdJXBrN3SP7bdJrQSMp2eZK:

    ```


    Learn more about creating API keys.


    # Pagination


    All list endpoints support cursor-based pagination. The body of a list response will contain a `data` property with an array of objects and a `next_cursor` property desginating the cursor value to retrieve the next set of results.


    Use the value of `next_cursor` in the `cursor` query parameter to specify the set of results to return. If `next_cursor` is `null`, there are no more results.


    You can also specify a `limit` in the query parameters to adjust the number of items per result set. The limit defaults to 10 and has a maximum of 100.


    # Rate limits


    The ProsperStack API enforces a rate limit of 100 requests per minute. Your live mode and test mode accounts have separate limits.


    When the rate limit is exceeded, requests will fail with the HTTP status `429 Too Many Requests` until the limit window resets.


    The ProsperStack API implements the RateLimit Header Fields for HTTP draft which describes a set of HTTP headers you can use to observe current request limits.


    The headers are:


    - `RateLimit-Limit` — The limit of requests per time window (1 minute)

    - `RateLimit-Remaining` — The number of requests left before exceeding the limit

    - `RateLimit-Reset` — The number of seconds until the limit window resets


    If you need to exceed the rate limit, let us know at support@prosperstack.com and we''ll be happy to help.'
  x-logo:
    url: https://prosperstack.com/images/logo-api.svg
servers:
- url: https://api.prosperstack.com/v1
security:
- basicAuth: []
tags:
- name: Properties
  x-displayName: Properties
  description: 'A property represents a ProsperStack custom property defined for subscribers or subscriptions.


    Properties can be used to store custom data with your subscribers and subscriptions. They can be of type `text`, `number`, `boolean` or `date`.


    Each custom property must be attached to either the `subscriber` or `subscription` entity type.'
paths:
  /properties:
    get:
      summary: List properties
      operationId: listProperties
      tags:
      - Properties
      parameters:
      - name: entity
        in: query
        description: Entity type to return properties for
        schema:
          type: string
          enum:
          - subscriber
          - subscription
      - name: cursor
        in: query
        description: Pagination cursor to retrieve
        schema:
          type: string
      - name: limit
        in: query
        description: Limit of properties to return
        schema:
          type: integer
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Property'
                  next_cursor:
                    $ref: '#/components/schemas/Cursor'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/Error'
    post:
      summary: Create a property
      operationId: createProperty
      tags:
      - Properties
      requestBody:
        $ref: '#/components/requestBodies/Property'
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: The URL of the created property
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
        '400':
          description: Bad Request
          $ref: '#/components/responses/Error'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/Error'
        '409':
          description: Conflict
          $ref: '#/components/responses/Error'
  /properties/{id}:
    get:
      summary: Retrieve a property
      operationId: retrievePropertyById
      tags:
      - Properties
      parameters:
      - name: id
        in: path
        description: Property ID to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
        '404':
          description: Not Found
          $ref: '#/components/responses/Error'
    delete:
      summary: Delete a property
      description: Delete a property to prevent it from being used in the future. Deleting a property does not delete associated property data already stored on subscribers or subscriptions.
      operationId: deletePropertyById
      parameters:
      - name: id
        in: path
        description: Property ID to delete
        required: true
        schema:
          type: string
      tags:
      - Properties
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          $ref: '#/components/responses/Error'
        '404':
          description: Not Found
          $ref: '#/components/responses/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    Cursor:
      type:
      - string
      - 'null'
      example: 'null'
    Property:
      type: object
      required:
      - id
      - key
      - name
      - entity
      - type
      - format
      - created_at
      properties:
        id:
          type: string
          example: prop_jrtpyZs1httwFFIl7V80cHwf
        key:
          type: string
          example: number_of_contacts
        name:
          type: string
          example: Number of contacts
        entity:
          type: string
          enum:
          - subscriber
          - subscription
        type:
          type: string
          enum:
          - text
          - number
          - boolean
          - date
          example: number
        format:
          type:
          - string
          - 'null'
          enum:
          - number
          - currency
          - null
          example: number
        created_at:
          type: string
          format: date-time
  requestBodies:
    Property:
      content:
        application/json:
          schema:
            type: object
            required:
            - key
            - name
            - entity
            - type
            properties:
              key:
                type: string
                example: number_of_contacts
              name:
                type: string
                example: Number of contacts
              entity:
                type: string
                enum:
                - subscriber
                - subscription
                example: subscriber
              type:
                type: string
                enum:
                - text
                - number
                - boolean
                - date
                example: number
              format:
                type: string
                enum:
                - number
                - currency
                example: number
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic