openapi: 3.1.0
info:
  title: FullStory Export Batch Import Segments API
  description: 'The FullStory Segments Export API provides an asynchronous workflow for downloading captured event data from FullStory. Developers can initiate export jobs to aggregate segment data, query for the status of running jobs, and retrieve download URLs for completed exports. Two types of segment data are available for export: individuals matching a segment and events performed by those individuals. This API is useful for integrating FullStory behavioral data into external analytics pipelines and data warehouses.'
  version: '1.0'
  contact:
    name: FullStory Support
    url: https://help.fullstory.com/
  termsOfService: https://www.fullstory.com/legal/terms-and-conditions/
servers:
- url: https://api.fullstory.com
  description: FullStory Production API Server
security:
- basicAuth: []
tags:
- name: Segments
  description: Retrieve segment metadata including name, creator, and creation time.
paths:
  /segments/v1:
    get:
      operationId: listSegments
      summary: List segments
      description: Returns a paginated list of segments for the organization. You can optionally limit the number of segments returned, with a default of 20 and a maximum of 100 per page. Use the pagination token to retrieve additional pages of results.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/PaginationToken'
      responses:
        '200':
          description: List of segments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentList'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /segments/v1/{segmentId}:
    get:
      operationId: getSegment
      summary: Get a segment
      description: Returns segment information for the provided segment ID, including the segment name, creator email, and creation timestamp.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/SegmentIdPath'
      responses:
        '200':
          description: Segment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Segment:
      type: object
      description: A FullStory segment representing a saved group of users matching specific behavioral criteria
      properties:
        id:
          type: string
          description: Unique identifier for the segment
        name:
          type: string
          description: Display name of the segment
        creator:
          type: string
          format: email
          description: Email address of the FullStory user who created the segment
        created:
          type: string
          format: date-time
          description: UTC RFC 3339 timestamp for when the segment was created. Not present for built-in segments.
    Error:
      type: object
      description: Standard error response from the FullStory API
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
    SegmentList:
      type: object
      description: Paginated list of segments
      properties:
        segments:
          type: array
          description: Array of segment objects
          items:
            $ref: '#/components/schemas/Segment'
        pagination_token:
          type: string
          description: Token to retrieve the next page of results. Absent when no more pages are available.
  parameters:
    SegmentIdPath:
      name: segmentId
      in: path
      required: true
      description: The unique identifier for the segment
      schema:
        type: string
    PaginationToken:
      name: pagination_token
      in: query
      required: false
      description: Token for retrieving the next page of results. Do not change other list parameters between consecutive paginated requests.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of segments to return per page. Default is 20, maximum is 100.
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key passed in the Authorization header using Basic authentication. Admin or Architect level keys are required.
externalDocs:
  description: FullStory Segments Export API Documentation
  url: https://developer.fullstory.com/server/v1/segments/create-segment-export/