Amazon Pinpoint Pinpoint Segments API
The Pinpoint Segments API from Amazon Pinpoint — 2 operation(s) for pinpoint segments.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-pinpoint:amazon-pinpoint-segments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Amazon Pinpoint Segments API
version: '2016-12-01'
description: Generated from AWS's published Smithy model for Amazon Pinpoint. 5 operation(s).
contact:
name: Amazon Web Services
url: https://aws.amazon.com/contact-us/
license:
name: Apache 2.0
identifier: Apache-2.0
url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://pinpoint.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4: []
tags:
- name: Segments
paths:
/v1/apps/{ApplicationId}/segments:
post:
operationId: CreateSegment
summary: Create Segment
description: Creates a new segment for an application or updates the configuration, dimension, and other settings for an existing segment that's associated with an application.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSegmentResponse'
'400':
description: BadRequestException
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestException'
'403':
description: ForbiddenException
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenException'
'500':
description: InternalServerErrorException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorException'
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowedException'
'404':
description: NotFoundException
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
'413':
description: PayloadTooLargeException
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeException'
'429':
description: TooManyRequestsException
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSegmentRequest'
tags:
- Segments
get:
operationId: GetSegments
summary: Get Segments
description: Retrieves information about the configuration, dimension, and other settings for all the segments that are associated with an application.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetSegmentsResponse'
'400':
description: BadRequestException
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestException'
'403':
description: ForbiddenException
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenException'
'500':
description: InternalServerErrorException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorException'
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowedException'
'404':
description: NotFoundException
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
'413':
description: PayloadTooLargeException
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeException'
'429':
description: TooManyRequestsException
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetSegmentsRequest'
tags:
- Segments
/v1/apps/{ApplicationId}/segments/{SegmentId}:
delete:
operationId: DeleteSegment
summary: Delete Segment
description: Deletes a segment from an application.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSegmentResponse'
'400':
description: BadRequestException
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestException'
'403':
description: ForbiddenException
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenException'
'500':
description: InternalServerErrorException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorException'
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowedException'
'404':
description: NotFoundException
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
'413':
description: PayloadTooLargeException
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeException'
'429':
description: TooManyRequestsException
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSegmentRequest'
tags:
- Segments
get:
operationId: GetSegment
summary: Get Segment
description: Retrieves information about the configuration, dimension, and other settings for a specific segment that's associated with an application.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetSegmentResponse'
'400':
description: BadRequestException
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestException'
'403':
description: ForbiddenException
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenException'
'500':
description: InternalServerErrorException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorException'
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowedException'
'404':
description: NotFoundException
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
'413':
description: PayloadTooLargeException
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeException'
'429':
description: TooManyRequestsException
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GetSegmentRequest'
tags:
- Segments
put:
operationId: UpdateSegment
summary: Update Segment
description: Creates a new segment for an application or updates the configuration, dimension, and other settings for an existing segment that's associated with an application.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentResponse'
'400':
description: BadRequestException
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestException'
'403':
description: ForbiddenException
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenException'
'500':
description: InternalServerErrorException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorException'
'405':
description: MethodNotAllowedException
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowedException'
'404':
description: NotFoundException
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundException'
'413':
description: PayloadTooLargeException
content:
application/json:
schema:
$ref: '#/components/schemas/PayloadTooLargeException'
'429':
description: TooManyRequestsException
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentRequest'
tags:
- Segments
components:
schemas:
GetSegmentResponse:
type: object
properties:
SegmentResponse:
$ref: '#/components/schemas/SegmentResponse'
required:
- SegmentResponse
SegmentImportResource:
type: object
properties:
ChannelCounts:
type: object
additionalProperties:
type: integer
description: The number of channel types in the endpoint definitions that were imported to create the segment.
ExternalId:
type: string
description: (Deprecated) Your AWS account ID, which you assigned to an external ID key in an IAM trust policy. Amazon Pinpoint previously used this value to assume an IAM role when importing endpoint definitions, but we removed this requirement. We don't recommend use of external IDs for IAM roles that are assumed by Amazon Pinpoint.
Format:
type: string
enum:
- CSV
- JSON
description: 'The format of the files that were imported to create the segment. Valid values are: CSV, for comma-separated values format; and, JSON, for newline-delimited JSON format.'
RoleArn:
type: string
description: The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that authorized Amazon Pinpoint to access the Amazon S3 location to import endpoint definitions from.
S3Url:
type: string
description: The URL of the Amazon Simple Storage Service (Amazon S3) bucket that the endpoint definitions were imported from to create the segment.
Size:
type: integer
description: The number of endpoint definitions that were imported successfully to create the segment.
required:
- ExternalId
- Format
- RoleArn
- S3Url
- Size
NotFoundException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
SegmentBehaviors:
type: object
properties:
Recency:
$ref: '#/components/schemas/RecencyDimension'
GetSegmentsRequest:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.
PageSize:
type: string
description: The maximum number of items to include in each page of a paginated response. This parameter is not supported for application, campaign, and journey metrics.
Token:
type: string
description: The NextToken string that specifies which page of results to return in a paginated response.
required:
- ApplicationId
SegmentLocation:
type: object
properties:
Country:
$ref: '#/components/schemas/SetDimension'
GPSPoint:
$ref: '#/components/schemas/GPSPointDimension'
AttributeDimension:
type: object
properties:
AttributeType:
type: string
enum:
- INCLUSIVE
- EXCLUSIVE
- CONTAINS
- BEFORE
- AFTER
- 'ON'
- BETWEEN
description: 'The type of segment dimension to use. Valid values are: INCLUSIVE - endpoints that have attributes matching the values are included in the segment.EXCLUSIVE - endpoints that have attributes matching the values are excluded in the segment.CONTAINS - endpoints that have attributes'' substrings match the values are included in the segment.BEFORE - endpoints with attributes read as ISO_INSTANT datetimes before the value are included in the segment.AFTER - endpoints with attributes read as ISO_INSTANT datetimes after the value are included in the segment.ON - endpoints with attributes read as ISO_IN'
Values:
type: array
items:
type: string
description: The criteria values to use for the segment dimension. Depending on the value of the AttributeType property, endpoints are included or excluded from the segment if their attribute values match the criteria values.
required:
- Values
SegmentDimensions:
type: object
properties:
Attributes:
type: object
additionalProperties:
$ref: '#/components/schemas/AttributeDimension'
description: One or more custom attributes to use as criteria for the segment.
Behavior:
$ref: '#/components/schemas/SegmentBehaviors'
Demographic:
$ref: '#/components/schemas/SegmentDemographics'
Location:
$ref: '#/components/schemas/SegmentLocation'
Metrics:
type: object
additionalProperties:
$ref: '#/components/schemas/MetricDimension'
description: One or more custom metrics to use as criteria for the segment.
UserAttributes:
type: object
additionalProperties:
$ref: '#/components/schemas/AttributeDimension'
description: One or more custom user attributes to use as criteria for the segment.
UpdateSegmentResponse:
type: object
properties:
SegmentResponse:
$ref: '#/components/schemas/SegmentResponse'
required:
- SegmentResponse
SegmentReference:
type: object
properties:
Id:
type: string
description: The unique identifier for the segment.
Version:
type: integer
description: The version number of the segment.
required:
- Id
SegmentDemographics:
type: object
properties:
AppVersion:
$ref: '#/components/schemas/SetDimension'
Channel:
$ref: '#/components/schemas/SetDimension'
DeviceType:
$ref: '#/components/schemas/SetDimension'
Make:
$ref: '#/components/schemas/SetDimension'
Model:
$ref: '#/components/schemas/SetDimension'
Platform:
$ref: '#/components/schemas/SetDimension'
RecencyDimension:
type: object
properties:
Duration:
type: string
enum:
- HR_24
- DAY_7
- DAY_14
- DAY_30
description: The duration to use when determining whether an endpoint is active or inactive.
RecencyType:
type: string
enum:
- ACTIVE
- INACTIVE
description: 'The type of recency dimension to use for the segment. Valid values are: ACTIVE, endpoints that were active within the specified duration are included in the segment; and, INACTIVE, endpoints that weren''t active within the specified duration are included in the segment.'
required:
- Duration
- RecencyType
CreateSegmentRequest:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.
WriteSegmentRequest:
$ref: '#/components/schemas/WriteSegmentRequest'
required:
- ApplicationId
- WriteSegmentRequest
PayloadTooLargeException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
GetSegmentsResponse:
type: object
properties:
SegmentsResponse:
$ref: '#/components/schemas/SegmentsResponse'
required:
- SegmentsResponse
WriteSegmentRequest:
type: object
properties:
Dimensions:
$ref: '#/components/schemas/SegmentDimensions'
Name:
type: string
description: The name of the segment.
SegmentGroups:
$ref: '#/components/schemas/SegmentGroupList'
tags:
type: object
additionalProperties:
type: string
description: As of 22-05-2023 tags has been deprecated for update operations. After this date any value in tags is not processed and an error code is not returned. To manage tags we recommend using either Tags in the API Reference for Amazon Pinpoint, resourcegroupstaggingapi commands in the AWS Command Line Interface Documentation or resourcegroupstaggingapi in the AWS SDK. (Deprecated) A string-to-string map of key-value pairs that defines the tags to associate with the segment. Each tag consists of a required tag key and an associated tag value.
SegmentGroupList:
type: object
properties:
Groups:
type: array
items:
$ref: '#/components/schemas/SegmentGroup'
description: An array that defines the set of segment criteria to evaluate when handling segment groups for the segment.
Include:
type: string
enum:
- ALL
- ANY
- NONE
description: Specifies how to handle multiple segment groups for the segment. For example, if the segment includes three segment groups, whether the resulting segment includes endpoints that match all, any, or none of the segment groups.
GPSCoordinates:
type: object
properties:
Latitude:
type: number
description: The latitude coordinate of the location.
Longitude:
type: number
description: The longitude coordinate of the location.
required:
- Latitude
- Longitude
MethodNotAllowedException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
DeleteSegmentRequest:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.
SegmentId:
type: string
description: The unique identifier for the segment.
required:
- ApplicationId
- SegmentId
SegmentGroup:
type: object
properties:
Dimensions:
type: array
items:
$ref: '#/components/schemas/SegmentDimensions'
description: An array that defines the dimensions for the segment.
SourceSegments:
type: array
items:
$ref: '#/components/schemas/SegmentReference'
description: The base segment to build the segment on. A base segment, also referred to as a source segment, defines the initial population of endpoints for a segment. When you add dimensions to a segment, Amazon Pinpoint filters the base segment by using the dimensions that you specify. You can specify more than one dimensional segment or only one imported segment. If you specify an imported segment, the Amazon Pinpoint console displays a segment size estimate that indicates the size of the imported segment without any filters applied to it.
SourceType:
type: string
enum:
- ALL
- ANY
- NONE
description: Specifies how to handle multiple base segments for the segment. For example, if you specify three base segments for the segment, whether the resulting segment is based on all, any, or none of the base segments.
Type:
type: string
enum:
- ALL
- ANY
- NONE
description: Specifies how to handle multiple dimensions for the segment. For example, if you specify three dimensions for the segment, whether the resulting segment includes endpoints that match all, any, or none of the dimensions.
SegmentResponse:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application that the segment is associated with.
Arn:
type: string
description: The Amazon Resource Name (ARN) of the segment.
CreationDate:
type: string
description: The date and time when the segment was created.
Dimensions:
$ref: '#/components/schemas/SegmentDimensions'
Id:
type: string
description: The unique identifier for the segment.
ImportDefinition:
$ref: '#/components/schemas/SegmentImportResource'
LastModifiedDate:
type: string
description: The date and time when the segment was last modified.
Name:
type: string
description: The name of the segment.
SegmentGroups:
$ref: '#/components/schemas/SegmentGroupList'
SegmentType:
type: string
enum:
- DIMENSIONAL
- IMPORT
description: 'The segment type. Valid values are: DIMENSIONAL - A dynamic segment, which is a segment that uses selection criteria that you specify and is based on endpoint data that''s reported by your app. Dynamic segments can change over time. IMPORT - A static segment, which is a segment that uses selection criteria that you specify and is based on endpoint definitions that you import from a file. Imported segments are static; they don''t change over time.'
tags:
type: object
additionalProperties:
type: string
description: A string-to-string map of key-value pairs that identifies the tags that are associated with the segment. Each tag consists of a required tag key and an associated tag value.
Version:
type: integer
description: The version number of the segment.
required:
- ApplicationId
- Arn
- CreationDate
- Id
- SegmentType
SegmentsResponse:
type: object
properties:
Item:
type: array
items:
$ref: '#/components/schemas/SegmentResponse'
description: An array of responses, one for each segment that's associated with the application (Segments resource) or each version of a segment that's associated with the application (Segment Versions resource).
NextToken:
type: string
description: The string to use in a subsequent request to get the next page of results in a paginated response. This value is null if there are no additional pages.
required:
- Item
GetSegmentRequest:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.
SegmentId:
type: string
description: The unique identifier for the segment.
required:
- ApplicationId
- SegmentId
InternalServerErrorException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
SetDimension:
type: object
properties:
DimensionType:
type: string
enum:
- INCLUSIVE
- EXCLUSIVE
description: 'The type of segment dimension to use. Valid values are: INCLUSIVE, endpoints that match the criteria are included in the segment; and, EXCLUSIVE, endpoints that match the criteria are excluded from the segment.'
Values:
type: array
items:
type: string
description: The criteria values to use for the segment dimension. Depending on the value of the DimensionType property, endpoints are included or excluded from the segment if their values match the criteria values.
required:
- Values
ForbiddenException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
GPSPointDimension:
type: object
properties:
Coordinates:
$ref: '#/components/schemas/GPSCoordinates'
RangeInKilometers:
type: number
description: The range, in kilometers, from the GPS coordinates.
required:
- Coordinates
UpdateSegmentRequest:
type: object
properties:
ApplicationId:
type: string
description: The unique identifier for the application. This identifier is displayed as the Project ID on the Amazon Pinpoint console.
SegmentId:
type: string
description: The unique identifier for the segment.
WriteSegmentRequest:
$ref: '#/components/schemas/WriteSegmentRequest'
required:
- ApplicationId
- SegmentId
- WriteSegmentRequest
MetricDimension:
type: object
properties:
ComparisonOperator:
type: string
description: 'The operator to use when comparing metric values. Valid values are: GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, and EQUAL.'
Value:
type: number
description: The value to compare.
required:
- ComparisonOperator
- Value
TooManyRequestsException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
DeleteSegmentResponse:
type: object
properties:
SegmentResponse:
$ref: '#/components/schemas/SegmentResponse'
required:
- SegmentResponse
BadRequestException:
type: object
properties:
Message:
type: string
description: The message that's returned from the API.
RequestID:
type: string
description: The unique identifier for the request or response.
CreateSegmentResponse:
type: object
properties:
SegmentResponse:
$ref: '#/components/schemas/SegmentResponse'
required:
- SegmentResponse
securitySchemes:
sigv4:
type: apiKey
in: header
name: Authorization
description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
x-aws-sigv4:
signingName: mobiletargeting
x-provenance:
method: harvested
publisher: Amazon Web Services
source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/pinpoint/service/2016-12-01/pinpoint-2016-12-01.json
note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)