Magnite Segments API

openapi: 3.2.0
info:
  title: SpringServe UI API (V0) Segments API
  version: 0.1.0
  description: "> **_NOTE:_** This document covers the v0 API (`/api/v0`). You can find additional documentation on the v0 API (`/api/v0`) on the \n[Magnite Help Center](https://help.magnite.com/), which is broken into sections for endpoints relevant to \n[SpringServe](https://help.magnite.com/help/api-documentation) and [Clearline](https://help.magnite.com/help/api-documentation-06dd4d3). \nYou can also find V1 swagger documentation by selecting ‘SpringServe API V1’ from the dropdown at the top right corner \nof this page. Please note we are in the process of creating V1 endpoints for all existing V0 endpoints, but while that work \nis in progress not all endpoints will be supported on V1. We advise reviewing both swagger pages to determine what \nis supported in each version.\n\n# Authentication\nWhen using this API documentation server, by default it will authenticate API calls using cookie-based authentication agains the selected server.  If you are properly logged into the SpringServe server and your session is still active, then the API calls should automatically authenticate.  \n\nOutside of this API documentation server you should use either Token Based or Bearer authentication.  You may also these authentication methods on this server as well,\n which will take precedence over any cookie/session based authentication.\n### Token Based Authentication\nUse the [POST /api/v0/auth](#/Auth/auth_post) endpoint to generate an API token that is then passed in the `Authorization: <token>` header\n\n### Bearer Authentication\nUse the [POST /api/v0/auth](#/Auth/auth_post) endpoint to authenticate and get a bearer token that is then passed in the `Authorization: Bearer <token>` header\n\n# Active Account Context\nA given request always runs in the context of currently active account for the authenticated user making\nthe request. The active account can be determined via the [GET /api/v0/accounts/current](#/Accounts/accounts_current_get)\nendpoint and updated via [POST /api/v0/accounts/{id}/set_current](#/Accounts/accounts_id_set_current_post).\nThe active account can also be overridden for an authenticated request by passing the `x-auth-context` header.\n\n# V0 List Resource Functionality\nV0 list endpoints support pagination via the `page` (first page is page 1) and `per` (how many results\nper page) query parameters. Some endpoints also support filtering by `ids[]` (repeated query param, e.g. ids[]=1&ids[]=2).\n"
servers:
- url: https://console.springserve.com
  description: Production API endpoint named by the SpringServe developer documentation (API - Getting Started).
- url: https://api.springserve.com
  description: Same application; also serves the Swagger UI at /api-docs. Verified 2026-08-13.
