Amperity Segments API

openapi: 3.2.0
info:
  title: Amperity API (Unstable) Segments API
  version: unstable
  description: '## Overview


    The Amperity API enables programmatic access to your Amperity tenant through a collection

    of RESTful endpoints that support API-first use cases for integrations, applications, and

    custom workflows.'
  contact:
    url: https://docs.amperity.com/api/
servers:
- url: https://app.amperity.com/api
  description: Amazon AWS
- url: https://<tenant-id>.amperity.com/api
  description: Microsoft Azure
  variables:
    tenant-id:
      default: your-tenant-id
      description: Your Amperity tenant ID.
security:
- BearerAuth: []
tags:
- name: Segments
  description: Return a list of segments available in your tenant.
paths:
  /segments:
    get:
      tags:
      - Segments
      summary: GET /segments
      operationId: list-segment
      description: Use the **GET /segments** endpoint to return a list of segments from your tenant.
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      - $ref: '#/components/parameters/AmperityTenant'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/NextToken'
      - $ref: '#/components/parameters/WithTotal'
      responses:
        '200':
          description: The **200** response returns a set of segments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    NextToken:
      name: next_token
      in: query
      required: false
      description: 'An opaque token that is used to paginate results. Omit the `next_token` property

        to return the first page. Use the cursor value for `next_token` that was returned

        in a response to view the next page of results.


        For example: `ABCd1fghIJk2l3M`


        > **Note:** The possible values for `next_token` are returned within the 200 response.


        > **Important:** The value for `next_token` cannot be null.

        '
      schema:
        type: string
        example: ZVEy1iwsKBs9a6H
    ApiVersionHeader:
      name: api-version
      in: header
      required: true
      description: 'A supported version of the Amperity API. For example: 2024-04-01.'
      schema:
        type: string
        enum:
        - '2024-04-01'
        - unstable
        default: unstable
        example: '2024-04-01'
    WithTotal:
      name: with_total
      in: query
      required: false
      description: 'Set this value to `true` to include a total count of all results. Default value: `false`.


        > **Note:** Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.

        '
      schema:
        type: boolean
        default: false
    Limit:
      name: limit
      in: query
      required: false
      description: The maximum number of records to include in a single page of results.
      schema:
        type: integer
    AmperityTenant:
      name: amperity-tenant
      in: header
      required: true
      description: The unique identifier for the tenant.
      schema:
        type: string
        example: <tenant-id>
  responses:
    InternalError:
      description: Internal Server Error — an unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Not Authorized — the API key does not have permission for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication Required — no valid Bearer token was provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request — the request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    SegmentList:
      type: object
      description: A paginated list of segments.
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: array
          description: Segment items on this page.
          items:
            $ref: '#/components/schemas/Segment'
        next_token:
          type: string
          description: 'The cursor value to use in a subsequent request to return the next page of results. When empty, the last page has been returned.

            '
          example: ZVEy1iwsKBs9a6H
        total:
          type: integer
          description: The total count of all results. Only returned when with_total is set to true.
    Segment:
      type: object
      description: A segment.
      required:
      - id
      - name
      - status
      additionalProperties: false
      properties:
        id:
          type: string
          description: The Amperity internal identifier for the segment.
          example: seg-35GMWpn6Y
        name:
          type: string
          description: The name of the segment.
          example: Returning Customers
        status:
          type: string
          description: The current status of the segment.
          example: active
    ErrorResponse:
      type: object
      description: An error response returned by the API.
      required:
      - status
      - message
      additionalProperties: false
      properties:
        status:
          type: integer
          description: The HTTP status code.
          example: 400
        message:
          type: string
          description: A description of the error.
          example: An unexpected error occurred.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using a Bearer token generated from an Amperity API key. Include the token in the Authorization header of every request.

        '