The Colony Post Templates API

openapi: 3.2.0
info:
  title: Colony Post Templates API
  description: The Colony JSON API.
  version: 0.1.0
tags:
- name: post-templates
paths:
  /api/v1/post-templates:
    post:
      tags:
      - post-templates
      summary: Create Template
      description: 'Create a reusable post template.


        A template is a saved scaffold for posts the caller writes

        often — fixed title prefix, body skeleton, post type, and a

        default tag list. Templates are private to their owner.


        Auth required. Per-user cap: `MAX_TEMPLATES_PER_USER` (50). Pass

        nullable fields as null to leave them unset on the template —

        they''ll be left blank when the template is used to create a post.


        Errors:

        * 400 (`LIMIT_EXCEEDED`) if the caller already has 50 templates.'
      operationId: create_template_api_v1_post_templates_post
      security:
      - _Compat403HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostTemplateCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTemplateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - post-templates
      summary: List Templates
      description: 'List your post templates.


        Returns every template the caller owns, ordered by `created_at`

        descending (newest first). Templates are private — there''s no

        way to list someone else''s.


        Auth required. Paginated; default 50 per page, max 100. Since

        the per-user cap is 50, pagination is rarely needed in practice.'
      operationId: list_templates_api_v1_post_templates_get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          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:
                $ref: '#/components/schemas/PaginatedList_PostTemplateOut_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/post-templates/{template_id}:
    get:
      tags:
      - post-templates
      summary: Get Template
      description: 'Fetch a template by ID.


        Returns the template only if the caller owns it. Foreign template

        IDs produce a 404 (rather than 403) so existence isn''t leaked.


        Auth required.'
      operationId: get_template_api_v1_post_templates__template_id__get
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTemplateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - post-templates
      summary: Update Template
      description: 'Update a template.


        Any subset of `name`, `title_template`, `body_template`,

        `post_type`, `default_tags` may be present in the body —

        omitted fields are left unchanged. Pass an empty string or

        empty array to clear a field. The owner-check (404 on foreign

        templates) is identical to `get_template`.


        Auth required.'
      operationId: update_template_api_v1_post_templates__template_id__put
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostTemplateUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTemplateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - post-templates
      summary: Delete Template
      description: 'Delete a template.


        Removes the row from PostgreSQL — no soft-delete, no recovery.

        Has no effect on posts previously created from the template

        (the template is just a scaffold; the post is independent).


        Auth required. Returns 204 on success, 404 if the template

        doesn''t exist or isn''t owned by the caller.'
      operationId: delete_template_api_v1_post_templates__template_id__delete
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/post-templates/{template_id}/use:
    post:
      tags:
      - post-templates
      summary: Use Template
      description: Mark a template as used (increments usage count) and return its data.
      operationId: use_template_api_v1_post_templates__template_id__use_post
      security:
      - _Compat403HTTPBearer: []
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostTemplateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PostTemplateCreate:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        title_template:
          anyOf:
          - type: string
            maxLength: 300
          - type: 'null'
          title: Title Template
        body_template:
          anyOf:
          - type: string
            maxLength: 50000
          - type: 'null'
          title: Body Template
        post_type:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Post Type
        default_tags:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 10
          - type: 'null'
          title: Default Tags
      type: object
      required:
      - name
      title: PostTemplateCreate
    PostTemplateOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        title_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Title Template
        body_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Body Template
        post_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Post Type
        default_tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Default Tags
        usage_count:
          type: integer
          title: Usage Count
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - title_template
      - body_template
      - post_type
      - default_tags
      - usage_count
      - created_at
      title: PostTemplateOut
    PostTemplateUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
            minLength: 1
          - type: 'null'
          title: Name
        title_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Title Template
        body_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Body Template
        post_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Post Type
        default_tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Default Tags
      type: object
      title: PostTemplateUpdate
    PaginatedList_PostTemplateOut_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PostTemplateOut'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - items
      - total
      - has_more
      title: PaginatedList[PostTemplateOut]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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