DEV Community display ads API
The display ads API from DEV Community — 3 operation(s) for display ads.
OpenAPI Specification
openapi: 3.0.3
info:
title: Forem API V1 agent_sessions display ads 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: display ads
paths:
/display_ads:
get:
summary: display ads
tags:
- display ads
description: This endpoint allows the client to retrieve a list of all display ads.
responses:
'200':
description: successful
content:
application/json:
example: []
schema:
type: array
items:
$ref: '#/components/schemas/DisplayAd'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
post:
summary: display ads
tags:
- display ads
description: This endpoint allows the client to create a new display ad.
parameters: []
responses:
'200':
description: successful
content:
application/json:
example:
id: 193
approved: true
body_markdown: '# Hi, this is ad
Yep, it''s an ad'
cached_tag_list: ''
clicks_count: 0
created_at: '2023-04-14T18:45:35.606+04:00'
creator_id: null
display_to: all
exclude_article_ids: ''
impressions_count: 0
name: Example Ad
organization_id: null
placement_area: post_comments
processed_html: <h1> <a href="#hi-this-is-ad" class="anchor"> </a> Hi, this is ad</h1><p>Yep, it's an ad</p>
published: true
success_rate: 0
type_of: in_house
updated_at: '2023-04-14T18:45:35.606+04:00'
audience_segment_type: null
tag_list: ''
schema:
type: object
items:
$ref: '#/components/schemas/DisplayAd'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'422':
description: unprocessable
content:
application/json:
example:
id: null
approved: true
body_markdown: '# Hi, this is ad
Yep, it''s an ad'
cached_tag_list: null
clicks_count: 0
created_at: null
creator_id: null
display_to: all
exclude_article_ids: ''
impressions_count: 0
name: Example Ad
organization_id: null
placement_area: moon
processed_html: null
published: true
success_rate: 0
type_of: in_house
updated_at: null
audience_segment_type: null
tag_list: null
requestBody:
content:
application/json:
schema:
type: object
items:
$ref: '#/components/schemas/DisplayAd'
/display_ads/{id}:
get:
summary: display ad
tags:
- display ads
description: This endpoint allows the client to retrieve a single display ad, via its id.
parameters:
- name: id
in: path
required: true
description: The ID of the display ad.
schema:
type: integer
format: int32
minimum: 1
example: 123
responses:
'200':
description: successful
content:
application/json:
example:
id: 196
approved: false
body_markdown: Hello _hey_ Hey hey 9
cached_tag_list: ''
clicks_count: 0
created_at: '2023-04-14T18:45:35.813+04:00'
creator_id: null
display_to: all
exclude_article_ids: ''
impressions_count: 0
name: Display Ad 196
organization_id: 304
placement_area: sidebar_left
processed_html: <p>Hello <em>hey</em> Hey hey 9</p>
published: false
success_rate: 0
type_of: in_house
updated_at: '2023-04-14T18:45:35.817+04:00'
audience_segment_type: null
tag_list: ''
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: Unknown DisplayAd ID
content:
application/json:
example:
error: not found
status: 404
put:
summary: display ads
tags:
- display ads
description: This endpoint allows the client to update the attributes of a single display ad, via its id.
parameters:
- name: id
in: path
required: true
description: The ID of the display ad.
schema:
type: integer
format: int32
minimum: 1
example: 123
responses:
'200':
description: successful
content:
application/json:
example:
approved: false
body_markdown: Hello _hey_ Hey hey 10
creator_id: null
display_to: all
name: Display Ad 198
organization_id: 306
placement_area: sidebar_left
published: false
type_of: in_house
exclude_article_ids: ''
cached_tag_list: ''
id: 198
clicks_count: 0
created_at: '2023-04-14T18:45:36.047+04:00'
impressions_count: 0
processed_html: <p>Hello <em>hey</em> Hey hey 10</p>
success_rate: 0
updated_at: '2023-04-14T18:45:36.051+04:00'
audience_segment_type: null
tag_list: ''
schema:
type: object
items:
$ref: '#/components/schemas/DisplayAd'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: not found
content:
application/json:
example:
error: not found
status: 404
requestBody:
content:
application/json:
schema:
type: object
items:
$ref: '#/components/schemas/DisplayAd'
/display_ads/{id}/unpublish:
put:
summary: unpublish
tags:
- display ads
description: This endpoint allows the client to remove a display ad from rotation by un-publishing it.
parameters:
- name: id
in: path
required: true
description: The ID of the display ad to unpublish.
schema:
type: integer
format: int32
minimum: 1
example: 123
responses:
'204':
description: no content
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: not found
content:
application/json:
example:
error: not found
status: 404
components:
schemas:
DisplayAd:
description: A Display Ad, aka Billboard, aka Widget
type: object
properties:
id:
type: integer
description: The ID of the Display Ad
name:
type: string
description: For internal use, helps distinguish ads from one another
body_markdown:
type: string
description: The text (in markdown) of the ad (required)
approved:
type: boolean
description: Ad must be both published and approved to be in rotation
published:
type: boolean
description: Ad must be both published and approved to be in rotation
organization_id:
type: integer
description: Identifies the organization to which the ad belongs
nullable: true
creator_id:
type: integer
description: Identifies the user who created the ad.
nullable: true
placement_area:
type: string
enum:
- sidebar_left
- sidebar_left_2
- sidebar_right
- feed_first
- feed_second
- feed_third
- post_sidebar
- post_comments
description: Identifies which area of site layout the ad can appear in
tag_list:
type: string
description: Tags on which this ad can be displayed (blank is all/any tags)
article_exclude_ids:
type: string
nullable: true
description: Articles this ad should *not* appear on (blank means no articles are disallowed, and this ad can appear next to any/all articles). Comma-separated list of integer Article IDs
audience_segment_type:
type: string
enum:
- testing
- trusted
- posted
- no_posts_yet
- dark_theme
- light_theme
- no_experience
- experience1
- experience2
- experience3
- experience4
- experience5
description: Specifies an group of users to show this ad to (only works with logged-in users)
display_to:
type: string
enum:
- all
- logged_in
- logged_out
default: all
description: Potentially limits visitors to whom the ad is visible
type_of:
type: string
enum:
- in_house
- community
- external
default: in_house
description: 'Types of the billboards:
in_house (created by admins),
community (created by an entity, appears on entity''s content),
external ( created by an entity, or a non-entity, can appear everywhere)
'
required:
- name
- body_markdown
- placement_area
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 "