openapi: 3.1.0
info:
  title: FullStory Segments Export Batch Import Endpoints 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: Endpoints
  description: Create, retrieve, update, and delete webhook endpoints that receive real-time notifications from FullStory. Each endpoint has a destination URL, configured event types, signing secret, and enabled status.
paths:
  /webhooks/v1/endpoints:
    post:
      operationId: createEndpoint
      summary: Create a webhook endpoint
      description: Creates a new webhook endpoint with the given properties, including the destination URL and the event types it should receive. Some event types require a subcategory property. Returns the created endpoint details including its ID and signing secret.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listEndpoints
      summary: List webhook endpoints
      description: Pages through all configured webhook endpoints with pagination support. Returns endpoint details including ID, URL, configured event types, and enabled status.
      tags:
      - Endpoints
      responses:
        '200':
          description: List of webhook endpoints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointList'
        '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'
  /webhooks/v1/endpoints/{endpointId}:
    get:
      operationId: getEndpoint
      summary: Get a webhook endpoint
      description: Retrieves endpoint details corresponding to the provided endpoint ID, including the destination URL, configured event types, signing secret, and enabled status.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      responses:
        '200':
          description: Webhook endpoint retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateEndpoint
      summary: Update a webhook endpoint
      description: Updates an existing webhook endpoint. Can be used to change the destination URL, configured events, signing secret, and the enabled status of the endpoint.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteEndpoint
      summary: Delete a webhook endpoint
      description: Permanently deletes the webhook endpoint specified by the endpoint ID. The endpoint will no longer receive any event notifications after deletion.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      responses:
        '200':
          description: Webhook endpoint deleted successfully
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint 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:
    CreateEndpointRequest:
      type: object
      required:
      - url
      - events
      description: Request body for creating a new webhook endpoint
      properties:
        url:
          type: string
          format: uri
          description: The URL that will receive webhook event notifications
        events:
          type: array
          description: The types of events this endpoint should receive
          items:
            $ref: '#/components/schemas/EventTypeConfig'
    UpdateEndpointRequest:
      type: object
      description: Request body for updating an existing webhook endpoint
      properties:
        url:
          type: string
          format: uri
          description: The new destination URL for webhook events
        events:
          type: array
          description: Updated list of event types for this endpoint
          items:
            $ref: '#/components/schemas/EventTypeConfig'
        signingSecret:
          type: string
          description: Updated signing secret for verifying webhook payloads
        enabled:
          type: boolean
          description: Whether the endpoint is enabled and receiving events
    Endpoint:
      type: object
      description: A configured webhook endpoint in FullStory
      properties:
        id:
          type: string
          description: Unique identifier for the webhook endpoint
        url:
          type: string
          format: uri
          description: The destination URL receiving webhook events
        events:
          type: array
          description: The event types configured for this endpoint
          items:
            $ref: '#/components/schemas/EventTypeConfig'
        signingSecret:
          type: string
          description: Secret used to sign webhook payloads for verification
        enabled:
          type: boolean
          description: Whether the endpoint is actively receiving events
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the endpoint was created
    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
    EventTypeConfig:
      type: object
      required:
      - eventName
      description: Configuration for a specific event type on a webhook endpoint
      properties:
        eventName:
          type: string
          description: The name of the event type
          enum:
          - segment.created
          - segment.trend.alert
          - recording.event.custom
          - note.created
        subcategory:
          type: string
          description: Required subcategory for event types that require one, such as specifying which custom event to listen for
    EndpointList:
      type: object
      description: List of webhook endpoints
      properties:
        endpoints:
          type: array
          description: Array of configured webhook endpoints
          items:
            $ref: '#/components/schemas/Endpoint'
  parameters:
    EndpointIdPath:
      name: endpointId
      in: path
      required: true
      description: The unique identifier of the webhook endpoint
      schema:
        type: string
  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/