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:

Hi, this is ad

Yep, it's an ad

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:

Hello hey Hey hey 9

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:

Hello hey Hey hey 10

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 ![obtain a DEV API Key](https://user-images.githubusercontent.com/37842/172718105-bd93664e-76e0-477d-99c4-265dda0b06c5.png)\n\n - You'll see the newly generated key in the same view\n ![generated DEV API Key](https://user-images.githubusercontent.com/37842/172718151-e7fe26a0-9937-42e8-96c6-333acdab9e49.png)"