openapi: 3.2.0 info: title: Forem API V1 Events API version: 1.0.0 description: Access Forem articles, users and other resources via API. servers: - url: https://dev.to description: Production server security: - api-key: [] - bearer_auth: [] tags: - name: Events paths: /api/events: get: summary: Retrieve events tags: - Events security: [] description: 'Retrieve a list of events on the platform. ### Query Parameters: - **type_of**: Filter events by their type (`live_stream`, `takeover`, `other`, `challenge`).' operationId: getEvents parameters: - name: type_of in: query required: false description: Filter events by type. schema: type: string enum: - live_stream - takeover - other - challenge responses: '200': description: A list of events content: application/json: schema: type: array items: $ref: '#/components/schemas/Event' post: summary: Create an event tags: - Events description: Create a new event. Requires administrator privileges. operationId: createEvent parameters: [] responses: '201': description: Event created content: application/json: schema: $ref: '#/components/schemas/Event' requestBody: content: application/json: schema: $ref: '#/components/schemas/EventInput' description: Event parameters to create. /api/events/{id}: get: summary: Retrieve an event tags: - Events security: [] description: Retrieve a single event by ID. operationId: getEventById parameters: - name: id in: path required: true description: ID of the event. schema: type: integer responses: '200': description: The requested event content: application/json: schema: $ref: '#/components/schemas/Event' patch: summary: Update an event tags: - Events description: Update an existing event. Requires administrator privileges. operationId: updateEvent parameters: - name: id in: path required: true description: ID of the event to update. schema: type: integer responses: '200': description: Event updated content: application/json: schema: $ref: '#/components/schemas/Event' requestBody: content: application/json: schema: $ref: '#/components/schemas/EventInput' description: Event parameters to update. delete: summary: Delete an event tags: - Events description: Delete an event. Requires administrator privileges. operationId: deleteEvent parameters: - name: id in: path required: true description: ID of the event to delete. schema: type: integer responses: '204': description: Event deleted components: schemas: EventInput: description: Representation of an Event to be created/updated type: object properties: event: type: object properties: title: type: string event_name_slug: type: string event_variation_slug: type: string description: type: - string - 'null' full_details: type: - string - 'null' description: Full text dump of all event details. primary_stream_url: type: - string - 'null' published: type: boolean default: false start_time: type: string format: date-time end_time: type: string format: date-time type_of: type: string enum: - live_stream - takeover - other - challenge organization_id: type: - integer - 'null' tag_list: type: - string - 'null' data: type: - object - 'null' required: - title - event_name_slug - event_variation_slug - start_time - end_time required: - event Event: description: Representation of an event type: object properties: id: type: integer format: int64 title: type: string event_name_slug: type: string event_variation_slug: type: string description: type: - string - 'null' full_details: type: - string - 'null' description: Full text dump of all event details, intended for agent and API consumption. type_of: type: string enum: - live_stream - takeover - other - challenge start_time: type: string format: date-time end_time: type: string format: date-time published: type: boolean primary_stream_url: type: - string - 'null' bg_color_hex: type: - string - 'null' broadcast_config: type: string enum: - no_broadcast - tagged_broadcast - global_broadcast broadcast_ended_at: type: - string - 'null' format: date-time user_id: type: - integer - 'null' format: int64 organization_id: type: - integer - 'null' format: int64 page_id: type: - integer - 'null' format: int64 data: type: - object - 'null' tags_array: type: array items: type: string cached_tag_list: type: - string - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - title - event_name_slug - event_variation_slug - type_of - start_time - end_time - published - created_at - updated_at 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)" bearer_auth: type: http scheme: bearer bearerFormat: JWT description: Short-lived RS256 RFC 9068 access token issued by the configured delegation service and verified against its configured JWKS. The issuer authorizes the client and requested operation before minting the token; Forem validates the token and resolves its subject and owner to a local user. An invalid token returns 401; an unavailable trust dependency with no usable cached key returns 503.