Kitchen Stories Personalization API

openapi: 3.0.0
info:
  version: '3'
  title: Kitchen Stories Internal Articles Admin Personalization API
  description: ''
  contact:
    email: hello@kitchenstories.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.kitchenstories.io/api
  description: LIVE Environment
- url: https://api.dev.kitchenstories.io/api
  description: Development Environment
- url: http://localhost:8000/api
  description: Local Environment
security:
- bearerAuth: []
- ApiKeyAuth: []
tags:
- name: Personalization
paths:
  /personalization/:
    get:
      summary: Get personalization flags for user (or preferences set)
      operationId: personalization-get
      tags:
      - Personalization
      parameters:
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns the flags for personalization
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization'
    post:
      summary: Obtain a preferences set (for logged out preferences usage)
      operationId: personalization-post
      tags:
      - Personalization
      requestBody:
        description: When calling this endpoint with a logged out user, it will generate and create a new preferences set and return an uuid. This uuid can be used to set the preferences. If you call this endpoint with a logged in user, you will obtain the same result as calling the GET endpoint.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personalization_body'
      responses:
        '200':
          description: Returns a new personalization set for a logged out user, or the existing personalization set for a logged in user
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization'
    put:
      summary: Update personalization flags for user (or preferences set)
      operationId: personalization-put
      tags:
      - Personalization
      parameters:
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      requestBody:
        description: --
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personalization_body'
      responses:
        '200':
          description: The payload with the flags to update and their values
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization'
        '404':
          description: Preferences set not found (when user logged out)
  /personalization/preferences/:
    get:
      summary: Get a list of personalization preferences
      operationId: personalizationpreferences-get
      tags:
      - Personalization
      parameters:
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The current preferences and their values
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_preference_paginated'
        '404':
          description: Preferences set not found (when user logged out)
    post:
      summary: Insert a new personalization preference
      operationId: personalizationpreferences-post
      tags:
      - Personalization
      parameters:
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      requestBody:
        description: A uuid identifying an option and an array of value uuids
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personalization_preference_body'
      responses:
        '200':
          description: Operation successful
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_preference'
        '403':
          description: NotAuthorized. When provided preferences set does not belong to user
  /personalization/preferences/{uuid}/:
    get:
      summary: Get a single personalization preference by uuid
      operationId: personalizationpreferences-get-by-uuid
      tags:
      - Personalization
      parameters:
      - name: uuid
        in: path
        description: Unique identifier for preference
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Operation successful
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_preference'
        '404':
          description: NotFound. When preference does not exist or does not belong to user/set
    put:
      summary: Update a single preference
      operationId: personalizationpreferences-put-by-uuid
      tags:
      - Personalization
      parameters:
      - name: uuid
        in: path
        description: Unique identifier for preference
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
          format: uuid
      requestBody:
        description: --
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/personalization_preference_body'
      responses:
        '200':
          description: Operation Successful
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_preference'
        '404':
          description: NotFound. When preference does not exist or does not belong to user/set
    delete:
      summary: Delete a single preference
      operationId: personalizationpreferences-delete-by-uuid
      tags:
      - Personalization
      parameters:
      - name: uuid
        in: path
        description: Unique identifier for preference
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: set
        description: The uuid of a Preferences Set (for logged-out usage)
        schema:
          type: string
      responses:
        '200':
          description: Operation Successful
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/form_response'
        '404':
          description: NotFound. When preference does not exist
  /personalization/options/:
    get:
      summary: Get a list of available personalization options (and their values)
      operationId: personalizationoptions-get
      tags:
      - Personalization
      parameters:
      - name: show_all
        in: query
        description: Show all options in the system (even those without values)
        schema:
          type: string
      responses:
        '200':
          description: Returns a list of options with associated available values
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_option_paginated'
  /personalization/options/{uuid}/:
    get:
      summary: Get a single option information by its uuid
      operationId: personalizationoptions-get-by-uuid
      tags:
      - Personalization
      parameters:
      - name: uuid
        in: path
        description: Unique identifier for option
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns the informatiom about the queried option
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_option'
        '404':
          description: NotFound. Option with given uuid does not exist
  /personalization/options/{uuid}/values/:
    get:
      summary: Get available values for a given option uuid
      operationId: personalizationoptions-values-get
      tags:
      - Personalization
      parameters:
      - name: uuid
        in: path
        description: Unique identifier for option
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns a paginated list of available values
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_option_value_paginated'
        '404':
          description: NotFound. When option does not exist
  /personalization/options/{option-uuid}/values/{value-uuid}/:
    get:
      summary: Get a single value for an option by its uuid
      operationId: personalizationoptions-values-get-by-uuid
      tags:
      - Personalization
      parameters:
      - name: option-uuid
        in: path
        description: Unique identifier for option
        required: true
        schema:
          type: string
          format: uuid
      - name: value-uuid
        in: path
        description: Unique identifier for value
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns the information about the queried value
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization_option_value'
        '404':
          description: NotFound. When value does not exist
  /personalization/feed/:
    get:
      summary: Get the personalized feed for the current user
      operationId: personalization-feed-get
      tags:
      - Personalization
      parameters:
      - in: query
        name: refresh
        description: Indicate if you want a fresh feed
        schema:
          type: boolean
      - in: query
        name: deep_refresh
        description: Get the current feed and issue a task to fully refresh it. Note that this feed response will not be the fully re-generated feed as it is asynchronously being generated. Please keep pooling this endpoint until all generated_at fields of the collections are updated.
        schema:
          type: boolean
      - in: query
        name: exclude_liked_saved_content
        description: Specifies whether to exclude content liked and saved by user from personalized content. Defaults to True.
        schema:
          type: boolean
      responses:
        '200':
          description: Returns the personalized feed.
          content:
            application/vnd.ajns.kitchenstories+json; version=3:
              schema:
                $ref: '#/components/schemas/personalization-feed'
