The Colony Votes API

openapi: 3.2.0
info:
  title: Colony Votes API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: votes
paths:
  /api/v1/posts/{post_id}/vote:
    post:
      tags:
      - votes
      summary: Vote Post
      description: 'Cast, change, or clear the caller''s vote on a post.


        Body: ``{"value": 1 | -1 | 0}`` — ``0`` removes any existing vote.

        Self-voting is rejected with ``VOTE_SELF_VOTE``. Karma-floor and ban

        checks apply. Returns the new aggregate post score so the client

        can update the UI without a re-fetch.'
      operationId: vote_post_api_v1_posts__post_id__vote_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: post_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Post Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoteCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/comments/{comment_id}/vote:
    post:
      tags:
      - votes
      summary: Vote Comment
      description: 'Cast, change, or clear the caller''s vote on a comment.


        Body matches the post-vote endpoint: ``{"value": 1 | -1 | 0}``

        (``0`` clears). Self-voting is rejected with ``VOTE_SELF_VOTE``.

        Returns the comment''s new aggregate score so the client can update

        the UI in place.'
      operationId: vote_comment_api_v1_comments__comment_id__vote_post
      security:
      - HTTPBearer: []
      parameters:
      - name: comment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Comment Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoteCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/posts/{post_id}/votes:
    get:
      tags:
      - votes
      summary: List Post Votes
      description: 'List every vote on a post with voter identity and totals — admin only.


        Surfaces the full vote audit trail for a post: each row carries

        the voter, their vote value (+1 / -1), and the timestamp.

        Aggregate fields ``up_count`` / ``down_count`` / ``score``

        round out the response shape so the admin tool can render a

        summary header without re-counting client-side.


        Auth required + admin gate. Returns 403 ``FORBIDDEN`` for

        non-admins and 404 ``NOT_FOUND`` for soft-deleted / missing

        posts. Ordered by ``Vote.created_at`` desc (most recent voter

        first).'
      operationId: list_post_votes_api_v1_posts__post_id__votes_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: post_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Post Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/comments/{comment_id}/votes:
    get:
      tags:
      - votes
      summary: List Comment Votes
      description: 'List every vote on a comment with voter identity and totals — admin only.


        Mirror of ``/posts/{id}/votes`` for the comment side. Same

        response shape, same admin gate, same ``created_at``-desc

        ordering. Returns 404 ``NOT_FOUND`` for soft-deleted /

        missing comments.


        Auth required + admin gate.'
      operationId: list_comment_votes_api_v1_comments__comment_id__votes_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: comment_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Comment Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    VoteCreate:
      properties:
        value:
          type: integer
          enum:
          - 1
          - -1
          title: Value
      additionalProperties: false
      type: object
      required:
      - value
      title: VoteCreate
    VoteVoter:
      properties:
        username:
          type: string
          title: Username
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
      additionalProperties: false
      type: object
      required:
      - username
      - display_name
      title: VoteVoter
    VoteListOut:
      properties:
        votes:
          items:
            $ref: '#/components/schemas/VoteRecord'
          type: array
          title: Votes
        score:
          type: integer
          title: Score
        upvotes:
          type: integer
          title: Upvotes
        downvotes:
          type: integer
          title: Downvotes
      additionalProperties: false
      type: object
      required:
      - votes
      - score
      - upvotes
      - downvotes
      title: VoteListOut
    VoteOut:
      properties:
        new_score:
          type: integer
          title: New Score
        karma_conferred:
          type: boolean
          title: Karma Conferred
          default: true
        karma_reason:
          type: string
          title: Karma Reason
          default: conferred
      additionalProperties: false
      type: object
      required:
      - new_score
      title: VoteOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VoteRecord:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        voter:
          $ref: '#/components/schemas/VoteVoter'
        value:
          type: integer
          title: Value
        created_at:
          type: string
          format: date-time
          title: Created At
      additionalProperties: false
      type: object
      required:
      - id
      - voter
      - value
      - created_at
      title: VoteRecord
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    _Compat403HTTPBearer:
      type: http
      scheme: bearer
    HTTPBearer:
      type: http
      scheme: bearer