The Asset Custom Fieldsets API from Knak — 2 operation(s) for asset custom fieldsets.
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 Asset Custom Fieldsets API
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: Asset Custom Fieldsets
paths:
/asset-custom-fieldsets:
get:
description: Retrieve all [asset custom fieldsets](#tag/asset_custom_fieldset).
summary: List all asset custom fieldsets
parameters:
- name: page
in: query
required: false
description: Page number
example: 1
schema:
type: integer
- name: per_page
in: query
required: false
description: Number of items per page
example: 10
schema:
type: integer
tags:
- Asset Custom Fieldsets
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssetCustomFieldsetsList'
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
example:
message: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
example:
message: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response'
example:
message: Resource not found.
/asset-custom-fieldsets/{asset_custom_fieldset_id}/asset-custom-fields:
get:
description: Retrieve all asset custom fields within an [asset custom fieldset](#tag/asset_custom_fieldset).
summary: List all asset custom fields within an asset custom fieldset
parameters:
- in: path
required: true
name: asset_custom_fieldset_id
description: ID of asset custom fieldset
example: 64a4810d4d12b
schema:
type: string
tags:
- Asset Custom Fieldsets
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AssetCustomField'
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the asset custom field you were looking for.
components:
schemas:
AssetCustomFieldset:
type: object
properties:
type:
type: string
example: asset-custom-fieldset
id:
type: string
example: 63eff78889f21
attributes:
type: object
properties:
id:
type: string
example: 63eff78889f21
name:
type: string
example: Asset Custom Fieldset
brands:
type: array
items:
$ref: '#/components/schemas/BrandSummary'
created_at:
type: string
format: date-time
example: '2023-05-17T21:54:19.000000Z'
updated_at:
type: string
format: date-time
example: '2023-05-18T19:55:21.000000Z'
BrandSummary:
type: object
properties:
id:
type: string
example: 63eff7760568a
name:
type: string
example: AMER
AssetCustomField:
type: object
properties:
type:
type: string
example: asset-custom-field
id:
type: string
example: 63eff78889f21
attributes:
type: object
properties:
id:
type: string
example: 63eff78889f21
label:
type: string
example: Field Label
field_name:
type: string
example: Field Name
default_value:
type: string
example: Default
nullable: true
type_definition:
type: string
format: JSON object
example:
type: date
required:
type: boolean
example: false
created_at:
type: string
format: date-time
example: '2023-05-17T21:54:19.000000Z'
updated_at:
type: string
format: date-time
example: '2023-05-18T19:55:21.000000Z'
AssetCustomFieldsetsList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AssetCustomFieldset'
links:
type: object
properties:
first:
type: string
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=1
last:
type: string
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=3
prev:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=1
next:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=3
meta:
type: object
properties:
current_page:
type: integer
example: 1
from:
type: integer
example: 1
last_page:
type: integer
example: 3
links:
type: array
items:
type: object
properties:
url:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=2
label:
type: string
example: Next
active:
type: boolean
example: true
path:
type: string
example: https://enterprise.knak.io/api/published/v1/asset-custom-fieldsets?page=2
per_page:
type: integer
example: 10
to:
type: integer
example: 2
total:
type: integer
example: 2
Response:
type: object
properties:
message:
type: string
example: This is the response message to the request made.
Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
description: HTTP status code as a string. Returned by endpoints that use the JSON:API error shape.
example: '409'
title:
type: string
detail:
type: string
meta:
type: object
description: Additional context for the error. Returned by endpoints that use the JSON:API error shape.
additionalProperties: true