{ "openapi": "3.0.3", "servers": [ { "url": "https://brandfolder.com/api/v4" } ], "info": { "title": "Brandfolder OpenAPI Reference", "version": "v4", "description": "Welcome to the OpenAPI reference documentation for Brandfolder by Smartsheet!\n" }, "tags": [ { "name": "assets", "x-displayName": "Assets", "description": "Assets are the core resource of Brandfolder. They act like containers that hold all of your digital resources and files, which we call Attachments. They belong to a Section in a Brandfolder and can also exist within many Collections.\n" }, { "name": "attachments", "x-displayName": "Attachments", "description": "Attachments are the representation of digital assets in Brandfolder. Generally speaking, they are actual files but can also be colors, fonts, links to embedded/external media, etc. They belong to an Asset and contain extra metadata related to the files they represent.\n\n> **Note:**\n>\n> If you need to list all of an organization's attachments, follow these steps:\n>\n> 1. List all Brandfolders: `GET /brandfolders?include=organization`\n> 2. List all sections for each Brandfolder within the target organization: `GET /brandfolders/{brandfolder_id}/sections`\n> 3. Iteratively list assets and their attachments for each Section: `GET /sections/{section_id}/assets?include=attachments`\n" }, { "name": "binary_upload", "x-displayName": "Binary upload", "description": "Brandfolder's Binary Upload service allows for authenticated users to upload locally stored files into Brandfolder via our API.\n\nBinary Upload is a multi-step process:\n\n1. [Get an upload URL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)\n2. Upload the file to the storage bucket using one of the methods below : \n - [Upload a file](/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestbucketput)\n - [Resumable upload](/api/brandfolder/openapi/binary_upload/opidstorageservicebfuploadrequestpost)\n3. [Create an asset](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost), telling the Brandfolder API the attachment is at that URL.\n\nThe Brandfolder Upload Request endpoint will return a response body with a signed `upload_url`, `resumable_upload_url`, storage `service_type` and `object_url`.\n\nEach Binary Upload `request_url` and `object_url` are designed to be used one time for a singular Asset. Both the `upload_url` and `resumable_upload_url` will expire 24 hours after they're issued. Assets uploaded to the `object_url` will be stored for 7 days before being purged. Should any of these URLs expire, you will simply need to restart the workflow to obtain active URLs. \n\n> **Tip:** We recommend that you use the Resumable Upload flow if you have poor internet connection, you're uploading local files that are larger than 200MB or if you're uploading files from a server that are larger than 500MB.\n\n![Upload Request Flow](../images/bf-upload-request-interactions.png)\n" }, { "name": "brandfolders", "x-displayName": "Brandfolders", "description": "Brandfolders are nested directly underneath an Organization in the overall heirarchy. They can have many Collections, Sections, and Assets.\n" }, { "name": "collections", "x-displayName": "Collections", "description": "Collections are nested under a Brandfolder and contain many Assets. They are mainly used as an additional way to organize, manage, share, and restrict access to a subset of Assets within your Brandfolder without having to upload Assets to multiple places.\n" }, { "name": "custom_fields", "x-displayName": "Custom fields", "description": "Custom Fields can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder, as well as for understanding more details about each Asset.\n\nEach Custom Field is essentially a key/value pair associated with **exactly one Asset**. Keys and values are always a string type, so use `\"123\"` instead of `123`.\n\nFor example, if you have several Assets that represent products you sell in different colors, you might create a Custom Field for each of those Assets with a key of `\"color\"` and a value of `\"blue\"` or `\"red\"`, etc. If you modify or delete a `\"color\":\"blue\"` Custom Field for any particular Asset, it will not affect other Custom Fields on other Assets, even if they have the same key and/or value.\n\n> **IMPORTANT:** Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.\n" }, { "name": "invitations", "x-displayName": "Invitations", "description": "Invitations are exactly what they sound like and can be created to invite Users to join your Organization, Brandfolder, or Collection as a `guest`, `collaborator`, `admin`, or (when inviting someone to an Organization) `owner`.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n" }, { "name": "labels", "x-displayName": "Labels", "description": "Brandfolder's Labels are an enhanced organization and findability feature meant to provide the peace of mind that comes with an organization's existing folder structure. Think of Labels like your music playlists--any asset can be assigned to a label or multiple labels.\n\nLabels are not turned on for every account. If you are unsure whether you have or need Labels, please contact brandfoldersupport@smartsheet.com.\n" }, { "name": "organizations", "x-displayName": "Organizations", "description": "An Organization is the top level resource of all objects in Brandfolder. It can have many Brandfolders nested beneath it.\n" }, { "name": "sections", "x-displayName": "Sections", "description": "Sections are nested under a Brandfolder and contain many Assets. They exist to help keep Assets organized within a Brandfolder. They also determine which type of digital assets can be uploaded within them (files, external media, fonts, etc.).\n" }, { "name": "tags", "x-displayName": "Tags", "description": "Tags can be assigned to Assets and are generally helpful for organizing and searching Assets within a Brandfolder.\n\nEach Tag is essentially a keyword associated with exactly one Asset.\n\nFor example, if you have several Assets that represent products you sell, you might create a \"product\" Tag for each one. If you modify or delete the \"product\" Tag for any particular Asset, it will not affect other Tags with the same value on other Assets.\n\nTags have a read-only attribute called `auto_generated` which indicates if the Tag was created automatically by our smart analysis of the file Attachment(s) (`true`) or if a User created the Tag (`false`).\n\n> **IMPORTANT:** Think carefully about whether Tags or Custom Fields are better suited to meet the needs of your particular use case.\n" }, { "name": "user_permissions", "x-displayName": "User permissions", "description": "User permissions describe relationships between Organizations, Brandfolders, Collections, Portals or Brandguides and the users that have access to them.\n\nLearn more about permissioning in our Knowledge Base article on User Permissions.\n" }, { "name": "webhooks", "x-displayName": "Webhooks", "description": "The Brandfolder Webhooks service allows you to subscribe to event-based notifications (callbacks) when a qualifying event is triggered within Brandfolder. Asset data will then be sent to the user-provided `callback_url` at the time the subscribed event occurs within the specified Brandfolder. \n\n> NOTE: The `callback_url` must be accessible from the public internet, meaning any localhost, private network domains, or domains that require authentication will all fail.\n\n

Authentication

\n\nUtilizing Webhooks requires authentication with the resource (Brandfolder) being subscribed to. A user's unique API Key is required in a header for actions on all endpoints related to the Webhooks service.\n\n- Find your API key at https://brandfolder.com/profile#integrations.\n- Click the icon to the right of your key to copy it to your clipboard.\n\nThere are two required headers in each request: \n\n`Content-Type: application/json`
\n`Authorization: Bearer `\n\nThe provided API Key is checked against any provided resource (where applicable) to confirm the appropriate permissions.\n___\n\n

Service Details

\n\nThe Brandfolder Webhooks service allows for subscriptions to events within individual Brandfolders. \n\n> NOTE: Asset data updates made at the Collection level will trigger a Brandfolder Webhook subscription. Since assets live at the Brandfolder level, any updates made at the Collection level would be reflected on the Brandfolder level as well, thus triggering a Webhook.\n\nDue to the way Brandfolder manages assets, you will see both an `\"asset.create\"` event and an `\"asset.update\"` event upon creation of a new asset. A `create` event is triggered when Brandfolder recognizes the new asset and begins to process it for use. An `update` event is triggered when the asset is ready for use.\n\nThe following event types trigger webhooks:\n\n* `asset.create` - Asset creation. A new asset has been added to a subscribed Brandfolder.\n* `asset.update` - Asset update. Asset data has been updated within a subscribed Brandfolder. One or more of the following asset attributes has been updated:\n * Name\n * Description\n * Section\n * Approval status\n * Expiration status\n * Comments & Annotations\n * Adding / Updating\n * Deleting\n * Tags\n * Adding / Updating\n * Deleting\n * Custom Fields\n * Adding / Updating\n * Deleting\n* `asset.delete` - Asset deletion. An asset has been removed from within a subscribed Brandfolder.\n\n> Once a Webhook subscription as been created, the payload that will be sent to the user-provided `callback_url` after an event has been triggered will have the following structure:\n\n```json\n{\n \"data\": {\n \"attributes\": {\n \"key\": \"\",\n \"event_time\": \"\",\n \"event_type\": \"\",\n \"brandfolder_key\": \"\",\n \"organization_key\": \"\"\n },\n \"webhook_id\": \"\"\n }\n}\n```\n\n> NOTE: The callback payload is a \"skinny\" payload -- it indicates which assets changed and the type of event that occurred, but does not contain any data from the assets themselves.\n\nThe Brandfolder Webhook service requires your application to immediately acknowledge receipt of any Webhooks by returning a `2xx` HTTP status code. If Brandfolder does not receive an acknowledgement or any non `2xx` HTTP status code is returned, Brandfolder will retry the Webhook up to 15 times with exponentially increasing wait times in between. \n\n**Any Webhook subscriptions that continue to fail without remedy will be made inactive.**\n\nMessages may be sent out of order to the `callback_url` associated with a Webhook subscription. The `event_time` provided in the payload can be used to order events.\n\nIf the API Key associated with a Webhook subscription loses access to the associated resource, the subscription will be deactivated within 30 minutes.\n" } ], "paths": { "/brandfolders": { "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "list-brandfolders", "summary": "List Brandfolders", "description": "Lists all Brandfolders for a User. Unauthorized requests will return an\nempty list.\n\nYou can use the returned `slug` attribute to form a link to the desired\nBrandfolder like so:\n\n````\nhttps://brandfolder.com/{slug}\n````\n", "tags": [ "brandfolders" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following attributes of the Brandfolders\nto return as part of the Brandfolders' attributes in the response.\n\nAllowed values: \n\n- asset_count\n- attachment_count\n- storage\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "asset_count,attachment_count,storage" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the Brandfolders you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- organization\n- collections\n- assets\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "organizations" }, { "in": "query", "name": "search", "description": "Set it to any URL-encoded query to fetch only Brandfolders that match your criteria.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "extension:png" } ], "responses": { "200": { "description": "References to all the user's Brandfolders.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brandfolder" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersByIdGet", "tags": [ "brandfolders" ], "summary": "Fetch a Brandfolder", "description": "You can use the returned `slug` attribute to form a link to the desired\nBrandfolder like so:\n\n````\nhttps://brandfolder.com/{slug}\n````\n", "parameters": [ { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following attributes of the Brandfolder\nto return as part of the Brandfolder's attributes in the response.\n\nAllowed values: \n\n- asset_count\n- attachment_count\n- section_count\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "asset_count,attachment_count,section_count" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the Brandfolder you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- organization\n- collections\n- search_filters\n- sections\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "organizations" } ], "responses": { "200": { "description": "A reference to the Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Brandfolder" } }, "required": [ "data" ] } } } } } }, "put": { "operationId": "opIdApiV4BrandfoldersByIdPut", "summary": "Update a Brandfolder", "description": "Updates the matching Brandfolder.", "tags": [ "brandfolders" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "description": "Attribute updates for the Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A new name for the Brandfolder.", "example": "Updated Brandfolder" }, "privacy": { "type": "string", "description": "A new privacy setting for the Brandfolder.", "example": "public" }, "slug": { "type": "string", "description": "A new URL-friendly slug for the Brandfolder.", "example": "updated-brandfolder" }, "tagline": { "type": "string", "description": "A new tagline for the brandfolder.", "example": "Updated Brandfolder tagline!" } } } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "brandfolders" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the Brandfolder.", "example": "Updated Brandfolder" }, "privacy": { "type": "string", "description": "The privacy setting of the Brandfolder.", "example": "public" }, "slug": { "type": "string", "description": "The URL-friendly slug of the Brandfolder.", "example": "updated-brandfolder" }, "tagline": { "type": "string", "description": "The tagline for the brandfolder.", "example": "Updated Brandfolder tagline!" } }, "required": [ "name", "privacy", "slug", "tagline" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/collections": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersCollectionsByBrandfolderIdGet", "summary": "List collections in a Brandfolder", "description": "List all collections in the Brandfolder.\n\nYou can use the returned `slug` parameter (in conjunction with the slug of\nthe parent Brandfolder) to form a link to the desired Collection like so:\n\n```\nhttps://brandfolder.com/{brandfolder_slug}/{collection_slug\n```\n", "tags": [ "collections" ], "responses": { "200": { "description": "All the collections in the Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4BrandfoldersCollectionsByBrandfolderIdPost", "summary": "Create a collection", "description": "Creates a collection in the matching Brandfolder.", "tags": [ "collections" ], "requestBody": { "description": "Attribute values for the collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A name.", "example": "My collection" }, "slug": { "type": "string", "description": "A URL-friendly slug. Use only letters, numbers, hyphens, and\nunderscores.\n\nNOTE: We recommend **not** to invent your own slug. If it is\nnot unique and valid, the request fails with a `422` error.\nDefault is to automatically assign a slug based on `name` (a\nname of \\\"My Collection\\\" would make a slug of\n\\\"my-collection\\\").\n", "example": "my-collection" }, "tagline": { "type": "string", "description": "A tag line.", "example": "My collection tag line" } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new collection.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/custom_field_keys": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersCustomFieldKeysByBrandfolderIdGet", "summary": "List custom field keys", "description": "Lists custom field keys for the matching Brandfolder.\n", "tags": [ "custom_fields" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `value` to return it as part of the asset's attributes in the\nresponse.\n\nAllowed value: `value`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "value" }, { "in": "query", "name": "include", "description": "Set it to `custom_field_values` to return those records related to the\nasset you're fetching. Related records are returned in an `included`\narray in the response.\n\nAllowed value: `custom_field_values`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "custom_field_values" } ], "responses": { "200": { "description": "All custom field keys for the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldKey" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4BrandfoldersCustomFieldKeysByBrandfolderIdPost", "summary": "Create custom field keys", "description": "Creates custom field keys for the matching brandfolder.\n\nThis endpoint is **only** needed for setting up controlled Custom Fields. If\nthis is enabled for your Brandfolder, you can set the allowed keys and\noptionally restrict their allowed values for Custom Fields using this\nendpoint.\n", "tags": [ "custom_fields" ], "requestBody": { "description": "Custom field keys for the matching brandfolder.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The key name.", "example": "color" }, "allowed_values": { "type": "array", "description": "The `value` that can be used with this `key` when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array `[]`, the `values` are unrestricted.", "items": { "type": "string" }, "example": [ "red", "white", "blue" ] }, "position": { "type": "integer", "format": "int32", "description": "Sets the location of the custom field among other custom fields in the Brandfolder UI.", "minimum": 0, "example": 0 }, "prioritized": { "type": "boolean", "description": "Set to `true` to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.", "example": false }, "required": { "type": "boolean", "description": "If set to `true`, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.", "example": false }, "restricted": { "type": "boolean", "description": "If set to `true`, the field value is restricted to a set of allowed values (see `allowed_values`); otherwise, the field value is unrestricted.", "example": true } } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new custom field keys.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldKey" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/organizations": { "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4OrganizationsGet", "summary": "List organizations", "description": "Lists all Organizations for a User. Unauthorized requests will return an empty list.\n\nYou can use the returned `slug` attribute to form a link to the desired Organization like so:\n\n````\nhttps://brandfolder.com/organizations/{slug}\n````\n", "tags": [ "organizations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `asset_count` to return each organization's asset count as part of each organization's attributes in the response.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string", "enum": [ "asset_count" ] }, "example": "asset_count" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the organizations you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- brandfolders\n- brandguides\n- collections\n- portals\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "brandfolders" } ], "responses": { "200": { "description": "All the user's organizations.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/organizations/{organization_id}": { "parameters": [ { "name": "organization_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-cocc75" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4OrganizationsByIdGet", "summary": "Get an organization", "description": "You can use the returned `slug` attribute to form a link to the desired Organization like so:\n\n````\nhttps://brandfolder.com/organizations/{slug}\n````\n", "tags": [ "organizations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following attributes of the organization to return as part of the organization's attributes in the response.\n\nAllowed values: \n\n- `asset_count` returns the organization's asset count.\n- `cname` returns the organization's Canonical Name (CNAME), or `null` if the organization doesn't have one.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string", "enum": [ "asset_count", "cname" ] }, "example": "asset_count" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following record names to return those records related to the organization you're fetching. Related records are returned in an `included` array in the response.\n\nAllowed values: \n\n- assets\n- brandfolders\n- brandguides\n- collections\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "collections" } ], "responses": { "200": { "description": "The matching organization.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Organization" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/organizations/{organization_id}/brandfolders": { "parameters": [ { "name": "organization_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-cocc75" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "post": { "operationId": "opIdApiV4OganizationsBrandfoldersByOrganizationIdPost", "summary": "Create a Brandfolder", "description": "Creates a Brandfolder in the specified organization.\n", "tags": [ "brandfolders" ], "parameters": [ { "name": "Content-Type", "in": "header", "schema": { "type": "string", "default": "application/json", "example": "application/json" } } ], "requestBody": { "description": "Attributes for the new Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the brandfolder.", "example": "Brandfolder" }, "privacy": { "type": "string", "description": "The privacy setting of the brandfolder.", "example": "private" }, "slug": { "type": "string", "description": "The URL-friendly slug of the brandfolder.", "example": "brandfolder" }, "tagline": { "type": "string", "description": "The tagline of the brandfolder.", "example": "You expected this - Brandfolder's Brandfolder!", "default": "" } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Brandfolder" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections": { "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsGet", "summary": "List collections", "description": "List the collections accessible to the user. \n\nUnauthorized requests return an empty list.\n\nYou can use the returned `slug` parameter (in conjunction with the slug of\nthe parent Brandfolder) to form a link to the desired Collection like so:\n\n```\nhttps://brandfolder.com/{brandfolder_slug}/{collection_slug}\n```\n", "tags": [ "collections" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "security": [ { "APIToken": [] } ], "responses": { "200": { "description": "A list of collections accessible to the user.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections/{collection_id}": { "parameters": [ { "name": "collection_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsByIdGet", "summary": "Fetch a collection", "description": "Returns the matching collection.\n", "tags": [ "collections" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `asset_count` to return the collection's asset count as part\nof the collection's attributes in the response.\n\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string", "enum": [ "asset_count" ] }, "example": "asset_count" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the collection you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- brandfolder\n- assets\n- search_filters\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "brandfolder" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "responses": { "200": { "description": "The matching collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "opIdApiV4CollectionsByIdPut", "summary": "Update a collection", "description": "Updates the matching collection.", "tags": [ "collections" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "description": "Attribute updates for the collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A new name.", "example": "New name" }, "slug": { "type": "string", "description": "A new URL-friendly slug. Use only letters, numbers, hyphens,\nand underscores.\n\nNOTE: We recommend **not** to invent your own slug. If it is\nnot unique and valid, the request fails with a `422` error.\nDefault is to automatically assign a slug based on `name` (a\nname of \\\"My Collection\\\" would make a slug of\n\\\"my-collection\\\").\n", "example": "new-name" }, "tagline": { "type": "string", "description": "A new tag line.", "example": "New tag line" } } } }, "required": [ "attibutes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "collections" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A new name.", "example": "New name" }, "slug": { "type": "string", "description": "A new URL-friendly slug.\n", "example": "new-name" }, "tagline": { "type": "string", "description": "A new tag line.", "example": "New tag line" }, "public": { "type": "boolean", "description": "Set to `true` for hassle-free sharing, allowing search engines to index your brand assets. Otherwise, set to `false` to share only with the users you specify.", "example": false }, "stealth": { "type": "boolean", "description": "Set to `true` to remove the collection from appearing in web searches.", "example": false }, "is_workspace": { "type": "boolean", "description": "Set to `true` if the collection is a Brandfolder workspace.", "example": false } } } } } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4CollectionsByIdDelete", "summary": "Delete a collection", "description": "Removes the matching collection.", "tags": [ "collections" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections/{collection_id}/assets": { "parameters": [ { "name": "collection_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsAssetsByCollectionIdGet", "summary": "List assets in a collection", "description": "Lists assets in a collection.", "tags": [ "assets", "collections" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request. More records may exist (as denoted by\nthe `meta.total_count` value).\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } }, { "in": "query", "name": "search", "description": "Set it to any URL-encoded query to fetch only assets that match your\ncriteria.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "extension:png" }, { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "cdn_url" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "tags" } ], "responses": { "200": { "description": "The matching collection assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4CollectionsAssetsByCollectionIdPost", "summary": "Create assets in a collection", "description": "Creates assets in the matching collection.\n\nAny files you wish to use as an Attachment in Brandfolder must be hosted at\na publicly available URL (until they have been successfully imported). If\nyou need to upload file contents directly to a server, you can use do a\nbinary file upload to our temporary storage bucket and then use that URL\nwhen creating Assets/Attachments.\n", "tags": [ "assets", "collections" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/AssetAttributesRequest" } } }, "required": [ "attributes" ] }, "section_key": { "type": "string", "description": "ID of the Section in which you want the newly created Asset(s)\nto live.\n", "example": "oqgol8-dslwxs-58b2z3" } }, "required": [ "data", "section_key" ] } } } }, "responses": { "200": { "description": "The new assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections/{collection_id}/tags": { "parameters": [ { "name": "collection_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsTagsByCollectionIdGet", "summary": "List tags in a collection", "description": "Lists tags in the matching collection.\n", "tags": [ "collections", "tags" ], "responses": { "200": { "description": "Tags in the matching collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/sections": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4SectionsGet", "summary": "List sections", "description": "Returns the Brandfolder's sections.", "tags": [ "sections" ], "parameters": [ { "in": "query", "name": "include", "schema": { "type": "string" }, "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names, to return those records related to the sections. Related\nrecords are returned in an `included` array in the response.\n\nAllowed values: \n\n- brandfolder\n- assets\n\nWARNING: This parameter can slow response times.\n", "example": "brandfolder" } ], "responses": { "200": { "description": "The sections in the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4BrandfoldersSectionsByBrandfolderIdPost", "summary": "Create a section", "description": "Creates a section in the matching Brandfolder.", "tags": [ "sections" ], "requestBody": { "description": "Attribute values for the section.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A name.", "example": "My section" }, "default_asset_type": { "type": "string", "description": "Set this to the type of asset to put in the section.\n\nIMPORTANT: If you're using the API to add assets to the\nsection, we strongly recommend setting this to\n`GenericFile`.\n", "enum": [ "GenericFile", "Color", "Font", "ExternalMedium", "Person", "Press", "Text" ], "example": "GenericFile" }, "position": { "type": "integer", "minimum": 0, "description": "Set this to a non-negative integer that represents where to\ndisplay the section relative to other sections. The first\nposition is `0`. The new position defaults to the next\navailable position.\n", "example": 0 } }, "required": [ "name", "default_asset_type" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new section.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Section" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/sections/{section_id}": { "parameters": [ { "name": "section_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgol8-dslwxs-58b2z3" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4SectionsByIdGet", "summary": "Fetch a section.", "description": "Fetches the matching section.", "tags": [ "sections" ], "parameters": [ { "in": "query", "name": "include", "schema": { "type": "string" }, "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names, to return those records related to the sections. Related\nrecords are returned in an `included` array in the response.\n\nAllowed values: \n\n- brandfolder\n- assets\n\nWARNING: This parameter can slow response times.\n", "example": "brandfolder" } ], "responses": { "200": { "description": "The matching section.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Section" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/sections/{section_id}/assets": { "parameters": [ { "name": "section_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgol8-dslwxs-58b2z3" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4SectionsAssetsBySectionIdGet", "summary": "List assets in a section", "description": "Lists assets in the matching section.", "tags": [ "assets", "sections" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request. More records may exist (as denoted by\nthe `meta.total_count` value).\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } }, { "in": "query", "name": "search", "description": "Set it to any URL-encoded query to fetch only assets that match your\ncriteria.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "extension:png" }, { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "cdn_url" } ], "responses": { "200": { "description": "The matching section assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/assets": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersAssetsByBrandfolderIdGet", "summary": "List assets in a Brandfolder", "description": "Lists assets in a Brandfolder.", "tags": [ "assets", "brandfolders" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request. More records may exist (as denoted by\nthe `meta.total_count` value).\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } }, { "in": "query", "name": "search", "description": "Set it to any URL-encoded query to fetch only assets that match your\ncriteria.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "extension:png" }, { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "cdn_url" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "tags" } ], "responses": { "200": { "description": "The matching Brandfolder assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4CollectionsAssetsByBrandfolderIdPost", "summary": "Create assets in a Brandfolder", "description": "Creates assets in the matching Brandfolder.\n\nAny files you wish to use as an Attachment in Brandfolder must be hosted at\na publicly available URL (until they have been successfully imported). If\nyou need to upload file contents directly to a server, you can use do a\nbinary file upload to our temporary storage bucket and then use that URL\nwhen creating Assets/Attachments.\n\n> **NOTE:** To create an asset from a binary upload, copy the `object_url`\nvalue from the [Get an upload\nURL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)\nresponse into your request body's `attachments.url` property.\n", "tags": [ "assets", "brandfolders" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/AssetAttributesRequest" } } }, "required": [ "attributes" ] }, "section_key": { "type": "string", "description": "ID of the Section in which you want the newly created Asset(s)\nto live.\n", "example": "oqgol8-dslwxs-58b2z3" } }, "required": [ "data", "section_key" ] } } } }, "responses": { "200": { "description": "The new assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/assets/{asset_id}": { "parameters": [ { "name": "asset_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4AssetsByIdGet", "summary": "Fetch an asset", "description": "Fetches the matching asset.", "tags": [ "assets" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n- `availability_start`\n- `availability_end`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "cdn_url" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "tags" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "responses": { "200": { "description": "The matching asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "data" ] } } } }, "403": { "description": "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "opIdApiV4AssetsByIdPut", "summary": "Update an asset", "description": "Updates the matching asset.\n\n> **Note:** All attributes are optional when updating. Only include the ones\nyou want to change.\n\nAny files you wish to use as an Attachment in Brandfolder must be hosted at\na publicly available URL (until they have been successfully imported). If\nyou need to upload file contents directly to a server, you can use do a\nbinary file upload to our temporary storage bucket and then use that URL\nwhen creating Assets/Attachments.\n", "tags": [ "assets" ], "requestBody": { "description": "Attribute updates for an asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/AssetAttributesRequest" } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4AssetsByIdDelete", "summary": "Delete an asset", "description": "Removes the matching asset.", "tags": [ "assets" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/assets/{asset_id}/tags": { "parameters": [ { "name": "asset_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4AssetsTagsByAssetIdGet", "summary": "List tags for an asset", "description": "Lists tags for the matching asset.\n", "tags": [ "assets", "tags" ], "parameters": [ { "in": "query", "name": "include", "description": "Set it to `asset` to return those asset records related to the tag\nyou're fetching. Related records are returned in an `included` array in\nthe response.\n\nAllowed value: `asset`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "asset" } ], "responses": { "200": { "description": "Tags for the matching asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4AssetsTagsByAssetIdPost", "summary": "Create tags for an asset", "description": "Creates tags for the matching asset.\n\n> **Note:** You can add multiple tags to the `attributes` array in the\nrequest body.\n", "tags": [ "tags" ], "requestBody": { "description": "New tag names for the asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "array", "description": "A list of tag names for the matching asset.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "A tag name.", "example": "product" } } } } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "All tags for the matching asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/assets/{asset_id}/custom_field_values": { "parameters": [ { "name": "asset_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4AssetsCustomFieldValuesByAssetIdGet", "summary": "List custom fields", "description": "Lists custom fields for the matching asset.\n", "parameters": [ { "in": "query", "name": "include", "schema": { "type": "string" }, "description": "Set it to `custom_field_key` to return those custom field keys related\nto the asset you're fetching. Related records are returned in an\n`included` array in the response.\n\nAllowed value: `custom_field_key`\n\nWARNING: This parameter can slow response times.\n" } ], "tags": [ "custom_fields" ], "responses": { "200": { "description": "The custom fields for the asset.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/custom_field_keys/{custom_field_key_id}/custom_field_values": { "parameters": [ { "name": "custom_field_key_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "post": { "operationId": "opIdApiV4CustomFieldKeysCustomFieldValuesByCustomFieldKeyIdPost", "summary": "Create custom field values for an asset", "description": "Creates custom fields for the matching asset.\n\nIn order to use this endpoint, you will need to have the Custom Field Key ID\nfor the Custom Field you wish to create. Please see [List Custom Field Keys\nfor a\nBrandfolder](/api/brandfolder/openapi/custom_fields/opidapiv4brandfolderscustomfieldkeysbybrandfolderidget)\nto get a list of the Custom Field Key IDs.\n\nWant to learn more about Custom Fields? Check out out our Knowledge Base\narticle on Custom\nFields.\n", "tags": [ "custom_fields" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "A list of custom field associations.", "items": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "value": { "type": "string", "description": "Custom field key value.", "example": "red" } }, "required": [ "value" ] }, "relationships": { "type": "object", "description": "Specifies the object receiving the custom field.", "properties": { "asset": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of target object.", "enum": [ "assets" ] }, "id": { "type": "string", "description": "The ID of the asset.", "example": "k5nj2bf5mc36j3ssm63359h" } }, "required": [ "type", "id" ] } }, "required": [ "data" ] } }, "required": [ "asset" ] } }, "required": [ "attributes", "relationships" ] } } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new custom fields.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "r79p3j4gbcgtv33gbsqrxb" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "custom_field_values" ] }, "attributes": { "type": "object", "properties": { "key": { "type": "string", "description": "A key name.", "example": "team" }, "value": { "type": "string", "description": "The value for the key.", "example": "product" } } } }, "required": [ "id", "type", "attributes" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/attachments/{attachment_id}": { "parameters": [ { "name": "attachment_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4AttachmentsByIdGet", "summary": "Fetch an attachment", "description": "Gets the matching attachment.", "tags": [ "attachments" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the attachment to return as part of the attachment's\nattributes in the response.\n\nAllowed values: \n\n- `metadata` \n- `thumbnail_url` \n- `view_thumbnail_retina` \n- `extension` \n- `version_count` \n- `tag_names` \n- `label_names`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "metadata" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the attachment you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `asset`\n- `section`\n- `brandfolder`\n- `collections`\n- `tags`\n- `labels`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "brandfolder" } ], "responses": { "200": { "description": "The matching attachment.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Attachment" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "opIdApiV4AttachmentsByIdPut", "summary": "Update an attachment", "description": "Updates a matching attachment.\n", "tags": [ "attachments" ], "requestBody": { "description": "Updates for the matching attachment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "filename": { "type": "string", "example": "brandfolder_logo.png" }, "url": { "type": "string", "example": "https://example.com/brandfolder_logo.png?expiry=1625260667\n" } } } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated attachment.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Attachment" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4AttachmentsByIdDelete", "summary": "Delete an attachment", "description": "Removes the matching attachment.", "tags": [ "attachments" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/tags": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersTagsByBrandfolderIdGet", "summary": "List tags in a Brandfolder", "description": "Lists tags in the matching Brandfolder.\n", "tags": [ "brandfolders", "tags" ], "responses": { "200": { "description": "Tags in the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/tags/{tag_id}": { "parameters": [ { "name": "tag_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "put": { "operationId": "opIdApiV4TagsByIdPut", "summary": "Update a tag", "description": "Updates the matching tag.\n", "tags": [ "tags" ], "requestBody": { "description": "New tag names for the asset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "product" } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated tag.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/async/tags/assets/{asset_key}": { "parameters": [ { "name": "asset_key", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "123456-22mpg8-dfmfi7" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "delete": { "operationId": "opIdApiV4AsyncTagsAssetsByAssetKeyDelete", "summary": "Delete tags", "description": "Removes the matching tag(s) of the matching asset.\n\nExample Request Body:\n\n{ \"tags\": [\"A\", \"B\"], \"locale\": \"en\" }\n\n> **Important:** This endpoint is asynchronous\n", "tags": [ "tags" ], "requestBody": { "description": "Example: { \"tags\": [\"A\", \"B\"], \"locale\": \"en\" }\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "example": [ "A", "B" ] }, "locale": { "type": "string", "example": "en" } }, "required": [ "tags" ] } } } }, "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/custom_field_keys/{custom_field_key_id}": { "parameters": [ { "name": "custom_field_key_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "plqlkk-22rw6g-3dqgx0" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "put": { "operationId": "opIdApiV4CustomFieldKeysByIdPut", "summary": "Update a custom field key", "description": "Update the matching custom field key.\n\n> **Warning:** It is NOT recommended to update keys that are currently in\nuse. Changing allowed values or whether they are restricted after other\nvalues have already been used can lead to undesirable results.\n", "tags": [ "custom_fields" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The key name.", "example": "color" }, "allowed_values": { "type": "array", "description": "The `value` that can be used with this `key` when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array `[]`, the `values` are unrestricted.", "items": { "type": "string" }, "example": [ "orange", "gray", "green" ] } } } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated custom field key.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "plqlkk-22rw6g-3dqgx0" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "custom_field_keys" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The key name.", "example": "color" }, "allowed_values": { "type": "array", "description": "The `value` that can be used with this `key` when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array `[]`, the `values` are unrestricted.", "items": { "type": "string" }, "example": [ "orange", "gray", "green" ] }, "position": { "type": "integer", "format": "int32", "description": "Sets the location of the custom field among other custom fields in the Brandfolder UI.", "minimum": 0, "example": 0 }, "prioritized": { "type": "boolean", "description": "Set to `true` to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.", "example": false }, "required": { "type": "boolean", "description": "If set to `true`, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.", "example": false }, "restricted": { "type": "boolean", "description": "If set to `true`, the field value is restricted to a set of allowed values (see `allowed_values`); otherwise, the field value is unrestricted.", "example": true } } } }, "required": [ "id", "type", "attributes" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4CustomFieldKeysByIdDelete", "summary": "Delete a custom field key", "description": "Deletes the matching custom field key.\n\n> **Warning:** Be very careful when using this endpoint as it also deletes\nall associated values for that key.\n", "tags": [ "custom_fields" ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/custom_field_values/{custom_field_value_id}": { "parameters": [ { "name": "custom_field_value_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "123456-22mpg8-dfmfi7" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "put": { "operationId": "opIdApiV4CustomFieldValuesByIdPut", "summary": "Update a custom field", "description": "Update the matching custom field.\n", "tags": [ "custom_fields" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "value": { "type": "string", "example": "Fall" } } } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated custom field.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldValue" } } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4CustomFieldValuesByIdDelete", "summary": "Delete a custom field", "description": "Deletes the matching custom field.\n", "tags": [ "custom_fields" ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/labels": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4OrganizationsLabelsByBrandfolderIdGet", "summary": "List labels", "description": "Lists the labels in the matching Brandfolder.", "tags": [ "labels" ], "responses": { "200": { "description": "The labels in the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4CollectionsLabelsByBrandfolderIdPost", "summary": "Create a label", "description": "Creates a label in the matching Brandfolder.", "tags": [ "labels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Sets a name for the label.", "example": "onboarding" }, "parent_key": { "type": "string", "description": "Set this to the ID of the label's parent label, if any.\nIf you're creating a root-level label, don't specify\nthis property.\n", "example": "abc123" } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The new label.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/labels/{label_id}": { "parameters": [ { "name": "label_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "123456-22mpg8-dfmfi7" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4LabelsByIdGet", "summary": "Fetch a label", "description": "Fetches the label.", "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "tags": [ "labels" ], "responses": { "200": { "description": "The matching label.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "put": { "operationId": "opIdApiV4UpdateLabelPut", "summary": "Update a label", "description": "Updates the name of the matching label.", "tags": [ "labels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "A new name for the label.", "example": "onboarding" } }, "required": [ "name" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated label.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_asset_type": { "$ref": "#/components/schemas/Label" } } } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4LabelsByIdDelete", "summary": "Delete a label", "description": "Deletes the matching label.", "tags": [ "labels" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/labels/{label_id}/assets": { "parameters": [ { "name": "label_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4LabelsAssetsByLabelIdGet", "summary": "List assets in a label", "description": "Lists assets in a label.", "tags": [ "assets", "labels" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request. More records may exist (as denoted by\nthe `meta.total_count` value).\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } }, { "in": "query", "name": "search", "description": "Set it to any URL-encoded query to fetch only assets that match your\ncriteria.\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "extension:png" }, { "in": "query", "name": "fields", "description": "Set it to a comma-separated list (no spaces) of any of the following\nattributes of the asset to return as part of the asset's attributes in\nthe response.\n\nAllowed values: \n\n- `created_at`\n- `updated_at`\n- `cdn_url`\n- `availability`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "cdn_url" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the asset you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values: \n\n- `attachments`\n- `brandfolder`\n- `collections`\n- `custom_fields`\n- `section`\n- `tags`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "tags" } ], "responses": { "200": { "description": "The matching label assets.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "404": { "description": "This occurs for CDN URLs of assets that are pending approval or\nunpublished. \n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/labels/{label_id}/move": { "parameters": [ { "name": "label_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "put": { "operationId": "opIdApiV4MoveLabelPut", "summary": "Move the label", "description": "Assigns the label a new parent label.", "tags": [ "labels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "parent_key": { "type": "string", "description": "Set this to the ID of the label's new parent label.", "example": "abc123" } }, "required": [ "parent_key" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The updated label.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Label" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/invitations": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersInvitationsByBrandfolderIdGet", "summary": "List invitations to a Brandfolder", "description": "Lists invitations to the matching Brandfolder.\n", "tags": [ "invitations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the invitations you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values:\n\n- `inviter`\n- `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviter" } ], "responses": { "200": { "description": "Invitations to the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4BrandfoldersInvitationsByBrandfolderIdPost", "summary": "Create an invitation to a Brandfolder", "description": "Creates an invitation to the matching Brandfolder.\n", "tags": [ "invitations" ], "requestBody": { "description": "An invitation to the Brandfolder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreationRequest" } } } }, "responses": { "200": { "description": "The new invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/Invitation" } } }, "meta": { "type": "object", "properties": { "auto_accepted": { "type": "boolean", "example": false } } } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/organizations/{organization_id}/invitations": { "parameters": [ { "name": "organization_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-cocc75" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4OrganizationsInvitationsByOrganizationIdGet", "summary": "List invitations to an organization", "description": "Lists invitations to the matching organization.\n", "tags": [ "invitations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the invitations you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values:\n\n- `inviter`\n- `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviter" } ], "responses": { "200": { "description": "Invitations to the matching organization.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4OrganizationsInvitationsByOrganizationIdPost", "summary": "Create an invitation to an organization", "description": "Creates an invitation to the matching organization.\n", "tags": [ "invitations" ], "requestBody": { "description": "An invitation to the organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreationRequest" } } } }, "responses": { "200": { "description": "The new invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/Invitation" } } }, "meta": { "type": "object", "properties": { "auto_accepted": { "type": "boolean", "example": false } } } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections/{collection_id}/invitations": { "parameters": [ { "name": "collection_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsInvitationsByCollectionIdGet", "summary": "List invitations to a collection", "description": "Lists invitations to the matching collection.\n", "tags": [ "invitations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the invitations you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values:\n\n- `inviter`\n- `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviter" } ], "responses": { "200": { "description": "Invitations to the matching collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4CollectionsInvitationsByCollectionIdPost", "summary": "Create an invitation to a collection", "description": "Creates an invitation to the matching collection.\n", "tags": [ "invitations" ], "requestBody": { "description": "An invitation to the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreationRequest" } } } }, "responses": { "200": { "description": "The new invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/Invitation" } } }, "meta": { "type": "object", "properties": { "auto_accepted": { "type": "boolean", "example": false } } } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/portals/{portal_id}/invitations": { "parameters": [ { "name": "portal_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4PortalsInvitationsByPortalIdGet", "summary": "List invitations to a portal", "description": "Lists invitations to the matching portal.\n\n> **Important:** You can get the portal ID in the response from **Fetch an\norganization**.\n", "tags": [ "invitations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the invitations you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values:\n\n- `inviter`\n- `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviter" } ], "responses": { "200": { "description": "Invitations to the matching portal.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4PortalsInvitationsByPortalIdPost", "summary": "Create an invitation to a portal", "description": "Creates an invitation to the matching portal.\n", "tags": [ "invitations" ], "requestBody": { "description": "An invitation to the portal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreationRequest" } } } }, "responses": { "200": { "description": "The new invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/Invitation" } } }, "meta": { "type": "object", "properties": { "auto_accepted": { "type": "boolean", "example": false } } } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandguides/{brandguide_id}/invitations": { "parameters": [ { "name": "brandguide_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandguidesInvitationsByBrandguideIdGet", "summary": "List invitations to a Brandguide", "description": "Lists invitations to the matching Brandguide.\n\n> **Important:** You can get the Brandguide ID in the response from **Fetch\nan organization**.\n", "tags": [ "invitations" ], "parameters": [ { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to a comma-separated list (no spaces) of any of the following\nrecord names to return those records related to the invitations you're\nfetching. Related records are returned in an `included` array in the\nresponse.\n\nAllowed values:\n\n- `inviter`\n- `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviter" } ], "responses": { "200": { "description": "Invitations to the matching Brandguide.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4BrandguidesInvitationsByBrandguideIdPost", "summary": "Create an invitation to a Brandguide", "description": "Creates an invitation to the matching Brandguide.\n", "tags": [ "invitations" ], "requestBody": { "description": "An invitation to the Brandguide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreationRequest" } } } }, "responses": { "200": { "description": "The new invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "$ref": "#/components/schemas/Invitation" } } }, "meta": { "type": "object", "properties": { "auto_accepted": { "type": "boolean", "example": false } } } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/invitations/{invitation_id}": { "parameters": [ { "name": "invitation_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "a3dlao-hd6so4-7d91d2" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4InvitationsByIdGet", "summary": "Fetch an invitation", "description": "Gets a matching invitation.\n", "tags": [ "invitations" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "query", "name": "fields", "description": "Set it to `created_at` to return it as part of the invitation's\nattributes in the response.\n\nAllowed value: `created_at`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "created_at" }, { "in": "query", "name": "include", "description": "Set it to `inviteable` to include the Brandfolder, Collection, or\nOrganization that this Invitation is for.\n\nAllowed value: `inviteable`\n\nWARNING: This parameter can slow response times.\n", "schema": { "type": "string" }, "example": "inviteable" } ], "responses": { "200": { "description": "The matching invitation.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invitation" } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4InvitationsByIdDelete", "summary": "Delete an invitation", "description": "Deletes the matching invitation.\n", "tags": [ "invitations" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/organizations/{organization_id}/user_permissions": { "parameters": [ { "name": "organization_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-cocc75" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4OrganizationsUserPermissionsByOrganizationIdGet", "summary": "List user permissions for an organization", "description": "Lists user permissions for the matching organization.\n", "tags": [ "user_permissions" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } } ], "responses": { "200": { "description": "User permissions for the matching organization.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionToOrganization" } }, "included": { "type": "array", "description": "An array listing the organization and its users.", "items": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/Organization" } ] } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/brandfolders/{brandfolder_id}/user_permissions": { "parameters": [ { "name": "brandfolder_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4BrandfoldersUserPermissionsByBrandfolderIdGet", "summary": "List user permissions for a Brandfolder", "description": "Lists user permissions for the matching Brandfolder.\n", "tags": [ "user_permissions" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } } ], "responses": { "200": { "description": "User permissions for the matching Brandfolder.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionToBrandfolder" } }, "included": { "type": "array", "description": "An array listing the Brandfolder and its users.", "items": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/Brandfolder" } ] } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/collections/{collection_id}/user_permissions": { "parameters": [ { "name": "collection_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4CollectionsUserPermissionsByCollectionIdGet", "summary": "List user permissions for a collection", "description": "Lists user permissions for the matching collection.\n", "tags": [ "user_permissions" ], "parameters": [ { "in": "query", "name": "page", "description": "Set this to a positive, non-zero integer representing the page number of\nthe results you want.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1 } }, { "in": "query", "name": "per", "description": "Set this pagination parameter to the maximum number of results you want\nto receive back from your request.\n", "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 3000, "default": 100 } } ], "responses": { "200": { "description": "User permissions for the matching collection.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionToCollection" } }, "included": { "type": "array", "description": "An array listing the collection and its users.", "items": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "$ref": "#/components/schemas/Collection" } ] } }, "meta": { "$ref": "#/components/schemas/PaginationMetadataResponse" } }, "required": [ "data", "meta" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/user_permissions/{user_permission_id}": { "parameters": [ { "name": "user_permission_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "p2f0ou-3geb4w-123456" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4UserPermissionsByIdGet", "summary": "Fetch a user permission", "description": "Returns the matching user permission.\n", "tags": [ "user_permissions" ], "parameters": [ { "in": "header", "name": "Accept", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "responses": { "200": { "description": "The matching user permission.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p2f0ou-3geb4w-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "user_permissions" ] }, "attributes": { "type": "object", "properties": { "permission_level": { "type": "string", "description": "Access level to the object.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n", "enum": [ "guest", "collaborator", "admin", "owner" ] } } }, "relationships": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p0v24p-g7jy9k-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "users" ] } } }, "permissible": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "organizations", "brandfolders", "collections" ] } } } } } }, "required": [ "id", "type", "attributes", "relationships" ] } }, "required": [ "data" ] } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4UserPermissionsByIdDelete", "summary": "Delete a user permission", "description": "Deletes the matching user permission, revoking the user's access to that\nobject. \n", "tags": [ "user_permissions" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/webhooks/send": { "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "post": { "servers": [ { "url": "https://brandfolder.com/api/v1" } ], "operationId": "opIdApiV4WebhooksSendPost", "summary": "Generate a test webhook", "description": "Generates a test Webhook.\n\n> **Important:** This operation uses server `https://brandfolder.com/api/v1` (notice the version is `v1`).\n\n> **Important:** Ensure that your code is able to receive a Brandfolder\nWebhook using this endpoint before creating a production Webhook\nsubscription.\n\nIf you receive a `202` response at this endpoint, then a fake Webhook\nnotification will POST to your `callback_url`. If you don't receive anything\nat your `callback_url` within a few minutes, it is likely that\n`callback_url` is invalid. Please ensure the URL begins with `https://` and\nthat it is a public domain (not `localhost`, behind a firewall, or any other\ndomain requiring authentication) which can receive HTTP `POST` requests and\nrespond with a `2xx` HTTP status code. \n", "tags": [ "webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Event type.", "enum": [ "asset.create", "asset.update", "asset.delete" ], "example": "asset.create" }, "resource_key": { "type": "string", "description": "Brandfolder ID.", "example": "oqgiju-21olts-ce9egi" }, "resource_type": { "type": "string", "description": "The type of resource the event acts on. Currently, `brandfolder` is the only supported type.", "example": "brandfolder", "enum": [ "brandfolder" ] }, "callback_url": { "type": "string", "description": "An HTTPS URL where webhook data will be posted.\n\nPlease ensure the URL begins with `https://` and that it is a public domain (not `localhost`, behind a firewall, or any other domain requiring authentication) which can receive HTTP `POST` requests and respond with a `2xx` HTTP status code.\n", "example": "https://your_company.com/your_callback_url" }, "asset_key": { "type": "string", "description": "Asset ID override", "example": "oqgkkd-fr5iv4-443db" }, "organization_key": { "type": "string", "description": "organization ID override.", "example": "oqgkkd-fr5iv4-cocc75" } }, "required": [ "event_type", "resource_key", "resource_type", "callback_url" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "202": { "description": "The webhook was successfully created.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "default": "Added demo webhook to queue" }, "status": { "type": "string", "default": "ok" } } } } } }, "400": { "description": "Invalid Payload Provided\n" }, "403": { "description": "Permission Denied for Provided Resource\n" }, "404": { "description": "Provided Resource Does Not Exist\n" }, "409": { "description": "Subscription Already Exists\n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/webhooks": { "servers": [ { "url": "https://brandfolder.com/api/v1" } ], "parameters": [ { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4WebhooksGet", "summary": "List active webhooks", "description": "List all active webhooks. \n\n> **Important:** This operation uses server `https://brandfolder.com/api/v1` (notice the version is `v1`).\n", "tags": [ "webhooks" ], "responses": { "200": { "description": "The active webhooks.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid header provided\n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "post": { "operationId": "opIdApiV4WebhooksPost", "summary": "Create a webhook subscription", "description": "Subscribes to get Webhook notifications for the specified asset event type\nwithin the specified Brandfolder. \n\n> **Important:** This operation uses server `https://brandfolder.com/api/v1` (notice the version is `v1`).\n", "tags": [ "webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "event_type": { "type": "string", "description": "An event type. Here are the currently supported event types:\n\n- `asset.create`: A new asset has been created within the subscribed Brandfolder\n- `asset.update`: Asset data has been updated within the subscribed Brandfolder\n- `asset.delete`: An asset has been removed from within the subscribed Brandfolder\n", "example": "asset.create", "enum": [ "asset.create", "asset.update", "asset.delete" ] }, "resource_key": { "type": "string", "description": "The ID of the resource being acted on.", "example": "oqgiju-21olts-ce9egi" }, "resource_type": { "type": "string", "description": "The type of resource the event acts on. Currently, `brandfolder` is the only supported type.", "example": "brandfolder" }, "callback_url": { "type": "string", "description": "An HTTPS URL where webhook data will be posted.\n\nPlease ensure the URL begins with `https://` and that it is a public domain (not `localhost`, behind a firewall, or any other domain requiring authentication) which can receive HTTP `POST` requests and respond with a `2xx` HTTP status code.\n", "example": "https://your_company.com/your_callback_url" } }, "required": [ "event_type", "resource_key", "resource_type", "callback_url" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "The webhook was successfully created.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid Payload Provided\n" }, "403": { "description": "Permission Denied for Provided Resource\n" }, "404": { "description": "Provided Resource Does Not Exist\n" }, "409": { "description": "Subscription Already Exists\n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/webhooks/{webhook_id}": { "servers": [ { "url": "https://brandfolder.com/api/v1" } ], "parameters": [ { "name": "webhook_id", "in": "path", "schema": { "type": "string" }, "required": true, "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, { "in": "header", "name": "Content-Type", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" }, { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdApiV4WebhooksByIdGet", "summary": "Fetch an active webhook", "description": "Gets an active matching webhook. \n\n> **Important:** This operation uses server `https://brandfolder.com/api/v1` (notice the version is `v1`).\n", "tags": [ "webhooks" ], "responses": { "200": { "description": "The webhook details.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "400": { "description": "Invalid Header Provided\n" }, "404": { "description": "The Requested Webhook Does Not Exist\n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "opIdApiV4WebhooksByIdDelete", "summary": "Delete a webhook", "description": "Deletes the matching webhook, so that data is no longer sent by it to its\nassociated callback URL.\n\n> **Important:** This operation uses server `https://brandfolder.com/api/v1` (notice the version is `v1`).\n", "tags": [ "webhooks" ], "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Invalid Header Provided\n" }, "404": { "description": "Could Not Determine This Webhook Exists or the Requester Does Not Own\nthe Webhook.\n" }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/upload_requests": { "parameters": [ { "$ref": "#/components/parameters/Authorization" } ], "get": { "operationId": "opIdStorageserviceUploadRequestsGet", "summary": "Get an upload URL", "description": "Gets an upload URL.\n\n> **NOTE:** After uploading a file, you can add it as Brandfolder asset by\ncopying the `object_url` value from the response into your request body's\n`attachments.url` property. See [Create assets in a\nBrandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost)\nfor details.\n", "tags": [ "binary_upload" ], "responses": { "200": { "description": "The request URL(s).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": "string", "description": "A signed upload_url that allows a user to PUT a file." }, "resumable_upload_url": { "type": "string", "description": "A signed URL that allows a user to resume PUT operations for a\nfile.\n" }, "service": { "type": "string", "description": "The storage service type." }, "object_url": { "type": "string", "description": "An attachment URL to provide to the Brandfolder create assets\nAPI call.\n" } } } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/upload_url": { "put": { "servers": [ { "url": "upload_url" } ], "security": [], "operationId": "opIdStorageserviceBfUploadRequestBucketPut", "summary": "Upload a file", "description": "To upload file data to the storage bucket, copy the `upload_url` provided\nfrom the `upload_request` response body. Create a PUT request with a path to\nthe file binary. \n\n> **NOTE:** Non-Resumable Uploads use the PUT method on initial creation.\n\n> **NOTE:** After uploading the file, you can add it as Brandfolder asset by\ncopying the `object_url` value from the [Get an upload\nURL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)\nresponse into your request body's `attachments.url` property. See [Create\nassets in a\nBrandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost)\nfor details.\n", "tags": [ "binary_upload" ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "description": "Path to the file you're uploading.", "example": "@/path/to/file" } } } }, "responses": { "200": { "description": "Successful response (always an empty object)\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X PUT \\\n--data-binary @/path/to/file \\\n\"upload_url\"\n" }, { "lang": "C#", "label": "C#", "source": "No example currently available." }, { "lang": "Java", "label": "Java", "source": "No example currently available." }, { "lang": "JavaScript", "label": "JavaScript", "source": "No example currently available." }, { "lang": "Node.js", "label": "Node.js", "source": "No example currently available." }, { "lang": "Python", "label": "Python", "source": "No example currently available." }, { "lang": "PHP", "label": "PHP", "source": "No example currently available." }, { "lang": "Go", "label": "Go", "source": "No example currently available." } ] } }, "/resumable_upload_url": { "post": { "servers": [ { "url": "resumable_upload_url" } ], "security": [], "operationId": "opIdStorageserviceBfUploadRequestPost", "summary": "Resumable upload", "description": "Users uploading larger files and/or with poor connectivity can initiate a\nresumable upload session with the `resumable_upload_url` from the\n`upload_request` body.\n\nGoogle provides some great\ndocumentation\non resumable uploads (as the content will be uploaded to Google Cloud\nStorage).\n\n> **NOTE:** Resumable Uploads use the POST method on initialization and the\nPUT method after to resume upload.\n\n> **NOTE:** After uploading a file, you can add it as Brandfolder asset by\ncopying the `object_url` value from the [Get an upload\nURL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)\nresponse into your request body's `attachments.url` property. See [Create\nassets in a\nBrandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost)\nfor details.\n", "tags": [ "binary_upload" ], "parameters": [ { "in": "header", "name": "x-goog-resumable", "required": true, "schema": { "type": "string", "enum": [ "start" ] }, "example": "start" } ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "description": "Path to the file you're uploading.", "example": "@/path/to/file" } } } }, "responses": { "200": { "description": "Successful response.\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "201": { "description": "Upload was interrupted. Resume uploading at this URL.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "example": "https://storageservice.com/bf-upload-request/signed-resumable-upload-url\n" } } } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -v -X POST \\\n-H 'x-goog-resumable: start' \\\n-H 'Content-Type: image/png' \\\n--data-binary @/path/to/file \\\n\"resumable_upload_url\"\n" }, { "lang": "C#", "label": "C#", "source": "No example currently available." }, { "lang": "Java", "label": "Java", "source": "No example currently available." }, { "lang": "JavaScript", "label": "JavaScript", "source": "No example currently available." }, { "lang": "Node.js", "label": "Node.js", "source": "No example currently available." }, { "lang": "Python", "label": "Python", "source": "No example currently available." }, { "lang": "PHP", "label": "PHP", "source": "No example currently available." }, { "lang": "Go", "label": "Go", "source": "No example currently available." } ] }, "put": { "servers": [ { "url": "resumable_upload_url" } ], "security": [], "operationId": "opIdStorageserviceBfUploadRequestPut", "summary": "Resume upload", "description": "Resumes uploading a file to the same location.\n\n> **NOTE:** After uploading the file, you can add it as Brandfolder asset by\ncopying the `object_url` value from the [Get an upload\nURL](/api/brandfolder/openapi/binary_upload/opidstorageserviceuploadrequestsget)\nresponse into your request body's `attachments.url` property. See [Create\nassets in a\nBrandfolder](/api/brandfolder/openapi/assets/opidapiv4collectionsassetsbybrandfolderidpost)\nfor details.\n", "tags": [ "binary_upload" ], "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary", "description": "Path to the file you're uploading.", "example": "@/path/to/your-file" } } } }, "responses": { "200": { "description": "Successful response.\n", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "201": { "description": "Upload was interrupted. Resume uploading at this URL.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "example": "https://storageservice.com/bf-upload-request/signed-resumable-upload-url\n" } } } } } }, "default": { "description": "Generic error payload", "content": { "application/json": { "schema": { "type": "string" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X PUT \\\n-H 'Content-Type: image/png' \\\n--data-binary @/path/to/file \\\n\"resumable_upload_url\"\n" }, { "lang": "C#", "label": "C#", "source": "No example currently available." }, { "lang": "Java", "label": "Java", "source": "No example currently available." }, { "lang": "JavaScript", "label": "JavaScript", "source": "No example currently available." }, { "lang": "Node.js", "label": "Node.js", "source": "No example currently available." }, { "lang": "Python", "label": "Python", "source": "No example currently available." }, { "lang": "PHP", "label": "PHP", "source": "No example currently available." }, { "lang": "Go", "label": "Go", "source": "No example currently available." } ] } } }, "components": { "securitySchemes": { "APIToken": { "scheme": "bearer", "type": "http", "description": "API Token." } }, "parameters": { "Authorization": { "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" }, "description": "Bearer token for authentication" } }, "schemas": { "BrandfolderAttributes": { "title": "Brandfolder attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the brandfolder.", "example": "Brandfolder" }, "privacy": { "type": "string", "description": "The privacy setting of the brandfolder.", "example": "private" }, "slug": { "type": "string", "description": "The URL-friendly slug of the brandfolder.", "example": "brandfolder" }, "tagline": { "type": "string", "description": "The tagline of the brandfolder.", "example": "You expected this - Brandfolder's Brandfolder!", "default": "" } }, "required": [ "name", "privacy", "slug", "tagline" ] }, "Brandfolder": { "title": "Brandfolder", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "brandfolders" ] }, "attributes": { "$ref": "#/components/schemas/BrandfolderAttributes" } }, "required": [ "id", "type", "attributes" ] }, "PaginationMetadataResponse": { "title": "Pagination metadata", "description": "Page context information.", "type": "object", "properties": { "current_page": { "type": "integer", "format": "int32", "example": 1, "minimum": 1, "default": 1 }, "next_page": { "type": "object", "nullable": true, "example": null, "default": null }, "prev_page": { "type": "object", "nullable": true, "example": null, "default": null }, "total_pages": { "example": 1, "minimum": 1, "default": 1 }, "total_count": { "example": 1, "minimum": 0, "default": 0 } }, "required": [ "current_page", "next_page", "prev_page", "total_pages", "total_count" ] }, "CollectionAttributes": { "title": "Collection attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the collection.", "example": "My collection" }, "tagline": { "type": "string", "description": "The tagline of the collection.", "example": "My collection tag line" }, "slug": { "type": "string", "description": "The URL-friendly slug of the collection.", "example": "my-collection" }, "public": { "type": "boolean", "description": "Set to `true` for hassle-free sharing, allowing search engines to index your brand assets. Otherwise, set to `false` to share only with the users you specify.", "example": false, "default": false }, "stealth": { "type": "boolean", "description": "Set to `true` to remove the collection from appearing in web searches.", "example": false, "default": false }, "is_workspace": { "type": "boolean", "description": "Set to `true` if the collection is a Brandfolder workspace.", "example": false, "default": false } } }, "Collection": { "title": "Collection", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "collections" ] }, "attributes": { "$ref": "#/components/schemas/CollectionAttributes" } }, "required": [ "id", "type", "attributes" ] }, "CustomFieldKeyAttributes": { "title": "Custom field key attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The key name.", "example": "color" }, "allowed_values": { "type": "array", "description": "The `value` that can be used with this `key` when creating or updating any Custom Field on an Asset must be one of these strings. If not included or empty array `[]`, the `values` are unrestricted.", "items": { "type": "string" }, "example": [ "red", "white", "blue" ] }, "position": { "type": "integer", "format": "int32", "description": "Sets the location of the custom field among other custom fields in the Brandfolder UI.", "minimum": 0, "example": 0 }, "prioritized": { "type": "boolean", "description": "Set to `true` to display the custom field in asset previews. A Brandfolder can have up to five prioritized custom fields.", "example": false }, "required": { "type": "boolean", "description": "If set to `true`, users uploading an asset must input the custom field before uploading the asset. Children of dependent custom fields can also be marked as required.", "example": false }, "restricted": { "type": "boolean", "description": "If set to `true`, the field value is restricted to a set of allowed values (see `allowed_values`); otherwise, the field value is unrestricted.", "example": true } }, "required": [ "name" ] }, "CustomFieldKey": { "title": "Custom field key", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "plqlkk-22rw6g-3dqgx0" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "custom_field_keys" ] }, "attributes": { "$ref": "#/components/schemas/CustomFieldKeyAttributes" } }, "required": [ "id", "type", "attributes" ] }, "OrganizationAttributes": { "title": "Organization attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the brandfolder.", "example": "Brandfolder's Organization" }, "tagline": { "type": "string", "description": "The tagline of the brandfolder.", "example": "An example tagline for the Organization" }, "slug": { "type": "string", "description": "The URL-friendly slug of the brandfolder.", "example": "brandfolder-organization" } } }, "Organization": { "title": "Organization", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-cocc75" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "organizations" ] }, "attributes": { "$ref": "#/components/schemas/OrganizationAttributes" } }, "required": [ "id", "type", "attributes" ] }, "AssetAttributes": { "title": "Asset attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the asset.", "example": "Brandfolder Logo" }, "description": { "type": "string", "description": "The description of the asset.", "example": "Brandfolder's logo in print ready format" }, "thumbnail_url": { "type": "string", "description": "The online location of the asset.", "example": "https://example.com/example.jpg?Expires=1624742369" }, "approved": { "type": "boolean", "description": "If `true`, this asset is approved; otherwise, it's not.", "example": true } } }, "Asset": { "title": "Asset", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "generic_files" ] }, "attributes": { "$ref": "#/components/schemas/AssetAttributes" } }, "required": [ "id", "type", "attributes" ] }, "AssetAttributesRequest": { "title": "Asset attributes request body", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the asset.", "example": "Brandfolder Logo" }, "description": { "type": "string", "description": "The description of the asset.", "example": "Brandfolder's logo in print ready format" }, "thumbnail_url": { "type": "string", "description": "The online location of the asset.", "example": "https://example.com/example.jpg?Expires=1624742369" }, "approved": { "type": "boolean", "description": "If `true`, this asset is approved; otherwise, it's not.", "example": true }, "availability_start": { "type": "string", "format": "date-time", "description": "This represents the publish/availability date in Brandfolder, the label `draft` will show.\n", "example": "2024-02-23T18:22:49.771Z" }, "availability_end": { "type": "string", "format": "date-time", "description": "This represents the expiration date in brandfolder, the label `expired` will show.\n", "example": "2025-02-23T18:22:49.771Z" }, "attachments": { "description": "An array of Attachment objects to add to the Asset (these do not overwrite exisiting Attachments).\n", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "A fully-formed URL of the file to upload (required for each new Attachment).\n", "example": "https://example.com/new-attachment.jpg" }, "filename": { "type": "string", "description": "A complete file name, with extension.", "example": "new-attachment.jpg" } }, "required": [ "url" ] } } }, "required": [ "name" ] }, "TagAttributes": { "title": "Tag attributes", "type": "object", "properties": { "name": { "type": "string", "description": "A keyword associated with exactly one asset.\n\nFor example, if you have several assets that represent products you sell, you might create a \"product\" tag for each one. If you modify or delete the \"product\" tag for any particular Asset, it doesn't affect other tags with the same value on other assets.\n", "example": "product" }, "auto_generated": { "type": "boolean", "description": "If `true`, this tag was generated automatically by our smart analysis of file attachments; otherwise, a user created it.", "example": true }, "source": { "type": "string", "nullable": true, "description": "The tag author.", "example": "google_vision", "default": null } }, "required": [ "name" ] }, "Tag": { "title": "Tag", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "a3dlao-hd6so4-7d91d2" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "tags" ] }, "attributes": { "$ref": "#/components/schemas/TagAttributes" } }, "required": [ "id", "type", "attributes" ] }, "SectionAttributes": { "title": "Section attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the section.", "example": "My section" }, "default_asset_type": { "type": "string", "description": "The type of asset the section contains.\n", "enum": [ "GenericFile", "Color", "Font", "ExternalMedium", "Person", "Press", "Text" ], "example": "GenericFile" }, "position": { "type": "integer", "minimum": 0, "description": "A non-negative integer that represents where the section displays relative to other sections. The first position is `0`.\n", "example": 0 } } }, "Section": { "title": "Section", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "sections" ] }, "attributes": { "$ref": "#/components/schemas/SectionAttributes" } }, "required": [ "id", "type", "attributes" ] }, "CustomFieldValueAttributes": { "title": "Custom field value attributes", "type": "object", "properties": { "key": { "type": "string", "description": "A key name.", "example": "Campaign" }, "value": { "type": "string", "description": "The value for the key.", "example": "Fall" } } }, "CustomFieldValue": { "title": "Custom field value", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "r79p3j4gbcgtv33gbsqrxb" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "custom_field_values" ] }, "attributes": { "$ref": "#/components/schemas/CustomFieldValueAttributes" } }, "required": [ "id", "type", "attributes" ] }, "AttachmentAttributes": { "title": "Attachment attributes", "type": "object", "properties": { "mimetype": { "type": "string", "description": "The MIME type of the file.", "example": "image/png" }, "extension": { "type": "string", "description": "The file suffix.", "example": "png" }, "filename": { "type": "string", "description": "The complete file name, including its suffix (if any).", "example": "brandfolder_logo.png" }, "size": { "type": "integer", "format": "int32", "description": "The file size in bytes.", "minimum": 0, "example": 123456 }, "width": { "type": "integer", "format": "int32", "description": "The image width in pixels.", "minimum": 0, "example": 1920 }, "height": { "type": "integer", "format": "int32", "description": "The image height in pixels.", "minimum": 0, "example": 1080 }, "url": { "type": "string", "description": "The file URL.", "example": "https://some_domain.com/brandfolder_logo.png?expiry=1625260667" }, "position": { "type": "integer", "format": "int32", "description": "The attachment ranking position in the Brandfolder UI.", "minimum": 0, "example": 0 }, "thumbnail_url": { "type": "string", "description": "The URL of the the attachment's thumbnail image.", "example": "https://some_domain.com/some_thumbnail.png" } }, "required": [ "filename", "mimetype", "url" ] }, "Attachment": { "title": "Attachment", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr3j84-33j7db" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "attachments" ] }, "attributes": { "$ref": "#/components/schemas/AttachmentAttributes" } }, "required": [ "id", "type", "attributes" ] }, "LabelAttributes": { "title": "Label attributes", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the label.", "example": "onboarding" }, "path": { "type": "array", "items": { "schema": { "type": "string" } }, "example": [ "oqgkkd-fr5iv4-443db", "abc123" ], "description": "Hierarchy of label IDs, starting with this label's ID." }, "position": { "type": "integer", "format": "int32", "minimum": 0, "description": "Label location represented by a positive integer; `0` is the first position.", "example": 0 }, "depth": { "type": "integer", "description": "The depth of the label hierarchy. A root level label's depth is `1`, a label with one parent has depth of `2`, and so on.\n", "example": 2 } } }, "Label": { "title": "Label", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-443db" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "labels" ] }, "attributes": { "$ref": "#/components/schemas/LabelAttributes" } }, "required": [ "id", "type", "attributes" ] }, "InvitationAttributes": { "title": "Invitation attributes", "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the recipient.", "example": "test@example.com" }, "permission_level": { "type": "string", "description": "Access to grant the recipient.", "example": "guest" }, "personal_message": { "type": "string", "description": "A message for the recipient.", "example": "Welcome to my Brandfolder!" }, "invitation_url": { "type": "string", "description": "The invitation's URL.", "example": "https://brandfolder.com/invitations/abc123" } }, "required": [ "email" ] }, "Invitation": { "title": "Invitation", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "a3dlao-hd6so4-7d91d2" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "invitations" ] }, "attributes": { "$ref": "#/components/schemas/InvitationAttributes" } }, "required": [ "id", "type", "attributes" ] }, "InvitationCreationRequest": { "title": "Invitation creation request", "type": "object", "properties": { "data": { "type": "object", "properties": { "attributes": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of invitee.", "example": "test@example.com" }, "permission_level": { "type": "string", "description": "Access to grant invitee.\n\n> **Note:** `owner` is only valid when inviting someone to an Organization.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n", "enum": [ "guest", "collaborator", "admin", "owner" ], "example": "guest" }, "personal_message": { "type": "string", "description": "A message for invitee.", "example": "Welcome to my Brandfolder!" }, "prevent_email": { "type": "boolean", "description": "Set this to `true` to skip sending an invitation email to the invitee.", "default": false } }, "required": [ "email", "permission_level" ] } }, "required": [ "attributes" ] } }, "required": [ "data" ] }, "UserPermissionToOrganization": { "title": "User permission to an organization", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p2f0ou-3geb4w-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "user_permissions" ] }, "attributes": { "type": "object", "properties": { "permission_level": { "type": "string", "description": "Access level to the object.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n", "enum": [ "guest", "collaborator", "admin", "owner" ] } } }, "relationships": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p0v24p-g7jy9k-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "users" ] } } }, "permissible": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "obte6d-45b4mo-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "organizations" ] } } } } } }, "required": [ "id", "type", "attributes", "relationships" ] }, "UserAttributes": { "title": "User attributes", "type": "object", "properties": { "email": { "type": "string", "description": "The user's email address.", "example": "jane.doe@smartsheet.com" }, "first_name": { "type": "string", "description": "The user's first name.", "example": "Jane" }, "last_name": { "type": "string", "description": "The user's last name.", "example": "Doe" } }, "required": [ "email", "first_name", "last_name" ] }, "User": { "title": "User", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p0v24p-g7jy9k-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "users" ] }, "attributes": { "$ref": "#/components/schemas/UserAttributes" } }, "required": [ "id", "type", "attributes" ] }, "UserPermissionToBrandfolder": { "title": "User permission to a Brandfolder", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p2f0ou-3geb4w-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "user_permissions" ] }, "attributes": { "type": "object", "properties": { "permission_level": { "type": "string", "description": "Access level to the object.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n", "enum": [ "guest", "collaborator", "admin", "owner" ] } } }, "relationships": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p0v24p-g7jy9k-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "users" ] } } }, "permissible": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgiju-21olts-ce9egi" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "brandfolders" ] } } } } } }, "required": [ "id", "type", "attributes", "relationships" ] }, "UserPermissionToCollection": { "title": "User permission to a collection", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p2f0ou-3geb4w-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "user_permissions" ] }, "attributes": { "type": "object", "properties": { "permission_level": { "type": "string", "description": "Access level to the object.\n\nLearn more about the permission levels you can grant Users in our Knowledge Base article on User Permissions.\n", "enum": [ "guest", "collaborator", "admin", "owner" ] } } }, "relationships": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "p0v24p-g7jy9k-123456" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "users" ] } } }, "permissible": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "type": { "type": "string", "description": "The type of the resource.", "enum": [ "collections" ] } } } } } }, "required": [ "id", "type", "attributes", "relationships" ] }, "WebhookAttributes": { "type": "object", "title": "Webhook subscription attributes", "properties": { "event_type": { "type": "string", "description": "An event type. Here are the currently supported event types:\n\n- `asset.create`: A new asset has been created within the subscribed Brandfolder\n- `asset.update`: Asset data has been updated within the subscribed Brandfolder\n- `asset.delete`: An asset has been removed from within the subscribed Brandfolder\n", "example": "asset.create", "enum": [ "asset.create", "asset.update", "asset.delete" ] }, "resource_key": { "type": "string", "description": "brandfolder_id", "example": "oqgiju-21olts-ce9egi" }, "resource_type": { "type": "string", "example": "brandfolder" }, "callback_url": { "type": "string", "example": "https://your_company.com/your_callback_url" } }, "required": [ "event_type", "resource_key", "resource_type", "callback_url" ] }, "Webhook": { "title": "Webhook", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the resource instance.", "example": "oqgkkd-fr5iv4-hh142d" }, "attributes": { "$ref": "#/components/schemas/WebhookAttributes" } }, "required": [ "id", "attributes" ] } } }, "security": [ { "APIToken": [] } ] }