DEV Community segments API
The segments API from DEV Community — 5 operation(s) for segments.
OpenAPI Specification
openapi: 3.0.3
info:
title: Forem API V1 agent_sessions segments API
version: 1.0.0
description: "Access Forem articles, users and other resources via API.\n For a real-world example of Forem in action, check out [DEV](https://www.dev.to).\n All endpoints can be accessed with the 'api-key' header and a accept header, but\n some of them are accessible publicly without authentication.\n\n Dates and date times, unless otherwise specified, must be in\n the [RFC 3339](https://tools.ietf.org/html/rfc3339) format."
servers:
- url: https://dev.to/api
description: Production server
security:
- api-key: []
tags:
- name: segments
paths:
/api/segments:
get:
summary: Manually managed audience segments
tags:
- segments
description: 'This endpoint allows the client to retrieve a list of audience segments.
An audience segment is a group of users that can be targeted by a Billboard. This API only permits managing segments you create and maintain yourself.
The endpoint supports pagination, and each page will contain `30` segments by default.'
operationId: getSegments
parameters:
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
'200':
description: A List of manually managed audience segments
content:
application/json:
example:
- id: 34
created_at: '2026-05-28T12:45:19.104-06:00'
name: null
type_of: manual
updated_at: '2026-05-28T12:45:19.104-06:00'
user_count: 1
- id: 33
created_at: '2026-05-28T12:45:19.016-06:00'
name: null
type_of: manual
updated_at: '2026-05-28T12:45:19.016-06:00'
user_count: 3
schema:
type: array
items:
$ref: '#/components/schemas/Segment'
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
post:
summary: Create a manually managed audience segment
tags:
- segments
description: 'This endpoint allows the client to create a new audience segment.
An audience segment is a group of users that can be targeted by a Billboard. This API only permits managing segments you create and maintain yourself.'
operationId: createSegment
responses:
'201':
description: A manually managed audience segment
content:
application/json:
example:
id: 35
created_at: '2026-05-28T12:45:19.421-06:00'
name: null
type_of: manual
updated_at: '2026-05-28T12:45:19.421-06:00'
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
/api/segments/{id}:
get:
summary: A manually managed audience segment
tags:
- segments
description: This endpoint allows the client to retrieve a single manually-managed audience segment specified by ID.
operationId: getSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
minimum: 1
responses:
'200':
description: The audience segment
content:
application/json:
example:
id: 36
created_at: '2026-05-28T12:45:19.625-06:00'
name: null
type_of: manual
updated_at: '2026-05-28T12:45:19.625-06:00'
user_count: 3
schema:
type: object
items:
$ref: '#/components/schemas/Segment'
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Audience Segment Not Found
content:
application/json:
example:
error: not found
status: 404
delete:
summary: Delete a manually managed audience segment
tags:
- segments
description: 'This endpoint allows the client to delete an audience segment specified by ID.
Audience segments cannot be deleted if there are still any Billboards using them.'
operationId: deleteSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
minimum: 1
responses:
'200':
description: The deleted audience segment
content:
application/json:
example:
id: 40
created_at: '2026-05-28T12:45:20.004-06:00'
name: null
type_of: manual
updated_at: '2026-05-28T12:45:20.004-06:00'
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Audience Segment Not Found
content:
application/json:
example:
error: not found
status: 404
'409':
description: Audience segment could not be deleted
content:
application/json:
example:
error: Segments cannot be deleted while in use by any billboards
/api/segments/{id}/users:
get:
summary: Users in a manually managed audience segment
tags:
- segments
description: This endpoint allows the client to retrieve a list of the users in an audience segment specified by ID. The endpoint supports pagination, and each page will contain `30` users by default.
operationId: getUsersInSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
minimum: 1
- $ref: '#/components/parameters/perPageParam30to1000'
responses:
'200':
description: A List of users in the audience segment
content:
application/json:
example:
- type_of: user
id: 4109
username: username61
name: Erminia "Pedro" \:/ Turcotte
twitter_username: twitter61
github_username: github61
summary: null
location: null
website_url: null
joined_at: May 28, 2026
profile_image: /uploads/user/profile_image/4109/6812d241-6f58-4837-885e-56a5c1a1cac7.jpeg
- type_of: user
id: 4110
username: username62
name: Perry "Jazmin" \:/ Harvey
twitter_username: twitter62
github_username: github62
summary: null
location: null
website_url: null
joined_at: May 28, 2026
profile_image: /uploads/user/profile_image/4110/66331066-af5b-44d8-bf8c-5a3787ecbfa2.jpeg
- type_of: user
id: 4111
username: username63
name: Kristofer "Ruth" \:/ Graham
twitter_username: twitter63
github_username: github63
summary: null
location: null
website_url: null
joined_at: May 28, 2026
profile_image: /uploads/user/profile_image/4111/1536d24e-ea86-4abf-bbac-d0eef3b4ebbd.jpeg
schema:
type: array
items:
$ref: '#/components/schemas/User'
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Audience Segment Not Found
content:
application/json:
example:
error: not found
status: 404
/api/segments/{id}/add_users:
put:
summary: Add users to a manually managed audience segment
tags:
- segments
description: 'This endpoint allows the client to add users in bulk to an audience segment specified by ID.
Successes are users that were included in the segment (even if they were already in it), and failures are users that could not be added to the segment.'
operationId: addUsersToSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
minimum: 1
responses:
'200':
description: Result of adding the users to the segment.
content:
application/json:
example:
succeeded:
- 4117
- 4118
- 4119
failed: []
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Audience Segment Not Found
content:
application/json:
example:
error: not found
status: 404
'422':
description: Unprocessable Entity
content:
application/json:
example:
error: 'param is missing or the value is empty: user_ids'
status: 422
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentUserIds'
/api/segments/{id}/remove_users:
put:
summary: Remove users from a manually managed audience segment
tags:
- segments
description: 'This endpoint allows the client to remove users in bulk from an audience segment specified by ID.
Successes are users that were removed; failures are users that weren''t a part of the segment.'
operationId: removeUsersFromSegment
parameters:
- name: id
in: path
required: true
schema:
type: integer
format: int32
minimum: 1
responses:
'200':
description: Result of removing the users to the segment.
content:
application/json:
example:
succeeded:
- 4136
- 4137
- 4138
failed: []
'401':
description: Unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Audience Segment Not Found
content:
application/json:
example:
error: not found
status: 404
'422':
description: Unprocessable Entity
content:
application/json:
example:
error: 'param is missing or the value is empty: user_ids'
status: 422
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentUserIds'
components:
schemas:
Segment:
description: A manually managed audience segment
type: object
properties:
id:
type: integer
description: The ID of the segment
type_of:
type: string
enum:
- manual
default: manual
description: Marks the segment as manually managed (other types are internal)
user_count:
type: integer
description: The current number of users in the segment
User:
description: The representation of a user returned in a list
type: object
properties:
type_of:
type: string
id:
type: integer
format: int64
username:
type: string
name:
type: string
summary:
type: string
nullable: true
twitter_username:
type: string
github_username:
type: string
website_url:
type: string
nullable: true
location:
type: string
nullable: true
joined_at:
type: string
profile_image:
type: string
SegmentUserIds:
type: object
properties:
user_ids:
type: array
items:
type: integer
maxItems: 10000
parameters:
perPageParam30to1000:
in: query
name: per_page
required: false
description: Page size (the number of items to return per page). The default maximum value can be overridden by "API_PER_PAGE_MAX" environment variable.
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 30
securitySchemes:
api-key:
type: apiKey
name: api-key
in: header
description: "API Key authentication.\n\nAuthentication for some endpoints, like write operations on the\nArticles API require a DEV API key.\n\nAll authenticated endpoints are CORS disabled, the API key is intended for non-browser scripts.\n\n### Getting an API key\n\nTo obtain one, please follow these steps:\n\n - visit https://dev.to/settings/extensions\n - in the \"DEV API Keys\" section create a new key by adding a\n description and clicking on \"Generate API Key\"\n\n \n\n - You'll see the newly generated key in the same view\n "