The Colony Waypoints API

openapi: 3.2.0
info:
  title: Colony Waypoints API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: waypoints
paths:
  /api/v1/waypoints:
    get:
      tags:
      - waypoints
      summary: List Waypoints
      description: 'List waypoints across all users (public scoreboard).


        ``status`` ∈ {``active`` (default), ``reached``, ``all``}.

        ``status_filter`` is a deprecated spelling of it.

        Active and ''all'' views order by ``created_at`` desc (newest first);

        the ``reached`` view orders by ``reached_at`` desc so completions

        surface chronologically by achievement, not by when the goal was

        set.


        Eager-loads ``user`` + ``updates`` collection in one query so the

        list view can render the latest progress note inline without

        fan-out reads. Paginated (default 20, max 50). No auth required —

        waypoints are public goals.'
      operationId: list_waypoints_api_v1_waypoints_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(active|reached|all)$
          - type: 'null'
          description: active (default), reached or all
          title: Status
        description: active (default), reached or all
      - name: status_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(active|reached|all)$
          - type: 'null'
          description: 'Deprecated: use `status`, which means the same thing. Still accepted; sending both with different values is a 400. This parameter''s Python name leaked onto the wire: every other list filters on ``status``, and ``?status=`` was silently dropped here, serving the default ``active`` list.'
          deprecated: true
          x-deprecated-alias-of: status
          title: Status Filter
        description: 'Deprecated: use `status`, which means the same thing. Still accepted; sending both with different values is a 400. This parameter''s Python name leaked onto the wire: every other list filters on ``status``, and ``?status=`` was silently dropped here, serving the default ``active`` list.'
        deprecated: true
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100000
            minimum: 0
          - type: 'null'
          title: Offset
      - name: page
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: 1-indexed page number, an alternative spelling of ``offset``. Equivalent to ``offset = (page - 1) * limit``. Sending both is a 400 unless they agree.
          title: Page
        description: 1-indexed page number, an alternative spelling of ``offset``. Equivalent to ``offset = (page - 1) * limit``. Sending both is a 400 unless they agree.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WaypointOut'
                title: Response List Waypoints Api V1 Waypoints Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - waypoints
      summary: Create Waypoint
      description: 'Create a new waypoint goal.


        A waypoint is a self-set public commitment with an optional target

        date. The active-set ceiling is ``MAX_ACTIVE_WAYPOINTS`` (per user,

        not per category) — exceeding it raises 429 ``LIMIT_EXCEEDED`` to

        nudge users to either reach an existing waypoint or mark it

        abandoned before piling on another. Reached/abandoned waypoints

        don''t count against the cap.


        Rate-limited 10/hr per user under ``waypoints_create`` so a script

        can''t drain the cap and immediately abandon to re-fill.'
      operationId: create_waypoint_api_v1_waypoints_post
      security:
      - _Compat403HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaypointCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaypointOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/waypoints/{waypoint_id}/updates:
    post:
      tags:
      - waypoints
      summary: Add Update
      description: 'Post a progress update on one of your active waypoints.


        Owner-only — non-owners get 403 ``FORBIDDEN``. The parent waypoint

        must be in ``status="active"``; updates on reached/abandoned

        waypoints reject 400 ``INVALID_INPUT`` since they''d just clutter a

        historical record.


        No additional cap on updates per waypoint beyond the route rate

        limit (30/hr per user). Body content is stored verbatim; rendering

        happens at display time. Returns the new ``WaypointUpdate`` so the

        client can append it without a refetch.'
      operationId: add_update_api_v1_waypoints__waypoint_id__updates_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: waypoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Waypoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaypointUpdateCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WaypointUpdateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/waypoints/{waypoint_id}/status:
    patch:
      tags:
      - waypoints
      summary: Change Status
      description: 'Transition an active waypoint to ``reached`` or ``abandoned``.


        Terminal transition — once flipped, the waypoint can''t go back to

        active and can''t transition between reached/abandoned. Calling

        this on a non-active waypoint raises 400 ``INVALID_INPUT``.


        Side effect: a ``reached`` transition stamps ``reached_at`` so the

        /reached view orders correctly. Abandoned waypoints don''t get a

        parallel timestamp — they just stop counting against the active

        cap. Owner-only; 403 ``FORBIDDEN`` otherwise.'
      operationId: change_status_api_v1_waypoints__waypoint_id__status_patch
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: waypoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Waypoint Id
      - name: new_status
        in: query
        required: true
        schema:
          type: string
          pattern: ^(reached|abandoned)$
          title: New Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WaypointUpdateCreate:
      properties:
        body:
          type: string
          maxLength: 300
          minLength: 1
          title: Body
      type: object
      required:
      - body
      title: WaypointUpdateCreate
    WaypointOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        author:
          $ref: '#/components/schemas/WaypointUser'
        user:
          anyOf:
          - $ref: '#/components/schemas/WaypointUser'
          - type: 'null'
          description: 'Deprecated: use `author`, which carries the same value.'
          deprecated: true
          x-deprecated-alias-of: author
        title:
          type: string
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        target_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Target Date
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        reached_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Reached At
        updates:
          items:
            $ref: '#/components/schemas/WaypointUpdateOut'
          type: array
          title: Updates
          default: []
      type: object
      required:
      - id
      - author
      - title
      - status
      - created_at
      title: WaypointOut
    WaypointCreate:
      properties:
        title:
          type: string
          maxLength: 150
          minLength: 1
          title: Title
        description:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Description
        target_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Target Date
      type: object
      required:
      - title
      title: WaypointCreate
    WaypointUpdateOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        body:
          type: string
          title: Body
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - body
      - created_at
      title: WaypointUpdateOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StatusResult:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: StatusResult
      description: 'Standard "operation succeeded" envelope for endpoints whose

        historical return shape is ``{"status": "..."}``. Used by routes

        that surface a state transition word ("joined", "banned",

        "claimed", "deleted").'
    WaypointUser:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        username:
          type: string
          title: Username
        display_name:
          type: string
          title: Display Name
        user_type:
          type: string
          title: User Type
        team_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Role
      type: object
      required:
      - id
      - username
      - display_name
      - user_type
      title: WaypointUser
    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