security:
- api_key: []
- bearer_token: []
tags:
- name: Segments
paths:
  /api/v0/segments:
    get:
      summary: Index
      description: List all segments. Supports pagination via page, per, and ids params.
      parameters:
      - $ref: ref/params.yaml#/components/parameters/pageParam
      - $ref: ref/params.yaml#/components/parameters/perParam
      - $ref: ref/params.yaml#/components/parameters/idsParam
      responses:
        '200':
          description: List of segments
          content:
            application/json:
              schema:
                $ref: ref/schemas.yaml#/components/schemas/ListResponse
      tags:
      - Segments
      operationId: segments_get
    post:
      summary: Create
      description: Creating a Segment
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              segment_list_create_simple:
                $ref: '#/components/examples/segment_list_create_simple'
              segment_list_create_full:
                $ref: '#/components/examples/segment_list_create_full'
              segment_pixel_create_simple:
                $ref: '#/components/examples/segment_pixel_create_simple'
              segment_pixel_create_full:
                $ref: '#/components/examples/segment_pixel_create_full'
        required: true
      responses:
        '201':
          description: Created segment
          content:
            application/json:
              schema:
                type: object
              example:
                name: My Cookie ID Segment
      tags:
      - Segments
      operationId: segments_post
  /api/v0/segments/{id}:
    get:
      summary: Show
      description: Get a segment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Segment details
          content:
            application/json:
              schema:
                type: object
              example:
                id: 10044
                account_id: 1
                name: My DID Segment
                description: My description
                active: true
                segment_type: list
                segment_list_type: cookie
                created_at: '2020-03-18T19:17:01.383Z'
      tags:
      - Segments
      operationId: segments_id_get
    put:
      summary: Update
      description: Update a segment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              segment_update_simple:
                $ref: '#/components/examples/segment_update_simple'
              segment_update_full:
                $ref: '#/components/examples/segment_update_full'
      responses:
        '200':
          description: Updated segment
          content:
            application/json:
              schema:
                type: object
      tags:
      - Segments
      operationId: segments_id_put
    delete:
      summary: Destroy
      description: Delete a segment
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
      tags:
      - Segments
      operationId: segments_id_delete
  /api/v0/segments/{segment_id}/items:
    get:
      summary: Index
      description: Get Device IDs or Cookies in a Segment
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      - $ref: ref/params.yaml#/components/parameters/pageParam
      - $ref: ref/params.yaml#/components/parameters/perParam
      - $ref: ref/params.yaml#/components/parameters/idsParam
      responses:
        '200':
          description: List of segment items
          content:
            application/json:
              schema:
                $ref: ref/schemas.yaml#/components/schemas/ListResponse
              example:
              - item: d207654f-6bdd-474e-9734-67b7c3d02d96
              - item: d20gt57i-6bdd-474e-9734-67b7c3d02d96
      tags:
      - Segments
      operationId: segments_segment_id_items_get
  /api/v0/segments/{segment_id}/items/bulk_create:
    post:
      summary: Bulk Create
      description: Add elements to a Segment
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              segment_items_bulk_create_single:
                $ref: '#/components/examples/segment_items_bulk_create_single'
              segment_items_bulk_create_multiple:
                $ref: '#/components/examples/segment_items_bulk_create_multiple'
        required: true
      responses:
        '201':
          description: Created items
          content:
            application/json:
              schema:
                type: object
              example:
                created: true
      tags:
      - Segments
      operationId: segments_segment_id_items_bulk_create_post
  /api/v0/segments/{segment_id}/items/bulk_delete:
    delete:
      summary: Bulk Delete
      description: Remove specific Device Ids or Cookies
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
            example:
              items:
              - d207654f-6bdd-474e-9734-67b7c3d02d96
      responses:
        '200':
          description: Deleted items
          content:
            application/json:
              schema:
                type: object
              example:
                deleted: true
      tags:
      - Segments
      operationId: segments_segment_id_items_bulk_delete_delete
  /api/v0/segments/{segment_id}/items/bulk_replace:
    post:
      summary: Bulk Replace
      description: Replace Entire Segment
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
            examples:
              segment_items_bulk_replace_single:
                $ref: '#/components/examples/segment_items_bulk_replace_single'
              segment_items_bulk_replace_multiple:
                $ref: '#/components/examples/segment_items_bulk_replace_multiple'
        required: true
      responses:
        '200':
          description: Replaced items
          content:
            application/json:
              schema:
                type: object
              example:
                created: true
      tags:
      - Segments
      operationId: segments_segment_id_items_bulk_replace_post
  /api/v0/segments/{segment_id}/items/file_bulk_create:
    post:
      summary: File Bulk Create
      description: Add Items to a Segment using a File
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - csv_file
              properties:
                csv_file:
                  type: string
                  format: binary
                  description: CSV file containing device IDs or cookies to append
        required: true
      responses:
        '201':
          description: Append confirmation
          content:
            application/json:
              schema:
                type: object
              example:
                created: true
      tags:
      - Segments
      operationId: segments_segment_id_items_file_bulk_create_post
  /api/v0/segments/{segment_id}/items/file_bulk_delete:
    delete:
      summary: File Bulk Delete
      description: Remove specific items using a File
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - csv_file
              properties:
                csv_file:
                  type: string
                  format: binary
                  description: CSV file containing device IDs or cookies to remove
      responses:
        '200':
          description: Deletion confirmation
          content:
            application/json:
              schema:
                type: object
              example:
                deleted: true
      tags:
      - Segments
      operationId: segments_segment_id_items_file_bulk_delete_delete
  /api/v0/segments/{segment_id}/items/file_bulk_replace:
    post:
      summary: File Bulk Replace
      description: Replace Entire Segment with a File
      parameters:
      - name: segment_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - csv_file
              properties:
                csv_file:
                  type: string
                  format: binary
                  description: CSV file containing device IDs or cookies to replace existing segment
        required: true
      responses:
        '200':
          description: Replacement confirmation
          content:
            application/json:
              schema:
                type: object
              example:
                created: true
      tags:
      - Segments
      operationId: segments_segment_id_items_file_bulk_replace_post
components:
  examples:
    segment_items_bulk_create_single:
      summary: Add single item
      value:
        items:
        - d207654f-6bdd-474e-9734-67b7c3d02d96
    segment_update_full:
      summary: Update segment (full)
      value:
        name: Segment Name
        description: Segment description
        active: true
    segment_list_create_simple:
      summary: List segment (simple)
      value:
        name: Segment Name
        segment_type: list
        segment_list_type: cookie
    segment_pixel_create_simple:
      summary: Pixel segment (simple)
      value:
        name: Segment Name
        segment_type: pixel
        segment_pixel_type: device_id
        user_expiration_value: 30
    segment_items_bulk_create_multiple:
      summary: Add multiple items
      value:
        items:
        - d207654f-6bdd-474e-9734-67b7c3d02d96
        - a1b2c3d4-6bdd-474e-9734-67b7c3d02d96
    segment_items_bulk_replace_single:
      summary: Replace with single item
      value:
        items:
        - d207654f-6bdd-474e-9734-67b7c3d02d96
    segment_pixel_create_full:
      summary: Pixel segment (full)
      value:
        name: Segment Name
        description: Segment description
        segment_type: pixel
        segment_pixel_type: device_id
        user_expiration_value: 30
        active: true
    segment_update_simple:
      summary: Update segment (simple)
      value:
        name: Segment Name
        active: true
    segment_items_bulk_replace_multiple:
      summary: Replace with multiple items
      value:
        items:
        - d207654f-6bdd-474e-9734-67b7c3d02d96
        - a1b2c3d4-6bdd-474e-9734-67b7c3d02d96
    segment_list_create_full:
      summary: List segment (full)
      value:
        name: Segment Name
        description: Segment description
        segment_type: list
        segment_list_type: cookie
        active: true
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: SpringServe authorization token based authentication.
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: SpringServe authorization bearer token based authentication.  This key is included in the response from the /api/v0/auth and /api/v1/auth endpoints.  This key will be automatically set if you run the example for /api/v0/auth or /api/v1/auth