components:
  schemas:
    personalization:
      type: object
      properties:
        uuid:
          type: string
          pattern: '[0-9a-f-]{36}'
        onboarding_completed:
          type: boolean
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    image:
      type: object
      properties:
        id:
          oneOf:
          - type: string
          - type: number
        url:
          type: string
          format: uri
        source:
          type: string
        source_link:
          type: string
        width:
          type: number
        height:
          type: number
      required:
      - url
      additionalProperties: false
    links:
      type: object
      properties:
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        next:
          type: string
          format: uri
        prev:
          type: string
          format: uri
      required:
      - last
      - first
      additionalProperties: false
    personalization_preference_body:
      type: object
      properties:
        option:
          type: string
          pattern: '[0-9a-f-]{36}'
        values:
          type: array
          items:
            type: string
      required:
      - option
      - values
    tag:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        slug:
          type: string
        type:
          type: string
        is_hidden:
          type: boolean
    meta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            pages:
              type: number
            count:
              type: number
            page:
              type: number
          required:
          - page
          - pages
          - count
          additionalProperties: false
      required:
      - pagination
      additionalProperties: false
    form_response:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
      required:
      - errors
    personalization_option_paginated:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/links'
        meta:
          $ref: '#/components/schemas/meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/personalization_option'
      required:
      - data
      - links
      - meta
    personalization_preference:
      type: object
      properties:
        uuid:
          type: string
          pattern: '[0-9a-f-]{36}'
        option:
          $ref: '#/components/schemas/personalization_option'
        values:
          type: array
          items:
            $ref: '#/components/schemas/personalization_option_value'
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
      required:
      - option
      - values
    personalized_feed_collection:
      type: object
      properties:
        type:
          type: string
          enum:
          - automated
        automated:
          type: object
          properties:
            title:
              type: string
            subtitle:
              type: string
            generated_at:
              type: string
              format: date-time
            content_count:
              type: number
            content:
              type: array
              items:
                oneOf:
                - $ref: '#/components/schemas/personalized_feed_recipe'
          required:
          - title
          - content
          additionalProperties: false
      required:
      - automated
      - type
    personalization_body:
      type: object
      properties:
        uuid:
          type: string
          pattern: '[0-9a-f-]{36}'
        onboarding_completed:
          type: boolean
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    personalization_option:
      type: object
      properties:
        uuid:
          type: string
          pattern: '[0-9a-f-]{36}'
        key:
          type: string
        option_type:
          type: string
          enum:
          - inclusive
          - exclusive
        value_type:
          type: string
          enum:
          - single
          - multi
        translation_status:
          type: string
          enum:
          - original
          - fully_translated
          - partially_translated
          - auto_translated
          - not_translated
        native_language:
          type: string
          enum:
          - en
          - de
          - zh
        values:
          type: array
          items:
            $ref: '#/components/schemas/personalization_option_value'
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
      required:
      - value_type
      - key
      - option_type
    user_public:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - community
          - contributor
          - editor
        new_type:
          type: string
          enum:
          - community
          - contributor
          - editor
          - partner
          - external
        name:
          type: string
        slug:
          type: string
        occupation:
          type: string
        description:
          type: string
        image:
          $ref: '#/components/schemas/image'
          nullable: true
        banner_image:
          $ref: '#/components/schemas/image'
        wide_banner_image:
          $ref: '#/components/schemas/image'
        website:
          type: string
          format: uri
        is_premium:
          type: boolean
        created:
          type: string
          format: date-time
      required:
      - type
      - new_type
      - name
      - id
    personalization_option_value_paginated:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/links'
        meta:
          $ref: '#/components/schemas/meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/personalization_option_value'
      required:
      - data
      - links
      - meta
    personalization_preference_paginated:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/links'
        meta:
          $ref: '#/components/schemas/meta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/personalization_preference'
      required:
      - data
      - links
      - meta
    personalization_option_value:
      type: object
      properties:
        uuid:
          type: string
          pattern: '[0-9a-f-]{36}'
        value:
          type: string
        title:
          type: string
        description:
          type: string
        translation_status:
          type: string
          enum:
          - original
          - fully_translated
          - partially_translated
          - auto_translated
          - not_translated
        native_language:
          type: string
          enum:
          - en
          - de
          - zh
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
      required:
      - value
    personalization-feed:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/personalized_feed_collection'
      required:
      - data
    personalized_feed_recipe:
      type: object
      properties:
        type:
          type: string
          enum:
          - recipe
        recipe:
          type: object
          properties:
            id:
              type: string
            type:
              type: string
              enum:
              - recipe
              - community
              - how-to
            title:
              type: string
            image:
              $ref: '#/components/schemas/image'
            content_id:
              type: string
            user_reactions:
              type: object
              properties:
                like_count:
                  type: number
              required:
              - like_count
              additionalProperties: false
            total_time:
              type: number
            author:
              $ref: '#/components/schemas/user_public'
            tags:
              type: array
              items:
                $ref: '#/components/schemas/tag'
            n_inclusive_tag_matching:
              type: number
          required:
          - image
          - description
          - url
          - title
          additionalProperties: false
      required:
      - type
      - recipe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Ultron-User