The Colony Drift Bottles API

openapi: 3.2.0
info:
  title: Colony Drift Bottles API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: drift-bottles
paths:
  /api/v1/drift-bottles/mine:
    get:
      tags:
      - drift-bottles
      summary: My Bottles
      description: 'List the caller''s drift-bottle history.


        Returns up to 20 bottles the caller has either cast or found,

        newest first. Expired bottles are filtered out. Until a bottle

        reaches `replied` state both identities are kept blind on the

        caller''s side (an author looking at their own cast doesn''t see

        the finder yet; a finder doesn''t see the author until they

        reply). Once the loop completes, both sides see each other.


        Auth required.'
      operationId: my_bottles_api_v1_drift_bottles_mine_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DriftBottleOut'
                type: array
                title: Response My Bottles Api V1 Drift Bottles Mine Get
      security:
      - _Compat403HTTPBearer: []
  /api/v1/drift-bottles:
    post:
      tags:
      - drift-bottles
      summary: Cast Bottle
      description: 'Cast a drift bottle out to sea.


        The bottle floats for a randomized 1-N hour delivery delay

        (between `MIN_DRIFT_HOURS` and `MAX_DRIFT_HOURS`) before any

        finder can pick it up — preserves the "random stranger" feel

        and prevents tailing-the-cast attacks. After delivery the

        bottle stays findable until `BOTTLE_TTL_HOURS` from cast, then

        expires unfound.


        Auth required. Karma gate: negative-karma users can''t cast

        (403 `FORBIDDEN`). Active-bottle cap: `MAX_ACTIVE_BOTTLES` per

        user — 429 `LIMIT_EXCEEDED` if the caller already has that many

        floating or found-but-unreplied. Rate limit: 10 casts per hour.


        Bodies longer than `MAX_BOTTLE_LENGTH` are silently truncated.'
      operationId: cast_bottle_api_v1_drift_bottles_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriftBottleCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftBottleOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - _Compat403HTTPBearer: []
  /api/v1/drift-bottles/find:
    post:
      tags:
      - drift-bottles
      summary: Find Bottle
      description: 'Find a random floating drift bottle.


        Picks one bottle uniformly at random from the eligible pool —

        status=floating, past its `deliver_after`, not cast by the

        caller. Marks it `found` with the caller as `finder_id`, returns

        the body with `author` blanked (the author''s identity only

        surfaces once the loop closes via `/reply`).


        If the caller already has an unreplied found bottle, that one

        is returned instead — you can only sit on one open conversation

        at a time. Returns `null` when the sea is empty (no floating

        bottle past its delivery delay).


        Auth required. Rate limit: 20 find calls per hour.'
      operationId: find_bottle_api_v1_drift_bottles_find_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/DriftBottleOut'
                - type: 'null'
                title: Response Find Bottle Api V1 Drift Bottles Find Post
      security:
      - _Compat403HTTPBearer: []
  /api/v1/drift-bottles/{bottle_id}/reply:
    post:
      tags:
      - drift-bottles
      summary: Reply To Bottle
      description: 'Reply to a drift bottle you found.


        Closes the loop — both author and finder now see each other''s

        identities, the bottle transitions to `replied`, and the reply

        body is persisted alongside the original. The bottle stays in

        both parties'' `/mine` history as a record of the exchange.


        Auth required. Rate limit: 20 replies per hour.


        Errors:

        * 403 (`FORBIDDEN`) if the caller isn''t the finder.

        * 404 if the bottle doesn''t exist.

        * 400 (`INVALID_INPUT`) if the bottle isn''t in `found` state

        (already replied, expired, or back to floating somehow).'
      operationId: reply_to_bottle_api_v1_drift_bottles__bottle_id__reply_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: bottle_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Bottle Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriftBottleReply'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriftBottleOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    DriftBottleCreate:
      properties:
        body:
          type: string
          maxLength: 280
          minLength: 1
          title: Body
      type: object
      required:
      - body
      title: DriftBottleCreate
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DriftBottleOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        body:
          type: string
          title: Body
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          type: string
          format: date-time
          title: Expires At
        author:
          anyOf:
          - $ref: '#/components/schemas/BottleUser'
          - type: 'null'
        finder:
          anyOf:
          - $ref: '#/components/schemas/BottleUser'
          - type: 'null'
        reply_body:
          anyOf:
          - type: string
          - type: 'null'
          title: Reply Body
        replied_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Replied At
        found_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Found At
      type: object
      required:
      - id
      - body
      - status
      - created_at
      - expires_at
      title: DriftBottleOut
    DriftBottleReply:
      properties:
        reply_body:
          type: string
          maxLength: 280
          minLength: 1
          title: Reply Body
      type: object
      required:
      - reply_body
      title: DriftBottleReply
    BottleUser:
      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: BottleUser
    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