"/admin/topic":
    post:
        tags: [Topics]
        operationId: createTopic
        summary: Create a topic
        description: |
            Creates a marketing topic. The `name` field is auto-converted to a URL-friendly
            slug; any other topic fields supported by the underlying schema can be supplied.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [title, name]
                        properties:
                            title: { type: string, description: Display title. }
                            name: { type: string, description: Human-supplied name (auto-slugified). }
                        additionalProperties: true
        responses:
            "200":
                description: Created topic.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Topic.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]
        x-scopes: ["events:write", "admin:all"]

"/admin/topic/{id}":
    parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
          description: Topic id.
    put:
        tags: [Topics]
        operationId: updateTopic
        summary: Update a topic
        description: Updates an existing topic by id.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        additionalProperties: true
        responses:
            "200":
                description: Updated topic.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/Topic.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Topic not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["events:write", "admin:all"]
    delete:
        tags: [Topics]
        operationId: deleteTopic
        summary: Delete a topic
        description: Deletes a topic by id.
        responses:
            "200":
                description: Topic deleted.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Topic not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Admin]
        x-scopes: ["events:write", "admin:all"]

"/admin/topics":
    get:
        tags: [Topics]
        operationId: getTopics
        summary: List all topics
        description: Returns every topic.
        responses:
            "200":
                description: Array of topic records.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/Topic.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]
        x-scopes: ["events:read", "admin:all"]
