Bulk update segments

PATCH

/v1/segments/bulk

curl --request PATCH \
  --url https://dev-api.infiniteaudience.ai/v1/segments/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "segment_ids": [ "example" ], "name": "example", "status": "active" }'

• Development API Server

Apply the same name and/or status change to up to 50 segments in one request. Only name and status are bulk-patchable — they are valid across all four subtypes. Composition and subtype-specific attributes (filters, filter_groups, column_mappings) are rejected with 400 INVALID_FIELD; use PATCH /v1/segments/{id} for those. Best-effort per segment: each segment is updated independently and failures (not found, invalid status transition) are reported per id in the failed array — successful updates are never rolled back. The single-PATCH status transition rule applies per segment: only archived segments can be restored to active. Requires ‘purchase’ scope.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

segment_ids

required

IDs of segments to update (1-50).

Array<string>

>= 1 items <= 50 items

name

New display name applied to every listed segment.

string

>= 1 characters <= 120 characters

status

New status applied to every listed segment. Only user-settable values are accepted; ‘active’ is only valid on segments currently archived (per-segment failure otherwise).

string

Allowed values: active archived

Responses

200

Bulk update processed. Per-segment failures, if any, are listed in failed.

Media typeapplication/json

object

updated

required

Number of segments successfully updated.

integer

failed

required

Segments that could not be updated.

Array<object>

object

id

required

string

error

required

string

Example

{
  "updated": 2,
  "failed": [
    {
      "id": "seg_missing",
      "error": "Not found"
    }
  ]
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplevalidation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}