Cherished Book Contributions API

openapi: 3.2.0
info:
  title: Cherishedbook Com Contributions API
  version: 2.2.0
  description: 'Operations tagged Contributions across 2 of this provider''s published API definitions: public.yaml, cherishedbook-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
- url: https://app.cherishedbook.com/api/v1
  description: Absolute base stated in https://www.cherishedbook.com/llms.txt (POST https://app.cherishedbook.com/api/v1/auth/device)
security:
- bearerAuth: []
tags:
- name: Contributions
paths:
  /contributions/{contribution}/approve:
    post:
      summary: Publish what someone wrote
      description: Publish something written on one of your memorials. Refused for anything the safety check flagged, and for those still awaiting the writer's email confirmation — the same two limits that apply on the website.
      operationId: approveContribution
      parameters:
      - in: path
        name: contribution
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contribution'
        '404':
          description: Not on a memorial you look after
        '422':
          description: Cannot be published
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                properties:
                  code:
                    type: string
                    enum:
                    - blocked_by_safety_check
                    - awaiting_verification
                  message:
                    type: string
      tags:
      - Contributions
    servers:
    - url: /api/v1
  /contributions/{contribution}:
    delete:
      summary: Hide what someone wrote
      description: 'Hide something someone wrote from their book. Recoverable: it can be restored. Because this concerns something a grieving person wrote, confirm with the memorial''s owner before doing it.'
      operationId: hideContribution
      parameters:
      - in: path
        name: contribution
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Hidden
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - hidden
                - message
                properties:
                  id:
                    type: integer
                  hidden:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Not on a memorial you look after
      tags:
      - Contributions
    servers:
    - url: /api/v1
  /contributions/{contribution}/reject:
    post:
      summary: Reject what someone wrote
      description: Mark it as rejected so it stays out of their book, optionally recording why.
      operationId: rejectContribution
      parameters:
      - in: path
        name: contribution
        required: true
        schema:
          type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contribution'
        '404':
          description: Not on a memorial you look after
      tags:
      - Contributions
    servers:
    - url: /api/v1
  /contributions/{contribution}/pin:
    post:
      summary: Pin something to the top of their book
      description: 'Puts it in the pinned band at the top of their book. It must be approved first: pinning something still being safety-checked would place it at the top the moment it passed, without anyone choosing that.'
      operationId: pinContribution
      tags:
      - Contributions
      parameters:
      - name: contribution
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Pinned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinState'
        '401':
          description: Missing or invalid token
        '422':
          description: Not approved yet.
    servers:
    - url: /api/v1
  /contributions/{contribution}/unpin:
    post:
      summary: Unpin something
      description: Moves it back to its usual place. Nothing is removed.
      operationId: unpinContribution
      tags:
      - Contributions
      parameters:
      - name: contribution
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Unpinned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinState'
        '401':
          description: Missing or invalid token
    servers:
    - url: /api/v1
  /contributions/{contribution}/restore:
    post:
      summary: Restore something hidden
      description: Put it back in their book.
      operationId: restoreContribution
      parameters:
      - in: path
        name: contribution
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contribution'
        '404':
          description: Not on a memorial you look after
      tags:
      - Contributions
    servers:
    - url: /api/v1
components:
  schemas:
    Contribution:
      type: object
      additionalProperties: false
      required:
      - id
      - type
      - title
      - body
      - author
      - status
      - is_approved
      - is_private
      - is_pinned
      - is_hidden
      - heart_count
      - moderation
      - can_approve
      - created_at
      properties:
        id:
          type: integer
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        body:
          type:
          - string
          - 'null'
        author:
          type: object
          additionalProperties: false
          required:
          - name
          - email
          - is_guest
          properties:
            name:
              type:
              - string
              - 'null'
            email:
              type:
              - string
              - 'null'
            is_guest:
              type: boolean
        status:
          type: string
          enum:
          - pending
          - approved
          - rejected
          - hidden
        is_approved:
          type: boolean
        is_private:
          type: boolean
        is_pinned:
          type: boolean
        is_hidden:
          type: boolean
        heart_count:
          type: integer
          minimum: 0
        moderation:
          type: object
          additionalProperties: false
          required:
          - status
          - reason
          properties:
            status:
              type:
              - string
              - 'null'
            reason:
              type:
              - string
              - 'null'
        can_approve:
          type: boolean
        created_at:
          type:
          - string
          - 'null'
    PinState:
      type: object
      required:
      - id
      - pinned
      - message
      properties:
        id:
          type: integer
        pinned:
          type: boolean
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API token, sent as `Authorization: Bearer <token>`.

        A personal token is obtained through the device flow (`POST /auth/device`), or by hand from Connected apps in account settings. Rate limited to 20 requests/minute.

        A business token is created by a Business Admin in Business settings → API tokens, is shown once, and scopes to that organization. Rate limited to 50 requests/minute.

        '
x-refined-from:
- public.yaml
- cherishedbook-com-openapi.yml