Knak Sync Location API

openapi: 3.1.0
info:
  description: |
    ## Overview
    An API specification to provide a Custom Sync Location in Knak.

    By implementing a service conforming to this API specification, you will be able to send asset data to your own service and have that service specify a sync location based on that data.

    ## Authentication
    Knak provides two options for authentication:
    - **Basic Authentication**: Knak will use Basic Authentication to authenticate with your API. You will just need to provide a username and password when configuring the integration.
    - **OAuth2**: Knak will use OAuth2 to authenticate with your API. You will need to implement endpoints under a specified authorization path to support this. The default path will be `/oauth/token` but you can provide a separate path when configuring the integration if you so choose. The flow used is the standard [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1).


    Knak will use the tokens generated to make requests from your service.

    ## Custom Sync Location
    When a user has a custom sync location configured and they have set up a sync restriction that leverages the custom sync location.
    Knak will call the `/knak-sync-location` (or your own specified path) endpoint with the asset data when an asset is synced. Your service should return a response with the sync location for the asset.

    When your service provides a sync location, Knak will use that location to display only the available sync location to the user.
  version: V1
  title: Custom Sync Location API Reference — Sync Location
  x-logo:
    url: https://s3.amazonaws.com/assets.knak.io/img/Knak-Logo-Medium.png
servers:
- url: https://yourService.com/your-sync-location-api
tags:
- name: Sync Location
  description: Endpoints to retrieve Sync Location
paths:
  /v1/knak-sync-location:
    post:
      tags:
      - Sync Location
      summary: Provide Sync Location for Asset
      description: Knak will call this endpoint to get the sync location for the asset. This is used to
        determine the sync location for the asset in Knak.
      security:
      - OAuth2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        description: The type of the asset
                        example: email
                      id:
                        type: string
                        description: The ID of the asset
                        example: 66154fd1e9704
                      custom_field_example_1:
                        type: string
                        description: Can be any custom field you want to use to determine the sync location
                        example: newsletter
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The type of the asset
                          example: email
                        id:
                          type: string
                          description: The ID of the asset
                          example: 66154fd1e9704
                        folder:
                          type: object
                          properties:
                            id:
                              type: string
                              description: The ID of the folder or program
                              example: '1256'
                            title:
                              type: string
                              description: The title of the folder or program
                              example: My Favourite Program
                            is_root:
                              type: boolean
                              description: Whether this is a root folder
                              example: false
                            status:
                              type: string
                              description: The status of the folder or program
                              nullable: true
                              example: null
                            parent_id:
                              type: string
                              description: The ID of the parent folder
                              example: '48'
                            folder_type:
                              type: string
                              description: The type of the folder (Folder or Program)
                              example: Program
        401:
          description: Unauthenticated
        403:
          description: Unauthorized
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The type of the asset
                          example: email
                        id:
                          type: string
                          description: The ID of the asset
                          example: 66154fd1e9704
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                          description: The error message
                          example: Invalid Custom Field
                        type:
                          type: string
                          description: The type of the error
                          example: invalid
                        level:
                          type: string
                          description: The severity level of the error
                          example: error
                        email_id:
                          type: string
                          description: The ID of the email
                          example: 66154fd1e9704