{ "openapi": "3.2.0", "info": { "title": "TrueLoyal Advocacy API", "version": "2", "description": "The reference for every endpoint of the TrueLoyal Advocacy API. Start with the [guides](guides/introduction.html) for authentication, pagination, versioning and the JSON:API conventions the API follows.\n\nDownload the OpenAPI definition: [YAML](advocacy-openapi.yml) or [JSON](advocacy-openapi.json)." }, "servers": [ { "url": "https://api.tintup.com" } ], "tags": [ { "name": "authentication", "summary": "OAuth", "description": "The OAuth 2.0 endpoints. How to create an OAuth application and get an access token is covered in the [Authentication guide](advocacy/guides/authentication.html)." }, { "name": "group_common", "summary": "Common" }, { "name": "accounts", "parent": "group_common", "summary": "Accounts" }, { "name": "authentication_factors", "parent": "group_common", "summary": "Authentication Factors" }, { "name": "domains", "parent": "group_common", "summary": "Domains" }, { "name": "email_templates", "parent": "group_common", "summary": "Email Templates" }, { "name": "fonts", "parent": "group_common", "summary": "Fonts" }, { "name": "oauth_applications", "parent": "group_common", "summary": "OAuth 2.0 Applications" }, { "name": "privacy_requests", "parent": "group_common", "summary": "Privacy Requests" }, { "name": "roles", "parent": "group_common", "summary": "Roles" }, { "name": "subaccounts", "parent": "group_common", "summary": "Subaccounts", "description": "A subaccount is an account that can be accessed directly using the specified account credentials, such as an\nInstagram business or creator account or a Facebook page." }, { "name": "team_users", "parent": "group_common", "summary": "Team Users" }, { "name": "teams", "parent": "group_common", "summary": "Teams" }, { "name": "group_experience_builder", "summary": "Experience Builder" }, { "name": "experiences", "parent": "group_experience_builder", "summary": "Experiences" }, { "name": "form_submissions", "parent": "group_experience_builder", "summary": "Form Submissions" }, { "name": "group_ecommerce", "summary": "E-commerce" }, { "name": "product_accounts", "parent": "group_ecommerce", "summary": "Product Accounts" }, { "name": "product_feeds", "parent": "group_ecommerce", "summary": "Product Feeds" }, { "name": "product_tags", "parent": "group_ecommerce", "summary": "Product Tags" }, { "name": "products", "parent": "group_ecommerce", "summary": "Products" }, { "name": "group_rights_management", "summary": "Rights Management" }, { "name": "right_request_templates", "parent": "group_rights_management", "summary": "Right Request Templates" }, { "name": "right_request_terms", "parent": "group_rights_management", "summary": "Right Request Terms" }, { "name": "right_requests", "parent": "group_rights_management", "summary": "Right Requests" }, { "name": "group_boards", "summary": "Boards" }, { "name": "tints", "parent": "group_boards", "summary": "Boards" }, { "name": "ctas", "parent": "group_boards", "summary": "CTAs" }, { "name": "personalizations", "parent": "group_boards", "summary": "Personalizations" }, { "name": "posts_summaries", "parent": "group_boards", "summary": "Post Summaries" }, { "name": "posts", "parent": "group_boards", "summary": "Posts" }, { "name": "posts_replies", "parent": "group_boards", "summary": "Replies" }, { "name": "saved_filters", "parent": "group_boards", "summary": "Saved Filters" }, { "name": "social_feeds", "parent": "group_boards", "summary": "Social Feeds" }, { "name": "group_tintmix", "summary": "TINTmix" }, { "name": "mixes", "parent": "group_tintmix", "summary": "Mixes" }, { "name": "group_ugc_studio", "summary": "UGC Studio" }, { "name": "assets", "parent": "group_ugc_studio", "summary": "Assets" }, { "name": "collections", "parent": "group_ugc_studio", "summary": "Collections" }, { "name": "marketing_integrations", "parent": "group_ugc_studio", "summary": "Marketing Integrations" }, { "name": "group_publisher", "summary": "Publisher" }, { "name": "campaigns", "parent": "group_publisher", "summary": "Campaigns" }, { "name": "scheduled_contents", "parent": "group_publisher", "summary": "Scheduled Content" }, { "name": "group_webhooks", "summary": "Webhooks" }, { "name": "webhooks", "parent": "group_webhooks", "summary": "Webhooks", "description": "A webhook subscribes to exactly one event. Create a separate webhook per event, which lets each one carry its\nown filter, serialization and body settings. See [Receiving Webhooks](advocacy/guides/receiving-webhooks.html) for how\nevents are delivered, and [Webhook Events](advocacy/webhook-events/overview.html) for what each event contains.\n\nBeyond the endpoint and the event, a webhook can set a filter, the HTTP method, extra request headers, which\nrelated resources to include, which fields to keep, and a Liquid template that reshapes the body entirely." }, { "name": "webhook_events", "parent": "group_webhooks", "summary": "Webhook Event Log", "description": "Every event we send is recorded with the payload, its delivery status and, with `include=attempts`, each\ndelivery attempt and your endpoint's response. Use these endpoints to debug your endpoint or to recover events\nyou missed. The event `id` is the `data.id` of the payload." }, { "name": "account_events", "x-sourcey-hide": true, "summary": "Accounts", "description": "Events about the social and integration accounts connected to your team." }, { "name": "asset_events", "x-sourcey-hide": true, "summary": "Assets", "description": "Events about the assets in your team's UGC Studio library, and their exports." }, { "name": "form_submission_events", "x-sourcey-hide": true, "summary": "Form Submissions", "description": "Events about the submissions to your team's experiences and forms, and their exports." }, { "name": "post_events", "x-sourcey-hide": true, "summary": "Posts", "description": "Events about the posts on your team's boards, and their exports." }, { "name": "product_feed_events", "x-sourcey-hide": true, "summary": "Product Feeds", "description": "Events about your team's product feeds." }, { "name": "team_user_events", "x-sourcey-hide": true, "summary": "Team Users", "description": "Events about the users of your team." }, { "name": "transaction_events", "x-sourcey-hide": true, "summary": "Transactions", "description": "Events about your team's loyalty transactions." } ], "paths": { "/oauth/authorize": { "get": { "servers": [ { "url": "https://id.tintup.com" }, { "url": "https://id.trueloyal.com" } ], "security": [], "summary": "Authorize an application using the authorization code flow", "description": "Redirect the user to this URL to request authorization. The user signs in (if needed) and approves the requested scopes, after which they are redirected to `redirect_uri` with a `code` query parameter (and the `state` you provided). The code expires after 5 minutes; exchange it for an access token with [Create an access token](#operation-oauth-token-post). PKCE is required for public (non-confidential) applications and recommended for all: send a `code_challenge` here and the matching `code_verifier` when exchanging the code. Applications created with the API are confidential.", "operationId": "authorizeOAuthApplication", "tags": [ "authentication" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "A space-delimited list of the scopes to request. Defaults to `identity` when omitted.", "style": "spaceDelimited", "explode": false, "example": [ "tints:read", "posts:read" ], "schema": { "type": "array", "default": [ "identity" ], "items": { "type": "string", "enum": [ "accounts:read", "accounts:write", "activities:read", "assets:read", "assets:write", "authentication_factors:read", "authentication_factors:write", "campaigns:read", "campaigns:write", "collections:read", "collections:write", "ctas:read", "ctas:write", "domains:read", "domains:write", "ecommerce:read", "experiences:read", "experiences:write", "fonts:read", "fonts:write", "form_submissions:read", "form_submissions:write", "forms:read", "forms:write", "identity", "identity:write", "instint_updates:read", "instint_updates:write", "marketing_integrations:read", "marketing_integrations:write", "marketing_integrations_requests:read", "marketing_integrations_requests:write", "mixes:read", "mixes:write", "oauth_applications:read", "oauth_applications:write", "personalizations:read", "personalizations:write", "posts:read", "posts:write", "privacy_requests:read", "privacy_requests:write", "product_accounts:read", "product_accounts:write", "product_feeds:read", "product_feeds:write", "products:read", "products:write", "rewards:read", "right_request_templates:read", "right_request_templates:write", "right_request_terms:read", "right_request_terms:write", "right_requests:read", "right_requests:write", "roles:read", "roles:write", "saved_filters:read", "saved_filters:write", "schemas:read", "schemas:write", "social_feeds:read", "social_feeds:write", "subaccount_metrics:read", "teams:read", "teams:write", "tints:read", "tints:write", "transactions:read", "transactions:write", "users:read", "users:write", "webhooks:read", "webhooks:write" ] } } }, { "name": "response_type", "in": "query", "required": true, "description": "Must be `code` to request an authorization code.", "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "client_id", "in": "query", "required": true, "description": "The application's `client_id`.", "schema": { "type": "string", "example": "3a7c1e0b9d8f4e6a2b5c7d9e1f3a5b7c" } }, { "name": "redirect_uri", "in": "query", "required": true, "description": "One of the redirect URIs registered for the application, matched exactly.", "schema": { "type": "string", "format": "uri", "example": "https://reports.example.com/auth/callback" } }, { "name": "state", "in": "query", "description": "An opaque value that is returned unchanged to `redirect_uri`. Use it to prevent CSRF attacks.", "schema": { "type": "string", "example": "6f1c2a9e4b7d" } }, { "name": "code_challenge", "in": "query", "required": false, "description": "The PKCE code challenge derived from your `code_verifier`. Required for public (non-confidential) applications.", "schema": { "type": "string", "example": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" } }, { "name": "code_challenge_method", "in": "query", "required": false, "description": "How `code_challenge` was derived from the `code_verifier`. Required when `code_challenge` is sent. Use `S256` (the Base64URL-encoded SHA-256 hash of the verifier); `plain` sends the verifier itself.", "schema": { "type": "string", "example": "S256", "enum": [ "S256", "plain" ] } } ], "responses": { "200": { "description": "The sign-in and consent page, rendered as HTML for the user.", "content": { "text/html": { "schema": { "type": "string" } } } }, "302": { "description": "The user approved the request and is redirected to `redirect_uri` with `code` and `state` query parameters (or `error` and `error_description` if the request was denied or invalid).", "headers": { "Location": { "description": "The `redirect_uri` with the authorization result as query parameters.", "schema": { "type": "string" }, "example": "https://reports.example.com/auth/callback?code=AUTHORIZATION_CODE&state=6f1c2a9e4b7d" } } } } } }, "/oauth/token": { "post": { "servers": [ { "url": "https://id.tintup.com" }, { "url": "https://id.trueloyal.com" } ], "security": [], "summary": "Create an access token", "description": "Exchanges an authorization code for an access token (`grant_type=authorization_code`), or uses a refresh token to obtain a new access token (`grant_type=refresh_token`). Access tokens expire after one hour; use the refresh token to get a new one.", "operationId": "createOAuthAccessToken", "tags": [ "authentication" ], "requestBody": { "$ref": "#/components/requestBodies/createOAuthAccessToken" }, "responses": { "200": { "description": "The access token.", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type" ], "properties": { "access_token": { "type": "string", "description": "The access token. Send it in the `Authorization` header as `Bearer `.", "example": "4e8a1c6f3b9d2e7a0c5f8b1d4e7a9c2f" }, "token_type": { "type": "string", "description": "The type of the token.", "enum": [ "Bearer" ], "example": "Bearer" }, "expires_in": { "type": "integer", "description": "The number of seconds until the access token expires.", "example": 3600 }, "refresh_token": { "type": "string", "description": "A token to get a new access token when this one expires.", "example": "7d2f9b4e1a6c8e3f0b5d7a9c2e4f6a8b" }, "scope": { "type": "string", "description": "A space-delimited list of the granted scopes.", "example": "tints:read posts:read" }, "created_at": { "type": "integer", "description": "The time the token was created, as a Unix timestamp.", "example": 1741970527 } } }, "example": { "access_token": "4e8a1c6f3b9d2e7a0c5f8b1d4e7a9c2f", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "7d2f9b4e1a6c8e3f0b5d7a9c2e4f6a8b", "scope": "tints:read posts:read", "created_at": 1741970527 } } } }, "400": { "description": "Bad Request. The request is invalid, for example the code is invalid, expired or already used, the PKCE verifier doesn't match, or a requested scope isn't allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "The OAuth 2.0 error code.", "enum": [ "invalid_request", "invalid_grant", "invalid_scope", "unauthorized_client", "unsupported_grant_type" ], "example": "invalid_grant" }, "error_description": { "type": "string", "description": "A human-readable explanation of the error.", "example": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client." } } } } } }, "401": { "description": "Unauthorized. The client authentication failed (unknown `client_id` or wrong `client_secret`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "The OAuth 2.0 error code.", "enum": [ "invalid_client" ], "example": "invalid_client" }, "error_description": { "type": "string", "description": "A human-readable explanation of the error.", "example": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method." } } } } } } } } }, "/v2/teams/{team_id}/accounts": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "accounts:read" ] } ], "summary": "Retrieve a list of accounts", "description": "Returns the accounts the user has access to.", "operationId": "listAccounts", "tags": [ "accounts" ], "parameters": [ { "$ref": "#/components/parameters/accountRelationships" }, { "$ref": "#/components/parameters/accountFilter" }, { "$ref": "#/components/parameters/accountSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/accountsWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "accounts:write" ] } ], "summary": "Create an account", "description": "Connects an account that uses credentials (API keys, passwords, etc.) rather than OAuth, such as an SFTP product feed or a reCAPTCHA site key. The credentials are never returned. An account with the same type and external ID can only be connected once per team.", "operationId": "createAccount", "tags": [ "accounts" ], "requestBody": { "$ref": "#/components/requestBodies/createAccount" }, "responses": { "201": { "$ref": "#/components/responses/accountWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/accounts/{account_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/accountId" } ], "get": { "security": [ { "access_token": [ "accounts:read" ] } ], "summary": "Retrieve an account", "operationId": "getAccount", "tags": [ "accounts" ], "parameters": [ { "$ref": "#/components/parameters/accountRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/accountWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "security": [ { "access_token": [ "accounts:write" ] } ], "summary": "Delete an account", "description": "Only accounts that are not in use by any social feed can be deleted; otherwise a `403` error is returned.", "operationId": "deleteAccount", "tags": [ "accounts" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/accounts/{account_id}/edit": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/accountId" }, { "$ref": "#/components/parameters/accountAuthorizationOrigin" }, { "$ref": "#/components/parameters/accountAuthorizationRedirectUri" } ], "get": { "security": [ { "access_token": [ "accounts:write" ] } ], "summary": "Reauthenticate an account", "description": "Returns the URL of the third-party authorization page for the account. Open this URL (usually in a popup window) so the user can grant access again. Once the user completes the authorization flow, the account's credentials are updated and the result is delivered using the `origin` or `redirect_uri` options. The user must authorize the same external account; otherwise the callback fails with a `422` error. Accounts connected with credentials (see [Create an account](#operation-v2-teams-team-id-accounts-post)) can't be reauthenticated and return a `422` error.", "operationId": "getAccountReauthorizationUrl", "tags": [ "accounts" ], "responses": { "200": { "$ref": "#/components/responses/accountAuthorizationUrl" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/accounts/{account_id}/subaccounts": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/accountId" } ], "get": { "security": [ { "access_token": [ "accounts:read" ] } ], "summary": "Retrieve a list of subaccounts for an account", "description": "Returns the pages, organizations, channels, boards, etc. that can be accessed with the account, sorted by ID. Subaccounts are refreshed from the source whenever the account is authenticated.", "operationId": "listAccountSubaccounts", "tags": [ "subaccounts" ], "parameters": [ { "$ref": "#/components/parameters/subaccountFilter" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/subaccountsWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/accounts/new": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "type", "in": "query", "description": "The type of account to authenticate.", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/accountTypes" } ], "example": "instagram_business" } }, { "name": "site", "in": "query", "description": "The store URL, for account types that are tied to a specific site. Required for `shopify`, where it must be a `*.myshopify.com` domain (`shop` is accepted as an alias); otherwise a `422` error is returned.", "schema": { "type": "string", "example": "acme-outdoor.myshopify.com" } }, { "$ref": "#/components/parameters/accountAuthorizationOrigin" }, { "$ref": "#/components/parameters/accountAuthorizationRedirectUri" } ], "get": { "security": [ { "access_token": [ "accounts:write" ] } ], "summary": "Authenticate an account", "description": "Returns the URL of the third-party authorization page for the requested account type. Open this URL (usually in a popup window) so the user can grant access. Once the user completes the authorization flow, the account is created (and its subaccounts are fetched) and the result is delivered using the `origin` or `redirect_uri` options. If the same external account is already connected to the team, the callback fails with a `422` error.", "operationId": "getNewAccountAuthorizationUrl", "tags": [ "accounts" ], "responses": { "200": { "$ref": "#/components/responses/accountAuthorizationUrl" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/subaccounts": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "accounts:read" ] } ], "summary": "Retrieve a list of subaccounts", "operationId": "listSubaccounts", "tags": [ "subaccounts" ], "parameters": [ { "name": "filter", "in": "query", "style": "deepObject", "schema": { "type": "object", "properties": { "id": { "type": "array", "items": { "type": "string" } }, "account_id": { "type": "array", "items": { "type": "integer" } }, "q": { "type": "string" }, "type": { "type": "array", "items": { "$ref": "#/components/schemas/subaccountTypes" } }, "capability": { "type": "array", "items": { "$ref": "#/components/schemas/subaccountCapabilities" } } } } }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/subaccountsWhenAuthorized" } } } }, "/v2/teams/{team_id}/product_feeds/{product_feed_id}/product_feed_refresh_requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productFeedId" } ], "post": { "security": [ { "access_token": [ "product_feeds:write" ] } ], "summary": "Create a product feed refresh request", "operationId": "createProductFeedRefreshRequest", "description": "Asynchronously re-syncs a product feed or, for `csv` product feeds, imports a new CSV file. All product feeds, with\nthe exception of `manual` feeds, can be refreshed.\n\nWe regularly update feeds managed through our integration partners, but you may trigger a refresh using this\nendpoint at any time. This is particularly useful if you have made product changes that you would like reflected in\nTrueLoyal immediately.\n\nFor `csv` product feeds, you can use this endpoint to upload a new CSV file. The file must be in the prescribed\nformat.\n\nWhen the request is invalid, the product feed's `status` is set to `error` and `error_message` describes the\nproblem.", "tags": [ "product_feeds" ], "requestBody": { "$ref": "#/components/requestBodies/createProductFeedRefreshRequest" }, "responses": { "202": { "$ref": "#/components/responses/productFeedRefreshRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/product_feeds/{product_feed_id}/product_feed_refresh_requests/{product_feed_refresh_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productFeedId" }, { "$ref": "#/components/parameters/productFeedRefreshRequestId" } ], "get": { "security": [ { "access_token": [ "product_feeds:write" ] } ], "summary": "Retrieve a product feed refresh request", "description": "Returns the status of a product feed refresh request.", "operationId": "getProductFeedRefreshRequest", "tags": [ "product_feeds" ], "responses": { "200": { "$ref": "#/components/responses/productFeedRefreshRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/products": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "products:read" ] } ], "summary": "Retrieve a list of products", "description": "Returns the products of the product feeds you have access to. Only `active` products are returned unless you filter on `status`. Also available as a CSV file (see the `text/csv` response).", "operationId": "listProducts", "tags": [ "products" ], "parameters": [ { "$ref": "#/components/parameters/productFilter" }, { "$ref": "#/components/parameters/productSort" }, { "$ref": "#/components/parameters/productRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/productsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "description": "Service Unavailable. Product search is temporarily unavailable; retry later." } } }, "post": { "security": [ { "access_token": [ "products:write" ] } ], "summary": "Create a product", "operationId": "createProduct", "description": "Creates a product in a `manual` product feed. Products of other product feeds are managed by their source and can't be created using the API.", "tags": [ "products" ], "requestBody": { "$ref": "#/components/requestBodies/createProduct" }, "responses": { "200": { "$ref": "#/components/responses/productWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/products/{product_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productId" } ], "get": { "security": [ { "access_token": [ "products:read" ] } ], "summary": "Retrieve a product", "operationId": "getProduct", "tags": [ "products" ], "parameters": [ { "$ref": "#/components/parameters/productRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/productWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "products:write" ] } ], "summary": "Update a product", "description": "Products of `manual` product feeds can be fully updated. Products of other product feeds are kept in sync with their source, so only their `status` can be changed (for example, to archive a product).", "operationId": "updateProduct", "tags": [ "products" ], "requestBody": { "$ref": "#/components/requestBodies/updateProduct" }, "responses": { "200": { "$ref": "#/components/responses/productWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "security": [ { "access_token": [ "products:write" ] } ], "summary": "Delete a product", "description": "Only products of `manual` product feeds can be deleted; other products return `404 Not Found`.", "operationId": "deleteProduct", "tags": [ "products" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/scheduled_contents": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "scheduled_contents:read" ] } ], "summary": "Retrieve a list of scheduled contents", "description": "By default, only contents scheduled to be published in the last 14 days or later are returned; use `filter[published_at]` to change the range.", "operationId": "listScheduledContents", "tags": [ "scheduled_contents" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/scheduledContentRelationships" }, { "$ref": "#/components/parameters/scheduledContentFilter" } ], "responses": { "200": { "$ref": "#/components/responses/scheduledContentsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "scheduled_contents:write" ] } ], "summary": "Create a scheduled content", "description": "Schedules content to be published to a connected account. Validation rules (required attributes, caption length and file limits) depend on the account's network.", "operationId": "createScheduledContent", "tags": [ "scheduled_contents" ], "parameters": [ { "$ref": "#/components/parameters/scheduledContentRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createScheduledContent" }, "responses": { "201": { "$ref": "#/components/responses/scheduledContentWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/scheduled_contents/{scheduled_content_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/scheduledContentId" } ], "get": { "security": [ { "access_token": [ "scheduled_contents:read" ] } ], "summary": "Retrieve a scheduled content", "description": "Retrieves one of the team's scheduled contents.", "operationId": "getScheduledContent", "tags": [ "scheduled_contents" ], "parameters": [ { "$ref": "#/components/parameters/scheduledContentRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/scheduledContentWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "scheduled_contents:write" ] } ], "summary": "Update a scheduled content", "description": "Only `pending` and `failed` scheduled contents can be updated; a `success` content returns 404.", "operationId": "updateScheduledContent", "tags": [ "scheduled_contents" ], "parameters": [ { "$ref": "#/components/parameters/scheduledContentRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateScheduledContent" }, "responses": { "200": { "$ref": "#/components/responses/scheduledContentWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "scheduled_contents:write" ] } ], "summary": "Delete a scheduled content", "description": "Deletes the scheduled content.", "operationId": "deleteScheduledContent", "tags": [ "scheduled_contents" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/scheduled_contents/aggregations": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "scheduled_contents:read" ] } ], "summary": "Retrieve aggregations for scheduled contents", "description": "Returns the number of scheduled contents of the team per tag, account and subaccount, across all statuses and dates.", "operationId": "getScheduledContentsAggregations", "tags": [ "scheduled_contents" ], "responses": { "200": { "$ref": "#/components/responses/scheduledContentsAggregationsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/campaigns": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "campaigns:read" ] } ], "summary": "Retrieve a list of campaigns", "description": "Returns the team's campaigns.", "operationId": "listCampaigns", "tags": [ "campaigns" ], "parameters": [ { "$ref": "#/components/parameters/campaignFilter" }, { "$ref": "#/components/parameters/campaignSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/campaignsWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "campaigns:write" ] } ], "summary": "Create a campaign", "description": "Creates a campaign.", "operationId": "createCampaign", "tags": [ "campaigns" ], "requestBody": { "$ref": "#/components/requestBodies/createCampaign" }, "responses": { "201": { "$ref": "#/components/responses/campaignWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/campaigns/{campaign_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/campaignId" } ], "get": { "security": [ { "access_token": [ "campaigns:read" ] } ], "summary": "Retrieve a campaign", "operationId": "getCampaign", "tags": [ "campaigns" ], "responses": { "200": { "$ref": "#/components/responses/campaignWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "campaigns:write" ] } ], "summary": "Update a campaign", "operationId": "updateCampaign", "tags": [ "campaigns" ], "requestBody": { "$ref": "#/components/requestBodies/updateCampaign" }, "responses": { "200": { "$ref": "#/components/responses/campaignWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "campaigns:write" ] } ], "summary": "Delete a campaign", "description": "Deleting a campaign also removes it from the scheduled content it was associated with.", "operationId": "deleteCampaign", "tags": [ "campaigns" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/product_feeds": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "product_feeds:read" ] } ], "summary": "Retrieve a list of product feeds", "operationId": "listProductFeeds", "tags": [ "product_feeds" ], "parameters": [ { "$ref": "#/components/parameters/productFeedFilter" }, { "$ref": "#/components/parameters/productFeedSort" }, { "$ref": "#/components/parameters/productFeedRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/productFeedsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "product_feeds:write" ] } ], "summary": "Create a product feed", "description": "Creates a product feed and starts importing its products in the background (except for `manual` feeds, whose products are created using the API). Which attributes are required depends on `source`.", "operationId": "createProductFeed", "tags": [ "product_feeds" ], "requestBody": { "$ref": "#/components/requestBodies/createProductFeed" }, "responses": { "201": { "$ref": "#/components/responses/productFeedWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/product_feeds/{product_feed_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productFeedId" } ], "get": { "security": [ { "access_token": [ "product_feeds:read" ] } ], "summary": "Retrieve a product feed", "operationId": "getProductFeed", "tags": [ "product_feeds" ], "parameters": [ { "$ref": "#/components/parameters/productFeedRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/productFeedWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "security": [ { "access_token": [ "product_feeds:write" ] } ], "summary": "Delete a product feed", "description": "Deletes the product feed and all of its products.", "operationId": "deleteProductFeed", "tags": [ "product_feeds" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/product_accounts": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "product_accounts:read" ] } ], "summary": "Retrieve a list of product accounts", "operationId": "listProductAccounts", "tags": [ "product_accounts" ], "parameters": [ { "$ref": "#/components/parameters/productAccountFilter" }, { "$ref": "#/components/parameters/productAccountRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/productAccountsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "product_accounts:write" ] } ], "summary": "Create a product account", "description": "Connects a product integration using credentials, without going through the authorization flow. Which attributes are required depends on `type`. The account profile is fetched from the source before the response is returned.", "operationId": "createProductAccount", "tags": [ "product_accounts" ], "requestBody": { "$ref": "#/components/requestBodies/createProductAccount" }, "responses": { "201": { "$ref": "#/components/responses/productAccountWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/product_accounts/{product_account_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productAccountId" } ], "get": { "security": [ { "access_token": [ "product_accounts:read" ] } ], "summary": "Retrieve a product account", "operationId": "getProductAccount", "tags": [ "product_accounts" ], "parameters": [ { "$ref": "#/components/parameters/productAccountRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/productAccountWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "product_accounts:write" ] } ], "summary": "Update a product account", "description": "Updates the credentials of a product account. Changing credentials resets `status` to `ok`.", "operationId": "updateProductAccount", "tags": [ "product_accounts" ], "requestBody": { "$ref": "#/components/requestBodies/updateProductAccount" }, "responses": { "200": { "$ref": "#/components/responses/productAccountWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "product_accounts:write" ] } ], "summary": "Delete a product account", "description": "Only product accounts without product feeds can be deleted; otherwise the request fails with `403 Forbidden`. Delete the product feeds first.", "operationId": "deleteProductAccount", "tags": [ "product_accounts" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/product_accounts/{product_account_id}/edit": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/productAccountId" }, { "$ref": "#/components/parameters/productAccountOrigin" }, { "$ref": "#/components/parameters/productAccountRedirectUri" } ], "get": { "security": [ { "access_token": [ "product_accounts:write" ] } ], "summary": "Reauthenticate a product account", "description": "Returns the URL of the third-party authorization page for the product account. Open this URL (usually in a popup window) so the user can grant access again. Once the user completes the authorization flow, the product account is updated and the result is delivered using the `origin` or `redirect_uri` options.", "operationId": "getProductAccountReauthorizationUrl", "tags": [ "product_accounts" ], "responses": { "200": { "$ref": "#/components/responses/productAccountAuthorizationRedirect" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/product_accounts/new": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "type", "in": "query", "description": "The type of product account to authenticate. Only types that use an authorization flow are supported.", "required": true, "schema": { "type": "string", "enum": [ "facebook", "shopify" ], "example": "shopify" } }, { "name": "site", "in": "query", "description": "The Shopify store URL. Required when `type` is `shopify`; ignored otherwise.", "schema": { "type": "string", "example": "https://acme.myshopify.com" } }, { "$ref": "#/components/parameters/productAccountOrigin" }, { "$ref": "#/components/parameters/productAccountRedirectUri" } ], "get": { "security": [ { "access_token": [ "product_accounts:write" ] } ], "summary": "Authenticate a product account", "description": "Returns the URL of the third-party authorization page for the requested product account type. Open this URL (usually in a popup window) so the user can grant access. Once the user completes the authorization flow, the product account is created and the result is delivered using the `origin` or `redirect_uri` options.", "operationId": "getNewProductAccountAuthorizationUrl", "tags": [ "product_accounts" ], "responses": { "200": { "$ref": "#/components/responses/productAccountAuthorizationRedirect" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/product_tags": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "post": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Create a product tag", "description": "Tags a product in a post of the board, optionally within a bounding box of the post's media.", "operationId": "createProductTag", "tags": [ "product_tags" ], "parameters": [ { "$ref": "#/components/parameters/productTagRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createProductTag" }, "responses": { "201": { "$ref": "#/components/responses/productTagWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/product_tags/{product_tag_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" }, { "$ref": "#/components/parameters/productTagId" } ], "patch": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Update a product tag", "description": "Changes the bounding box or the tagged product.", "operationId": "updateProductTag", "tags": [ "product_tags" ], "parameters": [ { "$ref": "#/components/parameters/productTagRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateProductTag" }, "responses": { "200": { "$ref": "#/components/responses/productTagWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Delete a product tag", "description": "Removes the product tag from the post.", "operationId": "deleteProductTag", "tags": [ "product_tags" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/marketing_integrations": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "marketing_integrations:read" ] } ], "summary": "Retrieve a list of marketing integrations", "operationId": "listMarketingIntegrations", "tags": [ "marketing_integrations" ], "parameters": [ { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/marketingIntegrationsWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "marketing_integrations:write" ] } ], "summary": "Create a marketing integration", "description": "Connects a marketing integration using credentials. Except for `twitter`, the credentials are checked by fetching the account's profile from the source. The credentials are never returned.", "operationId": "createMarketingIntegration", "tags": [ "marketing_integrations" ], "requestBody": { "$ref": "#/components/requestBodies/createMarketingIntegration" }, "responses": { "201": { "$ref": "#/components/responses/marketingIntegrationWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/marketing_integrations/{marketing_integration_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/marketingIntegrationId" } ], "delete": { "security": [ { "access_token": [ "marketing_integrations:write" ] } ], "summary": "Delete a marketing integration", "operationId": "deleteMarketingIntegration", "tags": [ "marketing_integrations" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/marketing_integrations/{marketing_integration_id}/edit": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/marketingIntegrationId" }, { "$ref": "#/components/parameters/marketingIntegrationAuthorizationOrigin" }, { "$ref": "#/components/parameters/marketingIntegrationAuthorizationRedirectUri" } ], "get": { "security": [ { "access_token": [ "marketing_integrations:write" ] } ], "summary": "Reauthenticate a marketing integration", "description": "Returns the URL of the third-party authorization page for the marketing integration. Open this URL (usually in a popup window) so the user can grant access again. Once the user completes the authorization flow, the marketing integration is updated and the result is delivered using the `origin` or `redirect_uri` options.", "operationId": "getMarketingIntegrationReauthorizationUrl", "tags": [ "marketing_integrations" ], "responses": { "200": { "$ref": "#/components/responses/marketingIntegrationAuthorizationUrl" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/marketing_integrations/{marketing_integration_id}/folders": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/marketingIntegrationId" } ], "get": { "security": [ { "access_token": [ "marketing_integrations:write" ] } ], "summary": "Retrieve a list of marketing integration folders", "description": "A folder is a remote group or collection that can be accessed directly using the specified marketing integration's credentials. Use a folder's `id` as the `folder_id` when [creating marketing integration requests](#operation-v2-teams-team-id-marketing-integrations-marketing-integration-id-requests-post). Sources without folders return an empty list.", "operationId": "listMarketingIntegrationFolders", "tags": [ "marketing_integrations" ], "responses": { "200": { "$ref": "#/components/responses/foldersWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/marketing_integrations/new": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "source", "in": "query", "description": "The source of the marketing integration to authenticate.", "required": true, "schema": { "type": "string", "enum": [ "dropbox", "facebook", "google_drive", "hubspot", "mailchimp" ], "example": "google_drive" } }, { "name": "site", "in": "query", "description": "The API endpoint to use, for sources that require one.", "schema": { "type": "string", "format": "uri", "example": "https://acme.example.com" } }, { "$ref": "#/components/parameters/marketingIntegrationAuthorizationOrigin" }, { "$ref": "#/components/parameters/marketingIntegrationAuthorizationRedirectUri" } ], "get": { "security": [ { "access_token": [ "marketing_integrations:write" ] } ], "summary": "Authenticate a marketing integration", "description": "Returns the URL of the third-party authorization page for the requested source. Open this URL (usually in a popup window) so the user can grant access. Once the user completes the authorization flow, the marketing integration is created and the result is delivered using the `origin` or `redirect_uri` options.", "operationId": "getNewMarketingIntegrationAuthorizationUrl", "tags": [ "marketing_integrations" ], "responses": { "200": { "$ref": "#/components/responses/marketingIntegrationAuthorizationUrl" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/marketing_integrations/{marketing_integration_id}/requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/marketingIntegrationId" } ], "post": { "security": [ { "access_token": [ "marketing_integrations_requests:write" ] } ], "summary": "Create marketing integration requests", "description": "Asynchronously publishes assets or collections to a marketing integration. One request is created per published asset (publishing a collection creates one request per asset in the collection).", "operationId": "createMarketingIntegrationRequests", "tags": [ "marketing_integrations" ], "requestBody": { "$ref": "#/components/requestBodies/createMarketingIntegrationRequests" }, "responses": { "202": { "$ref": "#/components/responses/marketingIntegrationRequestsWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/mixes/{mix_id}": { "parameters": [ { "$ref": "#/components/parameters/mixId" } ], "get": { "security": [], "summary": "Retrieve a public mix", "description": "This endpoint is public and doesn't require an access token.", "operationId": "getPublicMix", "tags": [ "mixes" ], "responses": { "200": { "$ref": "#/components/responses/mixWhenUnauthorized" } } } }, "/v2/teams/{team_id}/mixes": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "mixes:read" ] } ], "summary": "Retrieve a list of mixes", "description": "Returns the mixes you have access to.", "operationId": "listMixes", "tags": [ "mixes" ], "parameters": [ { "$ref": "#/components/parameters/mixFilter" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/mixesWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "mixes:write" ] } ], "summary": "Create a mix", "description": "Fails with `402` when the team has reached its plan's mix limit.", "operationId": "createMix", "tags": [ "mixes" ], "requestBody": { "$ref": "#/components/requestBodies/createMix" }, "responses": { "201": { "$ref": "#/components/responses/mixWhenAuthorized" }, "402": { "$ref": "#/components/responses/mixPlanLimitExceeded" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "mixes:write" ] } ], "summary": "Delete multiple mixes", "description": "Deletes several mixes at once.", "operationId": "deleteMixes", "tags": [ "mixes" ], "requestBody": { "$ref": "#/components/requestBodies/deleteMixes" }, "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/mixes/{mix_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/mixId" } ], "get": { "security": [ { "access_token": [ "mixes:read" ] } ], "summary": "Retrieve a mix", "description": "Retrieves one of the team's mixes.", "operationId": "getMix", "tags": [ "mixes" ], "responses": { "200": { "$ref": "#/components/responses/mixWhenAuthorized" } } }, "patch": { "security": [ { "access_token": [ "mixes:write" ] } ], "summary": "Update a mix", "description": "Updates the mix.", "operationId": "updateMix", "tags": [ "mixes" ], "requestBody": { "$ref": "#/components/requestBodies/updateMix" }, "responses": { "200": { "$ref": "#/components/responses/mixWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "mixes:write" ] } ], "summary": "Delete a mix", "description": "Deletes the mix.", "operationId": "deleteMix", "tags": [ "mixes" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/personalizations": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "personalizations:read" ] } ], "summary": "Retrieve a list of personalizations", "description": "Returns the personalizations the user has access to.", "operationId": "listPersonalizations", "tags": [ "personalizations" ], "parameters": [ { "$ref": "#/components/parameters/personalizationFilter" }, { "$ref": "#/components/parameters/personalizationSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/personalizationsWithAggregationsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "personalizations:write" ] } ], "summary": "Create a personalization", "description": "Creates a personalization and grants access to it to the user's role and to the roles that have access to new personalizations.", "operationId": "createPersonalization", "tags": [ "personalizations" ], "requestBody": { "$ref": "#/components/requestBodies/createPersonalization" }, "responses": { "201": { "$ref": "#/components/responses/personalizationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/personalizationLimitReached" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "personalizations:write" ] } ], "summary": "Update multiple personalizations", "description": "Only `name`, `theme`, `tags` and `status` are saved. `PUT` is accepted as an alias of `PATCH`.", "operationId": "updatePersonalizations", "tags": [ "personalizations" ], "requestBody": { "$ref": "#/components/requestBodies/updatePersonalizations" }, "responses": { "200": { "$ref": "#/components/responses/personalizationsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "personalizations:write" ] } ], "summary": "Delete multiple personalizations", "description": "Deletes several personalizations at once.", "operationId": "deletePersonalizations", "tags": [ "personalizations" ], "requestBody": { "$ref": "#/components/requestBodies/deletePersonalizations" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/personalizations/{personalization_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/personalizationId" } ], "get": { "security": [ { "access_token": [ "personalizations:read" ] }, {} ], "summary": "Retrieve a personalization", "description": "With an access token, retrieves one of the personalizations the user has access to. Without an `Authorization` header, retrieves any `active` personalization with a reduced set of attributes and only the published settings.", "operationId": "getPersonalization", "tags": [ "personalizations" ], "responses": { "200": { "$ref": "#/components/responses/personalizationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "personalizations:write" ] } ], "summary": "Update a personalization", "description": "`PUT` is accepted as an alias of `PATCH`.", "operationId": "updatePersonalization", "tags": [ "personalizations" ], "requestBody": { "$ref": "#/components/requestBodies/updatePersonalization" }, "responses": { "200": { "$ref": "#/components/responses/personalizationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "personalizations:write" ] } ], "summary": "Delete a personalization", "description": "Deletes the personalization.", "operationId": "deletePersonalization", "tags": [ "personalizations" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/replies": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "post": { "security": [ { "access_token": [ "replies:write" ] } ], "summary": "Create a reply", "description": "Replies to a post. When the post's author has an email address and the social feed has an email template, the reply is also emailed to the author.", "operationId": "createReply", "tags": [ "posts_replies" ], "parameters": [ { "$ref": "#/components/parameters/replyRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createReply" }, "responses": { "201": { "$ref": "#/components/responses/replyWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/replies/{reply_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/replyId" } ], "patch": { "security": [ { "access_token": [ "replies:write" ] } ], "summary": "Update a reply", "description": "Updates the reply.", "operationId": "updateReply", "tags": [ "posts_replies" ], "requestBody": { "$ref": "#/components/requestBodies/updateReply" }, "responses": { "200": { "$ref": "#/components/responses/replyWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "replies:write" ] } ], "summary": "Delete a reply", "description": "Deletes the reply.", "operationId": "deleteReply", "tags": [ "posts_replies" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/right_requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "right_requests:read" ] } ], "summary": "Retrieve a list of right requests", "description": "Returns the team's right requests for posts in the team's boards, as well as requests for Instagram posts requested by URL.", "operationId": "listRightRequests", "tags": [ "right_requests" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/rightRequestSort" }, { "$ref": "#/components/parameters/rightRequestFilter" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "right_requests:write" ] } ], "summary": "Create a right request", "description": "Asks the author of a post for the rights to reuse it. The message is generated from the template and sent from the given account; for X (Twitter), it is sent a few seconds later, so the right request starts as `pending`. For the other sources, it starts as `requested`.", "operationId": "createRightRequest", "tags": [ "right_requests" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createRightRequest" }, "responses": { "201": { "$ref": "#/components/responses/rightRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/right_requests/{right_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/rightRequestId" } ], "get": { "security": [ { "access_token": [ "right_requests:read" ] } ], "summary": "Retrieve a right request", "description": "Retrieves a right request.", "operationId": "getRightRequest", "tags": [ "right_requests" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/right_requests/metrics/{measure_name}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/rightRequestMeasureName" } ], "get": { "security": [ { "access_token": [ "right_requests:read" ] } ], "summary": "Retrieve right request metrics", "description": "Counts the right requests created or approved over time, optionally grouped by one or more dimensions. Only right requests sent from accounts connected by the current user are counted.", "operationId": "getRightRequestsMetrics", "tags": [ "right_requests" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestsMetricsFilter" }, { "$ref": "#/components/parameters/rightRequestsMetricsGroup" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestsMetricsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/right_requests/terms": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "right_request_terms:read" ] } ], "summary": "Retrieve a list of right request terms", "description": "Returns the team's published right request terms. Archived (deleted) terms are not included.", "operationId": "listRightRequestTerms", "tags": [ "right_request_terms" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTermRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/rightRequestTermSort" }, { "$ref": "#/components/parameters/rightRequestTermFilter" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestTermsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "right_request_terms:write" ] } ], "summary": "Create a right request term", "description": "Creates a right request term.", "operationId": "createRightRequestTerm", "tags": [ "right_request_terms" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTermRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createRightRequestTerm" }, "responses": { "201": { "$ref": "#/components/responses/rightRequestTermWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/right_requests/terms": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "right_request_terms:read" ] } ], "summary": "Retrieve a list of right request terms for a board", "description": "Returns the team's published right request terms. The board must belong to the team (otherwise a 404 is returned), but the list isn't currently narrowed down to terms limited to that board.", "operationId": "listTintRightRequestTerms", "tags": [ "right_request_terms" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTermRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/rightRequestTermSort" }, { "$ref": "#/components/parameters/rightRequestTermFilter" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestTermsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/right_requests/terms/{right_request_term_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/rightRequestTermId" } ], "get": { "security": [ { "access_token": [] } ], "summary": "Retrieve a right request term", "description": "Unlike the other right request term endpoints, this one also returns archived terms, so they can be displayed to authors who want to review the terms they were asked to accept. It requires an access token for a member of the team (a 403 is returned otherwise, including when no access token is given), but no specific scope. The `tint` relationship is only returned when the access token has the `tints:read` scope.", "operationId": "getRightRequestTerm", "tags": [ "right_request_terms" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTermRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestTermWhenAuthorized" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "delete": { "security": [ { "access_token": [ "right_request_terms:write" ] } ], "summary": "Delete a right request term", "description": "Archives the terms rather than permanently deleting them, so existing right requests keep pointing to them. Archived terms can't be deleted again (404).", "operationId": "deleteRightRequestTerm", "tags": [ "right_request_terms" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/right_requests/templates": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "right_request_templates:read" ] } ], "summary": "Retrieve a list of right request templates", "description": "Returns the team's right request templates. When the team doesn't have any yet, a default set of templates is created for it first.", "operationId": "listRightRequestTemplates", "tags": [ "right_request_templates" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTemplateRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/rightRequestTemplateSort" }, { "$ref": "#/components/parameters/rightRequestTemplateFilter" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestTemplatesWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "right_request_templates:write" ] } ], "summary": "Create a right request template", "description": "Creates a right request template.", "operationId": "createRightRequestTemplate", "tags": [ "right_request_templates" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTemplateRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createRightRequestTemplate" }, "responses": { "201": { "$ref": "#/components/responses/rightRequestTemplateWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/right_requests/templates": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "right_request_templates:read" ] } ], "summary": "Retrieve a list of right request templates for a board", "description": "Returns the team's right request templates. The list isn't currently narrowed down to templates limited to the board. When the team doesn't have any templates yet, a default set is created for it first.", "operationId": "listTintRightRequestTemplates", "tags": [ "right_request_templates" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTemplateRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/rightRequestTemplateSort" }, { "$ref": "#/components/parameters/rightRequestTemplateFilter" } ], "responses": { "200": { "$ref": "#/components/responses/rightRequestTemplatesWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/right_requests/templates/{right_request_template_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/rightRequestTemplateId" } ], "patch": { "security": [ { "access_token": [ "right_request_templates:write" ] } ], "summary": "Update a right request template", "description": "Updates a right request template.", "operationId": "updateRightRequestTemplate", "tags": [ "right_request_templates" ], "parameters": [ { "$ref": "#/components/parameters/rightRequestTemplateRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateRightRequestTemplate" }, "responses": { "200": { "$ref": "#/components/responses/rightRequestTemplateWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "right_request_templates:write" ] } ], "summary": "Delete a right request template", "description": "Permanently deletes the template.", "operationId": "deleteRightRequestTemplate", "tags": [ "right_request_templates" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams": { "get": { "security": [ { "access_token": [ "teams:read" ] } ], "summary": "Retrieve a list of teams", "description": "Returns the teams the authenticated user is a member of.", "operationId": "listTeams", "tags": [ "teams" ], "parameters": [ { "$ref": "#/components/parameters/teamRelationships" }, { "$ref": "#/components/parameters/teamFilter" }, { "$ref": "#/components/parameters/teamSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/teamsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "teams:write" ] } ], "summary": "Create a team", "description": "Creates a team on a self-service plan, subscribes it to the plan using the payment token, and makes the authenticated user its administrator. If the payment token can't be processed, the request fails with a `422 Unprocessable Entity` error on `billing_platform_token`.", "operationId": "createTeam", "tags": [ "teams" ], "requestBody": { "$ref": "#/components/requestBodies/createTeam" }, "responses": { "201": { "$ref": "#/components/responses/teamWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "teams:read" ] } ], "summary": "Retrieve a team", "description": "Returns a team the authenticated user is a member of.", "operationId": "getTeam", "tags": [ "teams" ], "parameters": [ { "$ref": "#/components/parameters/teamRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/teamWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "teams:write" ] } ], "summary": "Update a team", "description": "Updates the team.", "operationId": "updateTeam", "tags": [ "teams" ], "parameters": [ { "$ref": "#/components/parameters/teamRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateTeam" }, "responses": { "200": { "$ref": "#/components/responses/teamWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "teams:write" ] } ], "summary": "Delete a team", "description": "Cancels the team's subscription at the end of the current billing period. Only available to teams billed through Chargify; otherwise, the request fails with a `403 Forbidden` error.", "operationId": "deleteTeam", "tags": [ "teams" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/domains": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "domains:read" ] } ], "summary": "Retrieve a list of domains", "description": "Retrieves the team's domains that the user has access to.", "operationId": "listDomains", "tags": [ "domains" ], "parameters": [ { "$ref": "#/components/parameters/domainInclude" } ], "responses": { "200": { "$ref": "#/components/responses/domainsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "domains:write" ] } ], "summary": "Create a domain", "description": "Adds a custom domain to the team and starts issuing its SSL certificate; the domain's `status` is `pending` until the certificate has been issued. The new domain is automatically shared with the user's role and with every role that has access to new domains.", "operationId": "createDomain", "tags": [ "domains" ], "requestBody": { "$ref": "#/components/requestBodies/createDomain" }, "responses": { "201": { "$ref": "#/components/responses/domainWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/domainForbidden" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/domains/{domain_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/domainId" } ], "get": { "security": [ { "access_token": [ "domains:read" ] } ], "summary": "Retrieve a domain", "description": "Retrieves one of the team's domains.", "operationId": "getDomain", "tags": [ "domains" ], "parameters": [ { "$ref": "#/components/parameters/domainInclude" } ], "responses": { "200": { "$ref": "#/components/responses/domainWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "domains:write" ] } ], "summary": "Update a domain", "description": "Sets or clears the experience shown at the root of the domain. The domain's name can't be changed.", "operationId": "updateDomain", "tags": [ "domains" ], "requestBody": { "$ref": "#/components/requestBodies/updateDomain" }, "responses": { "200": { "$ref": "#/components/responses/domainWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "domains:write" ] } ], "summary": "Delete a domain", "description": "Deletes the domain. Experiences published on it are detached from the domain.", "operationId": "deleteDomain", "tags": [ "domains" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/email_templates": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "email_templates:read" ] } ], "summary": "Retrieve a list of email templates", "description": "Retrieves the team's email templates. Any member of the team can list them.", "operationId": "listEmailTemplates", "tags": [ "email_templates" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/emailTemplateFilter" }, { "$ref": "#/components/parameters/emailTemplateSort" }, { "$ref": "#/components/parameters/emailTemplateInclude" } ], "responses": { "200": { "$ref": "#/components/responses/emailTemplatesWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "email_templates:write" ] } ], "summary": "Create an email template", "description": "Creates an email template for the team. Any member of the team can create one.", "operationId": "createEmailTemplate", "tags": [ "email_templates" ], "requestBody": { "$ref": "#/components/requestBodies/createEmailTemplate" }, "responses": { "201": { "$ref": "#/components/responses/emailTemplateWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "email_templates:write" ] } ], "summary": "Delete multiple email templates", "description": "Deletes several of the team's email templates at once. IDs that don't match one of the team's templates are ignored.", "operationId": "deleteEmailTemplates", "tags": [ "email_templates" ], "requestBody": { "$ref": "#/components/requestBodies/deleteEmailTemplates" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/email_templates/{email_template_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/emailTemplateId" } ], "get": { "security": [ { "access_token": [ "email_templates:read" ] } ], "summary": "Retrieve an email template", "description": "Retrieves one of the team's email templates.", "operationId": "getEmailTemplate", "tags": [ "email_templates" ], "parameters": [ { "$ref": "#/components/parameters/emailTemplateInclude" } ], "responses": { "200": { "$ref": "#/components/responses/emailTemplateWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "email_templates:write" ] } ], "summary": "Update an email template", "description": "Updates the template's name or content. The template's `type` can't be changed.", "operationId": "updateEmailTemplate", "tags": [ "email_templates" ], "requestBody": { "$ref": "#/components/requestBodies/updateEmailTemplate" }, "responses": { "200": { "$ref": "#/components/responses/emailTemplateWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "email_templates:write" ] } ], "summary": "Delete an email template", "description": "Deletes the email template.", "operationId": "deleteEmailTemplate", "tags": [ "email_templates" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/fonts": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "fonts:read" ] } ], "summary": "Retrieve a list of fonts", "description": "Retrieves the team's fonts that the user has access to.", "operationId": "listFonts", "tags": [ "fonts" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/fontSort" } ], "responses": { "200": { "$ref": "#/components/responses/fontsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "fonts:write" ] } ], "summary": "Create a font", "description": "Creates a font from a file uploaded with the font upload endpoint. Creating a font takes three steps: create an upload, send the file to the upload's `url` with its `headers`, then call this endpoint with the upload's `id` as `upload_id`. The format and metrics are detected from the file. The new font is automatically shared with the user's role and with every role that has access to new fonts.", "operationId": "createFont", "tags": [ "fonts" ], "requestBody": { "$ref": "#/components/requestBodies/createFont" }, "responses": { "201": { "$ref": "#/components/responses/fontWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/fonts/upload": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "post": { "security": [ { "access_token": [] } ], "summary": "Create a font upload", "description": "Starts a direct upload for a font file. Send the file's bytes to the returned `url` with an HTTP `PUT` request and the returned `headers`, then create the font with the upload's `id` as `upload_id`. Accepted formats are WOFF, WOFF2, TrueType, OpenType, Embedded OpenType, and SVG, up to 5 MB. Any valid access token for a member of the team can create an upload; no specific scope is checked. A missing or invalid token results in a `403`.", "operationId": "createFontUpload", "tags": [ "fonts" ], "requestBody": { "$ref": "#/components/requestBodies/createFontUpload" }, "responses": { "201": { "$ref": "#/components/responses/fontUpload" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/fonts/{font_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/fontId" } ], "delete": { "security": [ { "access_token": [ "fonts:write" ] } ], "summary": "Delete a font", "description": "Deletes one of the team's fonts.", "operationId": "deleteFont", "tags": [ "fonts" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/fonts/{font_ids}.css": { "parameters": [ { "$ref": "#/components/parameters/fontStylesheetTeamId" }, { "$ref": "#/components/parameters/fontIds" } ], "get": { "security": [ {}, { "access_token": [ "fonts:read" ] } ], "summary": "Retrieve fonts as a CSS stylesheet", "description": "Returns a stylesheet containing one `@font-face` rule per requested font, for use in a `` tag. This is the URL returned in each font's `links.css`.\n\nWithout an `Authorization` header the endpoint is public: `team_id` can be the team's ID or one of its domain names, and any of the team's fonts can be requested. With an access token, `team_id` must be a team ID, and the token needs the `fonts:read` scope.", "operationId": "getFontsStylesheet", "tags": [ "fonts" ], "responses": { "200": { "$ref": "#/components/responses/fontsStylesheet" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "description": "Not Found. None of the requested fonts exist for the team, or the domain name doesn't match a domain.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "404", "title": "Not found", "status": "404" } ] } } } } } } }, "/v2/teams/{team_id}/tints": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "tints:read" ] } ], "summary": "Retrieve a list of boards", "description": "Returns the boards you have access to.", "operationId": "listTints", "tags": [ "tints" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/tintRelationships" }, { "$ref": "#/components/parameters/tintFilter" }, { "$ref": "#/components/parameters/tintSort" } ], "responses": { "200": { "$ref": "#/components/responses/tintsWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "tints:write" ] } ], "summary": "Create a board", "description": "Fails with `402` when the team has reached its plan's board limit.", "operationId": "createTint", "tags": [ "tints" ], "parameters": [ { "$ref": "#/components/parameters/tintRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createTint" }, "responses": { "201": { "$ref": "#/components/responses/tintWhenAuthorized" }, "402": { "$ref": "#/components/responses/tintPlanLimitExceeded" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "tints:write" ] } ], "summary": "Update multiple boards", "description": "The request is validated as a whole: if any board is invalid, none are updated.", "operationId": "updateTints", "tags": [ "tints" ], "requestBody": { "$ref": "#/components/requestBodies/updateTints" }, "responses": { "200": { "$ref": "#/components/responses/tintsUpdated" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "tints:write" ] } ], "summary": "Delete multiple boards", "description": "Deletes several boards at once.", "operationId": "deleteTints", "tags": [ "tints" ], "requestBody": { "$ref": "#/components/requestBodies/deleteTints" }, "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/tints/metrics/engagements/{embed_engagement_type}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintEngagementType" } ], "get": { "security": [ { "access_token": [ "tints:read" ] } ], "summary": "Retrieve aggregated board engagement metrics", "description": "Counts the engagement events of the team's boards, optionally grouped by one or more dimensions.", "operationId": "getTintsEngagementMetrics", "tags": [ "tints" ], "parameters": [ { "$ref": "#/components/parameters/tintEngagementMetricsFilter" }, { "$ref": "#/components/parameters/tintEngagementMetricsGroup" }, { "$ref": "#/components/parameters/tintEngagementMetricsAggregation" } ], "responses": { "200": { "$ref": "#/components/responses/tintEngagementMetricsWhenAuthorized" } } } }, "/v2/teams/{team_id}/tints/{tint_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "tints:read" ] } ], "summary": "Retrieve a board", "operationId": "getTint", "tags": [ "tints" ], "parameters": [ { "$ref": "#/components/parameters/tintRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/tintWhenAuthorized" } } }, "patch": { "security": [ { "access_token": [ "tints:write" ] } ], "summary": "Update a board", "description": "Updates the board.", "operationId": "updateTint", "tags": [ "tints" ], "parameters": [ { "$ref": "#/components/parameters/tintRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateTint" }, "responses": { "200": { "$ref": "#/components/responses/tintWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "tints:write" ] } ], "summary": "Delete a board", "description": "Deletes the board.", "operationId": "deleteTint", "tags": [ "tints" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/tints/{tint_slug}": { "parameters": [ { "$ref": "#/components/parameters/tintSlug" } ], "get": { "security": [ {}, { "access_token": [ "tints:read" ] } ], "summary": "Retrieve a public board", "description": "Returns a public board by its slug. No authentication is required; if an `Authorization` header is sent, the access token must have the `tints:read` scope.", "operationId": "getTintBySlug", "tags": [ "tints" ], "responses": { "200": { "$ref": "#/components/responses/tintWhenUnauthorized" } } } }, "/v2/me": { "get": { "security": [ { "access_token": [ "identity" ] } ], "summary": "Retrieve my user", "description": "Returns the user who owns the access token.", "operationId": "getMe", "tags": [ "team_users" ], "parameters": [ { "$ref": "#/components/parameters/meInclude" } ], "responses": { "200": { "$ref": "#/components/responses/meWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "patch": { "security": [ { "access_token": [ "identity:write" ] }, { "access_token": [ "identity:write" ], "id_token": [] } ], "summary": "Update my user", "description": "Updates the user who owns the access token. Changing the `email` or `password` attributes, or setting `temporary_support_access_ends_at`, additionally requires a valid ID token for the current access token, passed in the `id_token` query parameter; otherwise, the request fails with a `403 Forbidden` error (code `4030002`). A security email is sent to the user when their email or password is changed or when support access is granted.", "operationId": "updateMe", "tags": [ "team_users" ], "requestBody": { "$ref": "#/components/requestBodies/updateMe" }, "responses": { "200": { "$ref": "#/components/responses/meWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/users": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "users:read" ] } ], "summary": "Retrieve a list of users", "description": "Returns the members of the team.", "operationId": "listTeamUsers", "tags": [ "team_users" ], "parameters": [ { "$ref": "#/components/parameters/teamUserRelationships" }, { "$ref": "#/components/parameters/teamUserFilter" }, { "$ref": "#/components/parameters/teamUserSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/teamUsersWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "users:write" ] } ], "summary": "Invite users to a team", "description": "Invites a single user (`application/vnd.api+json` with a single resource object) or multiple users (`application/vnd.api+json; ext=bulk` with an array of resource objects) to the team, and emails them an invitation. An account is created for email addresses that don't have one yet. The response contains a single user or an array of users accordingly.", "operationId": "createTeamUsers", "tags": [ "team_users" ], "requestBody": { "$ref": "#/components/requestBodies/createTeamUsers" }, "responses": { "201": { "$ref": "#/components/responses/teamUsersCreated" }, "401": { "$ref": "#/components/responses/401" }, "402": { "$ref": "#/components/responses/teamUsersLimitExceeded" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "users:write" ] } ], "summary": "Update multiple users", "description": "Updates the role and `skip_idp` attribute of several team members at once. Users that aren't members of the team are skipped, and you can't update yourself. `PUT` is also accepted.", "operationId": "updateTeamUsers", "tags": [ "team_users" ], "requestBody": { "$ref": "#/components/requestBodies/updateTeamUsers" }, "responses": { "200": { "$ref": "#/components/responses/teamUsersUpdated" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "users:write" ] } ], "summary": "Remove multiple users from a team", "description": "The authenticated user can't remove themselves and is skipped, as are users that aren't members of the team.", "operationId": "deleteTeamUsers", "tags": [ "team_users" ], "requestBody": { "$ref": "#/components/requestBodies/deleteTeamUsers" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/users/{user_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "get": { "security": [ { "access_token": [ "users:read" ] } ], "summary": "Retrieve a user", "description": "Returns a member of the team.", "operationId": "getTeamUser", "tags": [ "team_users" ], "parameters": [ { "$ref": "#/components/parameters/teamUserRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/teamUserWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "users:write" ] } ], "summary": "Update a user", "description": "Updates the role and `skip_idp` attribute of a team member. You can't update yourself.", "operationId": "updateTeamUser", "tags": [ "team_users" ], "parameters": [ { "$ref": "#/components/parameters/teamUserRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateTeamUser" }, "responses": { "200": { "$ref": "#/components/responses/teamUserWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "users:write" ] } ], "summary": "Remove a user from a team", "description": "The authenticated user can't remove themselves.", "operationId": "deleteTeamUser", "tags": [ "team_users" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/users/export/requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "post": { "security": [ { "access_token": [ "users:read" ] } ], "summary": "Create a user export request", "description": "Asynchronously exports the team's users to a CSV file. Once complete, a websocket message of type `teams_user_export_request` containing the ID, status and URL is delivered to the user's private channel (`private-user-` followed by the user's ID). You may also poll the status of the request using the endpoint below.", "operationId": "createTeamsUserExportRequest", "tags": [ "team_users" ], "requestBody": { "$ref": "#/components/requestBodies/createTeamsUserExportRequest" }, "responses": { "202": { "$ref": "#/components/responses/teamsUserExportRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/users/export/requests/{teams_user_export_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/teamsUserExportRequestId" } ], "get": { "security": [ { "access_token": [ "users:read" ] } ], "summary": "Check the status of a user export request", "description": "Retrieves the status of one of the team's user export requests.", "operationId": "getTeamsUserExportRequest", "tags": [ "team_users" ], "responses": { "200": { "$ref": "#/components/responses/teamsUserExportRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/authentication_factors": { "get": { "security": [ { "access_token": [ "authentication_factors:read" ] } ], "summary": "Retrieve a list of authentication factors", "description": "Returns all the authentication factors (pending and active) of the current user.", "operationId": "listAuthenticationFactors", "tags": [ "authentication_factors" ], "responses": { "200": { "$ref": "#/components/responses/authenticationFactorsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "authentication_factors:write" ], "id_token": [] } ], "summary": "Create an authentication factor", "description": "Adds an authentication factor to the current user. What happens next depends on the kind of authentication factor:\n\n- `recovery_code`, and `out_of_band` with the `email` channel, are `active` right away.\n- `out_of_band` with the `sms`, `voice` or `fax` channel is `pending`, and a code is sent to `external_id` immediately. Verify it with [Verify an authentication factor](#operation-v2-authentication-factors-authentication-factor-id-patch). A new code can be requested after 30 seconds with [Create an authentication factor challenge](#operation-v2-authentication-factors-authentication-factor-id-challenges-post).\n- `one_time_password` is `pending` and has a `provisioning_url` to add to an authenticator app. Verify it with a code generated by the app.\n\nA user can only have one authentication factor per `type` and `channel` combination.", "operationId": "createAuthenticationFactor", "tags": [ "authentication_factors" ], "requestBody": { "$ref": "#/components/requestBodies/createAuthenticationFactor" }, "responses": { "201": { "$ref": "#/components/responses/authenticationFactorWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/authentication_factors/{authentication_factor_id}": { "parameters": [ { "$ref": "#/components/parameters/authenticationFactorId" } ], "patch": { "security": [ { "access_token": [ "authentication_factors:write" ], "id_token": [] } ], "summary": "Verify an authentication factor", "description": "Verifies a `pending` authentication factor with a code it received or generated, and marks it `active`. If the user doesn't have a default authentication factor yet, this one becomes the default. An email is sent to the user to let them know an authentication factor was added. Only `pending` authentication factors can be verified; others return `404`.", "operationId": "verifyAuthenticationFactor", "tags": [ "authentication_factors" ], "requestBody": { "$ref": "#/components/requestBodies/verifyAuthenticationFactor" }, "responses": { "200": { "$ref": "#/components/responses/authenticationFactorWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "description": "Unprocessable Entity. The code is missing, invalid or expired.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "title": "Invalid challenge", "detail": "Challenge is invalid", "source": { "pointer": "/data/attributes/challenge" } }, { "title": "Invalid otp_attempt", "detail": "Otp attempt is invalid", "source": { "pointer": "/data/attributes/otp_attempt" } } ] } } } } } }, "delete": { "security": [ { "access_token": [ "authentication_factors:write" ], "id_token": [] } ], "summary": "Delete an authentication factor", "description": "Removes an authentication factor from the current user and emails them about it. If it was the user's default authentication factor, another active authentication factor (other than a recovery code) becomes the default.", "operationId": "deleteAuthenticationFactor", "tags": [ "authentication_factors" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/authentication_factors/{authentication_factor_id}/challenges": { "parameters": [ { "$ref": "#/components/parameters/authenticationFactorId" } ], "post": { "security": [ { "access_token": [ "authentication_factors:write" ], "id_token": [] } ], "summary": "Create an authentication factor challenge", "description": "Sends a new code for a `pending` `out_of_band` authentication factor, for example when the user didn't receive the first one. A code is already sent when the authentication factor is created, and a new one can only be requested every 30 seconds; earlier requests return `429` with a `Retry-After` header. Authentication factors that are `active` or aren't `out_of_band` return `404`.", "operationId": "createAuthenticationFactorChallenge", "tags": [ "authentication_factors" ], "requestBody": { "$ref": "#/components/requestBodies/createAuthenticationFactorChallenge" }, "responses": { "201": { "$ref": "#/components/responses/authenticationFactorChallengeWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" } } } }, "/v2/teams/{team_id}/assets": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "assets:read" ] } ], "summary": "Retrieve a list of assets", "description": "Returns the team's assets that are in a collection the user has access to or in no collection. Returns 503 while search is temporarily unavailable.", "operationId": "listAssets", "tags": [ "assets" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/assetRelationships" }, { "$ref": "#/components/parameters/assetSort" }, { "$ref": "#/components/parameters/assetFilter" } ], "responses": { "200": { "$ref": "#/components/responses/assetsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "description": "Service Unavailable. Search is temporarily unavailable; retry later." } } }, "post": { "security": [ { "access_token": [ "assets:write" ] } ], "summary": "Create assets", "description": "Creates one or more assets asynchronously. Once complete, a websocket message of type `asset_bulk_create_request` is delivered to the team's private channel (`private-team-` followed by the team's ID) with the request's `id` and final `status`. Creation fails when the plan's limit of uploaded assets is reached.", "operationId": "createAssets", "tags": [ "assets" ], "requestBody": { "$ref": "#/components/requestBodies/createAssets" }, "responses": { "202": { "$ref": "#/components/responses/assetBulkCreateRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "assets:write" ] } ], "summary": "Update multiple assets", "description": "Updates several assets at once. If any asset is invalid, none are updated.", "operationId": "updateAssets", "tags": [ "assets" ], "parameters": [ { "$ref": "#/components/parameters/assetRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateAssets" }, "responses": { "200": { "$ref": "#/components/responses/assetsUpdatedWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "assets:write" ] } ], "summary": "Delete multiple assets", "description": "Deletes several assets at once.", "operationId": "deleteAssets", "tags": [ "assets" ], "requestBody": { "$ref": "#/components/requestBodies/deleteAssets" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/assets/{asset_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/assetId" } ], "get": { "security": [ { "access_token": [ "assets:read" ] } ], "summary": "Retrieve an asset", "description": "Returns 404 when the asset is only in collections the user doesn't have access to.", "operationId": "getAsset", "tags": [ "assets" ], "parameters": [ { "$ref": "#/components/parameters/assetRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/assetWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "assets:write" ] } ], "summary": "Update an asset", "description": "Updates the asset.", "operationId": "updateAsset", "tags": [ "assets" ], "parameters": [ { "$ref": "#/components/parameters/assetRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateAsset" }, "responses": { "200": { "$ref": "#/components/responses/assetWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "assets:write" ] } ], "summary": "Delete an asset", "description": "Deletes the asset.", "operationId": "deleteAsset", "tags": [ "assets" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/assets/aggregations": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "assets:read" ] } ], "summary": "Retrieve asset aggregations", "description": "Returns the number of the team's assets per source, detected object, emotion, media type and tag. Returns 503 while search is temporarily unavailable.", "operationId": "getAssetsAggregations", "tags": [ "assets" ], "parameters": [ { "$ref": "#/components/parameters/assetStatusFilter" } ], "responses": { "200": { "$ref": "#/components/responses/assetsAggregationsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "description": "Service Unavailable. Search is temporarily unavailable; retry later." } } } }, "/v2/teams/{team_id}/social_feeds": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "social_feeds:read" ] } ], "summary": "Retrieve a list of social feeds", "description": "Returns the social feeds of the boards you have access to.", "operationId": "listSocialFeeds", "tags": [ "social_feeds" ], "parameters": [ { "$ref": "#/components/parameters/socialFeedFilter" }, { "$ref": "#/components/parameters/socialFeedRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/socialFeedsWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "social_feeds:write" ] } ], "summary": "Create a social feed", "description": "Fails with `402` when the team has reached its plan's limit of active social feeds. For `influencer` social feeds, an authorization request is emailed to the `contact`.", "operationId": "createSocialFeed", "tags": [ "social_feeds" ], "parameters": [ { "$ref": "#/components/parameters/socialFeedRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createSocialFeed" }, "responses": { "200": { "$ref": "#/components/responses/socialFeedWhenAuthorized" }, "402": { "$ref": "#/components/responses/socialFeedPlanLimitExceeded" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "social_feeds:write" ] } ], "summary": "Update multiple social feeds", "description": "The request is validated as a whole: if any social feed is invalid, none are updated.", "operationId": "updateSocialFeeds", "tags": [ "social_feeds" ], "requestBody": { "$ref": "#/components/requestBodies/updateSocialFeeds" }, "responses": { "200": { "$ref": "#/components/responses/socialFeedsUpdated" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/social_feeds/{social_feed_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/socialFeedId" } ], "get": { "security": [ { "access_token": [ "social_feeds:read" ] } ], "summary": "Retrieve a social feed", "operationId": "getSocialFeed", "tags": [ "social_feeds" ], "parameters": [ { "$ref": "#/components/parameters/socialFeedRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/socialFeedWhenAuthorized" } } }, "patch": { "security": [ { "access_token": [ "social_feeds:write" ] } ], "summary": "Update a social feed", "description": "Updates the social feed.", "operationId": "updateSocialFeed", "tags": [ "social_feeds" ], "parameters": [ { "$ref": "#/components/parameters/socialFeedRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateSocialFeed" }, "responses": { "200": { "$ref": "#/components/responses/socialFeedWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "social_feeds:write" ] } ], "summary": "Delete a social feed", "description": "Deletes the social feed and the posts it ingested.", "operationId": "deleteSocialFeed", "tags": [ "social_feeds" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/social_feeds/{social_feed_id}/metrics": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/socialFeedId" } ], "get": { "security": [ { "access_token": [] } ], "deprecated": true, "summary": "Retrieve aggregated ingestion metrics for a social feed", "description": "This endpoint is deprecated. Use `GET /v2/teams/{team_id}/posts/metrics/ingested?filter[social_feed_id]={social_feed_id}` instead.", "operationId": "getSocialFeedMetrics", "tags": [ "social_feeds" ], "parameters": [ { "$ref": "#/components/parameters/socialFeedMetricsGroup" }, { "$ref": "#/components/parameters/socialFeedMetricsFilter" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/socialFeedMetricsWhenAuthorized" } } } }, "/v2/teams/{team_id}/experiences": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "operationId": "listExperiences", "security": [ { "access_token": [ "experiences:read" ] } ], "summary": "Retrieve a list of experiences", "description": "Returns the experiences the user has access to.", "tags": [ "experiences" ], "parameters": [ { "$ref": "#/components/parameters/experienceRelationships" }, { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/experienceFilter" }, { "$ref": "#/components/parameters/experienceSort" } ], "responses": { "200": { "$ref": "#/components/responses/experiencesWithTotalWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "operationId": "createExperience", "security": [ { "access_token": [ "experiences:write" ] } ], "summary": "Create an experience", "description": "Creates an experience and grants access to it to the user's role and to the roles that have access to new experiences.", "tags": [ "experiences" ], "parameters": [ { "$ref": "#/components/parameters/experienceRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createExperience" }, "responses": { "201": { "$ref": "#/components/responses/experienceWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "operationId": "updateExperiences", "security": [ { "access_token": [ "experiences:write" ] } ], "summary": "Update multiple experiences", "description": "Updates several experiences in a single request. If any experience is invalid, none are updated and the errors are returned. The experience `type` can't be changed. `PUT` is accepted as an alias of `PATCH`.", "tags": [ "experiences" ], "requestBody": { "$ref": "#/components/requestBodies/updateExperiences" }, "responses": { "200": { "$ref": "#/components/responses/experiencesWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "operationId": "deleteExperiences", "security": [ { "access_token": [ "experiences:write" ] } ], "summary": "Delete multiple experiences", "description": "Deletes several experiences at once.", "tags": [ "experiences" ], "requestBody": { "$ref": "#/components/requestBodies/deleteExperiences" }, "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "experience_id", "in": "path", "required": true, "description": "The ID or slug of the experience. Slugs are only accepted when retrieving a published experience without authentication.", "schema": { "oneOf": [ { "type": "integer", "title": "ID", "example": 42 }, { "type": "string", "title": "Slug", "pattern": "^(?!\\d)[a-z0-9_-]+$", "example": "summer-sweepstakes" } ] } } ], "get": { "operationId": "getExperience", "security": [ { "access_token": [ "experiences:read" ] }, {} ], "summary": "Retrieve an experience", "description": "With an access token, retrieves one of the experiences the user has access to by ID. Without an `Authorization` header, retrieves a published experience by ID or by slug. When using a slug, `team_id` may also be the name of the experience's custom domain, the request's `Referer` must be allowed for the experience, and the experience's impression count is incremented.", "tags": [ "experiences" ], "parameters": [ { "name": "team_id", "in": "path", "required": true, "description": "The ID of the team. When retrieving a published experience by slug, this can also be the name of the experience's custom domain.", "schema": { "oneOf": [ { "type": "integer", "title": "ID", "example": 1 }, { "type": "string", "title": "Domain name", "example": "contests.example.com" } ] } }, { "$ref": "#/components/parameters/experienceRelationships" } ], "responses": { "200": { "description": "The experience. Unauthenticated requests receive a reduced set of attributes.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "title": "Authenticated", "allOf": [ { "$ref": "#/components/schemas/ExperienceBase" } ] }, { "title": "Unauthenticated", "allOf": [ { "$ref": "#/components/schemas/PublicExperience" } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "operationId": "updateExperience", "security": [ { "access_token": [ "experiences:write" ] } ], "summary": "Update an experience", "description": "`PUT` is accepted as an alias of `PATCH`.", "tags": [ "experiences" ], "parameters": [ { "$ref": "#/components/parameters/experienceId" }, { "$ref": "#/components/parameters/experienceRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateExperience" }, "responses": { "200": { "$ref": "#/components/responses/experienceWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "operationId": "deleteExperience", "security": [ { "access_token": [ "experiences:write" ] } ], "summary": "Delete an experience", "description": "Deletes the experience.", "tags": [ "experiences" ], "parameters": [ { "$ref": "#/components/parameters/experienceId" } ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}/form_submissions": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/experienceId" } ], "get": { "security": [ { "access_token": [ "form_submissions:read" ] } ], "summary": "Retrieve a list of form submissions", "description": "Requires access to the experience.", "operationId": "listFormSubmissions", "tags": [ "form_submissions" ], "parameters": [ { "$ref": "#/components/parameters/formSubmissionFilter" }, { "$ref": "#/components/parameters/formSubmissionSort" }, { "$ref": "#/components/parameters/formSubmissionRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/formSubmissionsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "post": { "security": [], "summary": "Create a form submission", "description": "Submits the experience's form. This endpoint is public; the experience must be active, the request's `Referer` must be allowed for the experience, and the captcha token must be valid when the experience uses a captcha. For teams connected to a loyalty program, an optional `Authorization: Bearer` header may carry the loyalty member's JWT; the submission is then linked to that member, and an invalid token is rejected with a `403`.", "operationId": "createFormSubmission", "tags": [ "form_submissions" ], "parameters": [ { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/metadata" }, { "$ref": "#/components/parameters/anonymousUid" }, { "$ref": "#/components/parameters/deviceFingerprint" } ], "requestBody": { "$ref": "#/components/requestBodies/createFormSubmission" }, "responses": { "201": { "$ref": "#/components/responses/formSubmissionWhenCreated" }, "402": { "$ref": "#/components/responses/formSubmissionLimitReached" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "form_submissions:write" ] } ], "summary": "Delete all form submissions", "description": "Deletes all of the experience's form submissions. Requires access to the experience.", "operationId": "deleteFormSubmissions", "tags": [ "form_submissions" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}/form_submissions/{form_submission_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/experienceId" }, { "$ref": "#/components/parameters/formSubmissionId" } ], "delete": { "operationId": "deleteFormSubmission", "security": [ { "access_token": [ "form_submissions:write" ] } ], "summary": "Delete a form submission", "description": "Deletes the form submission.", "tags": [ "form_submissions" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}/form_submissions/metrics": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/experienceId" } ], "get": { "security": [ {}, { "access_token": [] } ], "summary": "Retrieve form submission metrics", "description": "Returns form submission counts grouped by the `group` parameter. The request's `Referer` must be allowed for the experience. When called without an `Authorization` header, this endpoint is public.", "operationId": "getFormSubmissionsMetrics", "tags": [ "form_submissions" ], "parameters": [ { "$ref": "#/components/parameters/formSubmissionMetricGroup" }, { "$ref": "#/components/parameters/formSubmissionMetricFilter" }, { "$ref": "#/components/parameters/formSubmissionMetricRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/formSubmissionMetricsWhenAuthorized" }, "400": { "$ref": "#/components/responses/formSubmissionMetricsBadRequest" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}/form_submissions/export/requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/experienceId" } ], "post": { "security": [ { "access_token": [ "form_submissions:read" ] } ], "summary": "Create a form submission export request", "description": "Form submissions are exported asynchronously. Once complete, a websocket message of type `form_submissions_export_request` containing the status and URL is delivered to the user's private channel (`private-user-` followed by the user's ID), and the `exported` webhook event is sent. You may also poll the export request until it completes.", "operationId": "createFormSubmissionExportRequest", "tags": [ "form_submissions" ], "parameters": [ { "$ref": "#/components/parameters/formSubmissionExportRequestRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createFormSubmissionExportRequest" }, "responses": { "202": { "$ref": "#/components/responses/formSubmissionExportRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/experiences/{experience_id}/form_submissions/export/requests/{form_submission_export_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/experienceId" }, { "$ref": "#/components/parameters/formSubmissionExportRequestId" } ], "get": { "security": [ { "access_token": [ "form_submissions:read" ] } ], "summary": "Retrieve a form submission export request", "description": "Use this endpoint to check the status of an asynchronous form submission export request. Requires access to the exported experience.", "operationId": "getFormSubmissionExportRequest", "tags": [ "form_submissions" ], "parameters": [ { "$ref": "#/components/parameters/formSubmissionExportRequestRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/formSubmissionExportRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/posts": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "posts:read" ] } ], "summary": "Retrieve a list of posts", "description": "Returns the posts of the boards you have access to, newest pinned posts first by default. Returns `503` while search is temporarily unavailable.", "operationId": "listPosts", "tags": [ "posts" ], "parameters": [ { "$ref": "#/components/parameters/postFilter" }, { "$ref": "#/components/parameters/postSort" }, { "$ref": "#/components/parameters/postRelationships" }, { "$ref": "#/components/parameters/postCollapse" }, { "$ref": "#/components/parameters/cursorPagination" } ], "responses": { "200": { "$ref": "#/components/responses/postsWhenAuthorized" } } }, "delete": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Delete multiple posts", "description": "Deletes several posts of the board at once.", "operationId": "deletePosts", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/deletePosts" }, "responses": { "204": { "$ref": "#/components/responses/204" } } }, "patch": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Update multiple posts", "description": "The request is validated as a whole: if any post is invalid, none are updated.", "operationId": "updatePosts", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/updatePosts" }, "responses": { "200": { "$ref": "#/components/responses/postsUpdated" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/posts/metrics/moderated": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "summary": "Retrieve aggregated post moderation metrics", "operationId": "getPostsModeratedMetrics", "tags": [ "posts" ], "security": [ { "access_token": [ "posts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/postsModeratedMetricsFilter" }, { "$ref": "#/components/parameters/postsModeratedMetricsGroup" } ], "responses": { "200": { "$ref": "#/components/responses/postsModeratedMetricsWhenAuthorized" } } } }, "/v2/teams/{team_id}/posts/metrics/engagements/{post_engagement_type}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/postEngagementType" } ], "get": { "security": [ { "access_token": [ "posts:read" ] } ], "summary": "Retrieve aggregated post engagement metrics", "operationId": "getPostsEngagementMetrics", "tags": [ "posts" ], "parameters": [ { "$ref": "#/components/parameters/postsEngagementMetricsFilter" }, { "$ref": "#/components/parameters/postsEngagementMetricsGroup" } ], "responses": { "200": { "$ref": "#/components/responses/postsEngagementMetricsWhenAuthorized" } } } }, "/v2/teams/{team_id}/posts/metrics/ingested": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ {}, { "access_token": [ "posts:read" ] } ], "summary": "Retrieve aggregated post ingestion metrics", "description": "Provides up to 12 months of ingestion metrics. Authentication isn't required when `filter[social_feed_id]` or `filter[tint_id]` is specified; otherwise, the access token must have the `posts:read` scope.", "operationId": "getPostsIngestedMetrics", "tags": [ "posts" ], "parameters": [ { "$ref": "#/components/parameters/postsIngestedMetricsFilter" }, { "$ref": "#/components/parameters/postsIngestedMetricsGroup" } ], "responses": { "200": { "$ref": "#/components/responses/postsIngestedMetricsWhenAuthorized" } } } }, "/v2/teams/{team_id}/posts/{post_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/postId" } ], "patch": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Update a post", "description": "Updates the post.", "operationId": "updatePost", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/updatePost" }, "responses": { "200": { "$ref": "#/components/responses/postWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Delete a post", "description": "Deletes the post.", "operationId": "deletePost", "tags": [ "posts" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/posts": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "posts:read" ] } ], "summary": "Retrieve a list of posts for a board", "description": "This endpoint is deprecated. Use `GET /v2/teams/{team_id}/posts?filter[tint_id]={tint_id}` instead, which accepts the same parameters.", "deprecated": true, "operationId": "listTintPosts", "tags": [ "posts" ], "parameters": [ { "$ref": "#/components/parameters/postFilter" }, { "$ref": "#/components/parameters/postSort" }, { "$ref": "#/components/parameters/postRelationships" }, { "$ref": "#/components/parameters/postCollapse" }, { "$ref": "#/components/parameters/cursorPagination" } ], "responses": { "200": { "$ref": "#/components/responses/postsWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "posts:write" ] } ], "summary": "Create a custom post", "description": "Asynchronously creates a post in the board's custom social feed (the feed is created if it doesn't exist). The response is a post create request; the post itself is created shortly after.", "operationId": "createTintPost", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/createTintPost" }, "responses": { "202": { "$ref": "#/components/responses/postRequestWhenUnauthorized" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/tints/{tint_slug}/posts": { "parameters": [ { "$ref": "#/components/parameters/tintSlug" } ], "get": { "security": [ {}, { "access_token": [ "posts:read" ] } ], "summary": "Retrieve a list of public posts for a board", "description": "Returns the public posts of a public board. No authentication is required; if an `Authorization` header is sent, the access token must have the `posts:read` scope.", "operationId": "listPublicTintPosts", "tags": [ "posts" ], "parameters": [ { "$ref": "#/components/parameters/publicPostFilter" }, { "$ref": "#/components/parameters/postSort" }, { "$ref": "#/components/parameters/publicPostRelationships" }, { "$ref": "#/components/parameters/cursorPagination" } ], "responses": { "200": { "$ref": "#/components/responses/postsWhenUnauthorized" } } }, "post": { "security": [ {}, { "access_token": [ "posts:write" ] } ], "summary": "Create a public post", "description": "Asynchronously creates a post in the board's public post social feed. No authentication is required; if an `Authorization` header is sent, the access token must have the `posts:write` scope. The response is a post create request whose status can be checked using `GET /v2/tints/{tint_slug}/posts/requests/{post_request_id}`.", "operationId": "createPublicTintPost", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/createPublicTintPost" }, "responses": { "202": { "$ref": "#/components/responses/postRequestWhenUnauthorized" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/tints/{tint_slug}/posts/summaries": { "parameters": [ { "$ref": "#/components/parameters/tintSlug" } ], "post": { "security": [ {}, { "access_token": [ "posts:read" ] } ], "summary": "Generate or retrieve a posts summary", "description": "Generates or retrieves a summary of the posts of the specified board. No authentication is required; if an\n`Authorization` header is sent, the access token must have the `posts:read` scope.\n\nIf the summary already exists and is up to date, the request returns `200 OK` with the summary, or\n`204 No Content` if the summary is empty. If the summary needs to be generated, the request returns\n`202 Accepted` and the summary will be available shortly.", "operationId": "createPostsSummary", "tags": [ "posts_summaries" ], "parameters": [ { "$ref": "#/components/parameters/postsSummaryRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createPostsSummary" }, "responses": { "200": { "$ref": "#/components/responses/postsSummaryWhenAuthorized" }, "202": { "$ref": "#/components/responses/postsSummaryAcceptedWhenAuthorized" }, "204": { "$ref": "#/components/responses/204" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/tints/{tint_slug}/posts/requests/{post_request_id}": { "parameters": [ { "$ref": "#/components/parameters/tintSlug" }, { "$ref": "#/components/parameters/postRequestId" } ], "get": { "security": [ {}, { "access_token": [ "posts:read" ] } ], "summary": "Check the status of a post create request", "description": "Returns the status of an asynchronous request created by `POST /v2/tints/{tint_slug}/posts`. No authentication is required; if an `Authorization` header is sent, the access token must have the `posts:read` scope.", "operationId": "getPostCreateRequest", "tags": [ "posts" ], "responses": { "200": { "$ref": "#/components/responses/postRequestWhenUnauthorized" } } } }, "/v2/teams/{team_id}/posts/export/requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "post": { "security": [ { "access_token": [ "posts:read" ] } ], "summary": "Create a post export request", "description": "Asynchronously exports posts. Once complete, a websocket message of type `post_export_request` containing the response is delivered to the user's private channel (`private-user-` followed by the user's ID). You may also poll the status of the request using the endpoint below.", "operationId": "createPostExportRequest", "tags": [ "posts" ], "requestBody": { "$ref": "#/components/requestBodies/createPostExportRequest" }, "responses": { "202": { "$ref": "#/components/responses/postExportRequestWhenAuthorized" } } } }, "/v2/teams/{team_id}/posts/export/requests/{post_export_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/postExportRequestId" } ], "get": { "security": [ { "access_token": [ "posts:read" ] } ], "summary": "Check the status of a post export request", "operationId": "getPostExportRequest", "tags": [ "posts" ], "responses": { "200": { "$ref": "#/components/responses/postExportRequestWhenAuthorized" } } } }, "/v2/teams/{team_id}/collections": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "collections:read" ] } ], "summary": "Retrieve a list of collections", "description": "Returns the collections you have access to.", "operationId": "listCollections", "tags": [ "collections" ], "parameters": [ { "$ref": "#/components/parameters/collectionFilter" }, { "$ref": "#/components/parameters/collectionSort" }, { "$ref": "#/components/parameters/collectionRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/collectionsWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "collections:write" ] } ], "summary": "Create a collection", "description": "Creates a collection.", "operationId": "createCollection", "tags": [ "collections" ], "parameters": [ { "$ref": "#/components/parameters/collectionRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createCollection" }, "responses": { "201": { "$ref": "#/components/responses/collectionWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "patch": { "security": [ { "access_token": [ "collections:write" ] } ], "summary": "Update multiple collections", "description": "The request is validated as a whole: if any collection is invalid, none are updated.", "operationId": "updateCollections", "tags": [ "collections" ], "requestBody": { "$ref": "#/components/requestBodies/updateCollections" }, "responses": { "200": { "$ref": "#/components/responses/collectionsUpdated" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "collections:write" ] } ], "summary": "Delete multiple collections", "description": "Deletes several collections at once.", "operationId": "deleteCollections", "tags": [ "collections" ], "requestBody": { "$ref": "#/components/requestBodies/deleteCollections" }, "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/collections/{collection_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/collectionId" } ], "patch": { "security": [ { "access_token": [ "collections:write" ] } ], "summary": "Update a collection", "description": "Updates the collection.", "operationId": "updateCollection", "tags": [ "collections" ], "parameters": [ { "$ref": "#/components/parameters/collectionRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateCollection" }, "responses": { "200": { "$ref": "#/components/responses/collectionWhenAuthorized" } } }, "delete": { "security": [ { "access_token": [ "collections:write" ] } ], "summary": "Delete a collection", "description": "Deletes the collection.", "operationId": "deleteCollection", "tags": [ "collections" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/oauth/applications": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [] }, { "access_token": [], "id_token": [] } ], "summary": "Retrieve a list of OAuth applications", "description": "Returns the team's OAuth applications that the current user has access to through their role. Send a valid `id_token` as well to get the `client_secret` of each application.", "operationId": "listOAuthApplications", "tags": [ "oauth_applications" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/oauthApplicationsSort" } ], "responses": { "200": { "$ref": "#/components/responses/oauthApplicationsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [] }, { "access_token": [], "id_token": [] } ], "summary": "Create an OAuth application", "description": "Creates an OAuth application owned by the team. The current user's role, and every role that has access to new OAuth applications, get access to it. Send a valid `id_token` as well to get the `client_secret` in the response.", "operationId": "createOAuthApplication", "tags": [ "oauth_applications" ], "requestBody": { "$ref": "#/components/requestBodies/createOAuthApplication" }, "responses": { "201": { "$ref": "#/components/responses/oauthApplicationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/oauth/applications/{oauth_application_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/oauthApplicationId" } ], "get": { "security": [ { "access_token": [] }, { "access_token": [], "id_token": [] } ], "summary": "Retrieve an OAuth application", "description": "Retrieves one of the team's OAuth applications. Send a valid `id_token` as well to get the `client_secret` in the response.", "operationId": "getOAuthApplication", "tags": [ "oauth_applications" ], "responses": { "200": { "$ref": "#/components/responses/oauthApplicationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [] }, { "access_token": [], "id_token": [] } ], "summary": "Update an OAuth application", "description": "Updates the OAuth application. Send a valid `id_token` as well to get the `client_secret` in the response.", "operationId": "updateOAuthApplication", "tags": [ "oauth_applications" ], "requestBody": { "$ref": "#/components/requestBodies/updateOAuthApplication" }, "responses": { "200": { "$ref": "#/components/responses/oauthApplicationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [] } ], "summary": "Delete an OAuth application", "description": "Deletes the OAuth application.", "operationId": "deleteOAuthApplication", "tags": [ "oauth_applications" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/webhooks": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "webhooks:read" ] } ], "summary": "Retrieve a list of webhooks", "description": "Returns the webhooks the current user has access to.", "operationId": "listWebhooks", "tags": [ "webhooks" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/webhookSort" } ], "responses": { "200": { "$ref": "#/components/responses/webhooksWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "webhooks:write" ] } ], "summary": "Create a webhook", "description": "The new webhook is shared with the roles that are granted access to new webhooks and with the current user's role.", "operationId": "createWebhook", "tags": [ "webhooks" ], "requestBody": { "$ref": "#/components/requestBodies/createWebhook" }, "responses": { "201": { "$ref": "#/components/responses/webhookCreated" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/webhooks/{webhook_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/webhookId" } ], "get": { "security": [ { "access_token": [ "webhooks:read" ] } ], "summary": "Retrieve a webhook", "description": "Retrieves one of the team's webhooks.", "operationId": "getWebhook", "tags": [ "webhooks" ], "responses": { "200": { "$ref": "#/components/responses/webhookWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "webhooks:write" ] } ], "summary": "Update a webhook", "description": "Updates the webhook.", "operationId": "updateWebhook", "tags": [ "webhooks" ], "requestBody": { "$ref": "#/components/requestBodies/updateWebhook" }, "responses": { "200": { "$ref": "#/components/responses/webhookWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "webhooks:write" ] } ], "summary": "Delete a webhook", "description": "Deleting a webhook also deletes its events.", "operationId": "deleteWebhook", "tags": [ "webhooks" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/webhooks/{webhook_id}/events": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/webhookId" } ], "get": { "security": [ { "access_token": [ "webhooks:read" ] } ], "summary": "Retrieve a list of webhook events", "description": "Returns the events recorded for a webhook, with the payload we sent and their delivery status.", "operationId": "listWebhookEvents", "tags": [ "webhook_events" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/webhookEventFilter" }, { "$ref": "#/components/parameters/webhookEventSort" }, { "$ref": "#/components/parameters/webhookEventInclude" } ], "responses": { "200": { "$ref": "#/components/responses/webhookEventsWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/webhooks/{webhook_id}/events/{webhook_event_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/webhookId" }, { "$ref": "#/components/parameters/webhookEventId" } ], "get": { "security": [ { "access_token": [ "webhooks:read" ] } ], "summary": "Retrieve a webhook event", "description": "Retrieves one of the webhook's events, with the payload we sent and its delivery status.", "operationId": "getWebhookEvent", "tags": [ "webhook_events" ], "parameters": [ { "$ref": "#/components/parameters/webhookEventInclude" } ], "responses": { "200": { "$ref": "#/components/responses/webhookEventWhenAuthorized" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/saved_filters": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "saved_filters:read" ] } ], "summary": "Retrieve a list of saved filters", "operationId": "listSavedFilters", "tags": [ "saved_filters" ], "parameters": [ { "$ref": "#/components/parameters/savedFilterRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/savedFiltersWhenAuthorized" } } }, "post": { "security": [ { "access_token": [ "saved_filters:write" ] } ], "summary": "Create a saved filter", "operationId": "createSavedFilter", "tags": [ "saved_filters" ], "parameters": [ { "$ref": "#/components/parameters/savedFilterRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createSavedFilter" }, "responses": { "201": { "$ref": "#/components/responses/savedFilterWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/saved_filters/{saved_filter_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" }, { "$ref": "#/components/parameters/savedFilterId" } ], "get": { "security": [ { "access_token": [ "saved_filters:read" ] } ], "summary": "Retrieve a saved filter", "operationId": "getSavedFilter", "tags": [ "saved_filters" ], "parameters": [ { "$ref": "#/components/parameters/savedFilterRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/savedFilterWhenAuthorized" } } }, "patch": { "security": [ { "access_token": [ "saved_filters:write" ] } ], "summary": "Update a saved filter", "operationId": "updateSavedFilter", "tags": [ "saved_filters" ], "requestBody": { "$ref": "#/components/requestBodies/updateSavedFilter" }, "responses": { "200": { "$ref": "#/components/responses/savedFilterWhenAuthorized" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "saved_filters:write" ] } ], "summary": "Delete a saved filter", "operationId": "deleteSavedFilter", "tags": [ "saved_filters" ], "responses": { "204": { "$ref": "#/components/responses/204" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/ctas": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "get": { "security": [ { "access_token": [ "ctas:read" ] } ], "summary": "Retrieve a list of CTAs", "description": "Returns the CTAs of the board.", "operationId": "listCtas", "tags": [ "ctas" ], "parameters": [ { "$ref": "#/components/parameters/pagination" }, { "$ref": "#/components/parameters/ctaRelationships" }, { "$ref": "#/components/parameters/ctaSort" } ], "responses": { "200": { "$ref": "#/components/responses/ctasWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "post": { "security": [ { "access_token": [ "ctas:write" ] } ], "summary": "Create a CTA", "description": "Creates a CTA on the board.", "operationId": "createCta", "tags": [ "ctas" ], "parameters": [ { "$ref": "#/components/parameters/ctaRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createCta" }, "responses": { "201": { "$ref": "#/components/responses/ctaWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/ctas/{cta_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" }, { "$ref": "#/components/parameters/ctaId" } ], "get": { "security": [ { "access_token": [ "ctas:read" ] } ], "summary": "Retrieve a CTA", "description": "Retrieves one of the board's CTAs.", "operationId": "getCta", "tags": [ "ctas" ], "parameters": [ { "$ref": "#/components/parameters/ctaRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/ctaWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "ctas:write" ] } ], "summary": "Update a CTA", "description": "Updates the CTA.", "operationId": "updateCta", "tags": [ "ctas" ], "parameters": [ { "$ref": "#/components/parameters/ctaRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/updateCta" }, "responses": { "200": { "$ref": "#/components/responses/ctaWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "ctas:write" ] } ], "summary": "Delete a CTA", "description": "Deletes the CTA and removes it from every post and saved filter it was applied to.", "operationId": "deleteCta", "tags": [ "ctas" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/cta_associations": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" } ], "post": { "security": [ { "access_token": [ "posts:write" ] }, { "access_token": [ "saved_filters:write" ] } ], "summary": "Create a CTA association", "description": "Applies a CTA to a post or a saved filter of the board. A token with either the `posts:write` or the `saved_filters:write` scope is accepted.", "operationId": "createCtaAssociation", "tags": [ "ctas" ], "parameters": [ { "$ref": "#/components/parameters/ctaAssociationRelationships" } ], "requestBody": { "$ref": "#/components/requestBodies/createCtaAssociation" }, "responses": { "201": { "$ref": "#/components/responses/ctaAssociationWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/tints/{tint_id}/cta_associations/{cta_association_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/tintId" }, { "$ref": "#/components/parameters/ctaAssociationId" } ], "delete": { "security": [ { "access_token": [ "posts:write" ] }, { "access_token": [ "saved_filters:write" ] } ], "summary": "Delete a CTA association", "description": "Removes a CTA from a post or a saved filter of the board. A token with either the `posts:write` or the `saved_filters:write` scope is accepted.", "operationId": "deleteCtaAssociation", "tags": [ "ctas" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/roles": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "roles:read" ] } ], "summary": "Retrieve a list of roles", "description": "Returns the team's roles.", "operationId": "listRoles", "tags": [ "roles" ], "parameters": [ { "$ref": "#/components/parameters/roleInclude" }, { "$ref": "#/components/parameters/roleFilter" }, { "$ref": "#/components/parameters/roleSort" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/rolesWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "roles:write" ] } ], "summary": "Create a role", "description": "Creates a role for the team.", "operationId": "createRole", "tags": [ "roles" ], "requestBody": { "$ref": "#/components/requestBodies/createRole" }, "responses": { "201": { "$ref": "#/components/responses/roleWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/roles/{role_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/roleId" } ], "get": { "security": [ { "access_token": [ "roles:read" ] } ], "summary": "Retrieve a role", "description": "Retrieves one of the team's roles.", "operationId": "getRole", "tags": [ "roles" ], "parameters": [ { "$ref": "#/components/parameters/roleInclude" } ], "responses": { "200": { "$ref": "#/components/responses/roleWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } }, "patch": { "security": [ { "access_token": [ "roles:write" ] } ], "summary": "Update a role", "description": "Updates the role.", "operationId": "updateRole", "tags": [ "roles" ], "requestBody": { "$ref": "#/components/requestBodies/updateRole" }, "responses": { "200": { "$ref": "#/components/responses/roleWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" } } }, "delete": { "security": [ { "access_token": [ "roles:write" ] } ], "summary": "Delete a role", "description": "Deletes the role. Team members who are assigned the role are removed from the team along with it.", "operationId": "deleteRole", "tags": [ "roles" ], "responses": { "204": { "$ref": "#/components/responses/204" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } }, "/v2/teams/{team_id}/privacy/requests": { "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "get": { "security": [ { "access_token": [ "privacy_requests:read" ] } ], "summary": "Retrieve a list of privacy requests", "operationId": "listPrivacyRequests", "tags": [ "privacy_requests" ], "parameters": [ { "$ref": "#/components/parameters/privacyRequestSort" }, { "$ref": "#/components/parameters/privacyRequestRelationships" }, { "$ref": "#/components/parameters/pagination" } ], "responses": { "200": { "$ref": "#/components/responses/privacyRequestsWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" } } }, "post": { "security": [ { "access_token": [ "privacy_requests:write" ] } ], "summary": "Create a privacy request", "description": "Creates a privacy request and processes it asynchronously. For an `erasure` request, the loyalty member's form submissions and assets are deleted and their community member profile is anonymized and deactivated. Poll the request until its `status` is `success` or `failure`.", "operationId": "createPrivacyRequest", "tags": [ "privacy_requests" ], "requestBody": { "$ref": "#/components/requestBodies/createPrivacyRequest" }, "responses": { "201": { "$ref": "#/components/responses/privacyRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" } } } }, "/v2/teams/{team_id}/privacy/requests/{privacy_request_id}": { "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/privacyRequestId" } ], "get": { "security": [ { "access_token": [ "privacy_requests:read" ] } ], "summary": "Retrieve a privacy request", "operationId": "getPrivacyRequest", "tags": [ "privacy_requests" ], "parameters": [ { "$ref": "#/components/parameters/privacyRequestRelationships" } ], "responses": { "200": { "$ref": "#/components/responses/privacyRequestWhenAuthorized" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" } } } } }, "webhooks": { "account_created": { "post": { "summary": "account_created", "description": "Sent when a social or integration account is connected to the team.\n\n`relationships.object.data` identifies the account, and `included` contains the account.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "accountCreatedWebhook", "tags": [ "account_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `account_created` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "account_created" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The account this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the account.", "items": { "$ref": "#/components/schemas/Account" } } } }, "example": { "data": { "id": "1377451", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "account_created" }, "relationships": { "object": { "data": { "type": "account", "id": "310" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "310", "type": "account", "attributes": { "external_id": "17841400000000000", "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-14T16:42:07.000Z", "status": "ok", "name": "Acme Outdoors", "username": "acmeoutdoors", "expires_at": "2025-05-13T16:42:07.000Z", "image_url": "https://cdn.example.com/accounts/310/avatar.jpg", "capabilities": [ "ingest", "compose" ], "meta": {}, "likes_count": null, "media_count": 214, "followers_count": 5210, "follows_count": 180, "site": null, "type": "instagram_business" }, "relationships": { "subaccounts": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "account_updated": { "post": { "summary": "account_updated", "description": "Sent when the `status` of one of the team's accounts changes (for example, when its authorization expires or is renewed). Other changes to the account do not send this event.\n\n`relationships.object.data` identifies the account, and `included` contains the account.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "accountUpdatedWebhook", "tags": [ "account_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `account_updated` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "account_updated" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The account this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the account.", "items": { "$ref": "#/components/schemas/Account" } } } }, "example": { "data": { "id": "1377452", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "account_updated" }, "relationships": { "object": { "data": { "type": "account", "id": "310" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "310", "type": "account", "attributes": { "external_id": "17841400000000000", "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-14T16:42:07.000Z", "status": "ok", "name": "Acme Outdoors", "username": "acmeoutdoors", "expires_at": "2025-05-13T16:42:07.000Z", "image_url": "https://cdn.example.com/accounts/310/avatar.jpg", "capabilities": [ "ingest", "compose" ], "meta": {}, "likes_count": null, "media_count": 214, "followers_count": 5210, "follows_count": 180, "site": null, "type": "instagram_business" }, "relationships": { "subaccounts": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "account_destroyed": { "post": { "summary": "account_destroyed", "description": "Sent when one of the team's accounts is disconnected (deleted).\n\n`relationships.object.data` identifies the deleted account. The account no longer exists by the time you receive the event, so don't rely on `included`: it may be empty, or contain the account as it was just before it was deleted. When it is empty, a webhook `filter` has nothing to match against and the event is delivered anyway.", "operationId": "accountDestroyedWebhook", "tags": [ "account_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `account_destroyed` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "account_destroyed" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The deleted account.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "Don't rely on it: the account no longer exists, so this may be empty.", "items": { "$ref": "#/components/schemas/Account" } } } }, "example": { "data": { "id": "1377453", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "account_destroyed" }, "relationships": { "object": { "data": { "type": "account", "id": "310" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "asset_created": { "post": { "summary": "asset_created", "description": "Sent when an asset is added to the team, whether uploaded, imported or created in bulk.\n\n`relationships.object.data` identifies the asset, and `included` contains the asset, its `variants` and its `collections` (each collection with only its `name`).\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "assetCreatedWebhook", "tags": [ "asset_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `asset_created` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "asset_created" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The asset this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the asset, its `variants` and its `collections` (each collection with only its `name`).", "items": { "oneOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/Collection" }, { "$ref": "#/components/schemas/Variant" } ] } } } }, "example": { "data": { "id": "1377454", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "asset_created" }, "relationships": { "object": { "data": { "type": "asset", "id": "5501" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "5501", "type": "asset", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-14T16:42:07.000Z", "status": "active", "source": "branded", "objects": [ "shoe" ], "source_url": null, "name": "Trail boots hero shot", "description": null, "insights": {}, "alternative_text": "A hiker lacing up brown leather boots.", "tags": [ "summer" ], "emotions": [], "infections": [], "licenses": null, "sfw": true, "imported_from_data": null, "caption": null, "author": null, "post_text": null, "post_title": null, "text": null, "url": "https://cdn.example.com/assets/5501/original.jpg", "thumbnail_url": "https://cdn.example.com/assets/5501/thumbnail.jpg", "expanded_url": "https://cdn.example.com/assets/5501/original.jpg", "duration": null, "dimensions": [ 1920, 1080 ], "mime_type": "image/jpeg", "size": 482113, "download_url": "https://cdn.example.com/assets/5501/original.jpg" }, "relationships": { "person": { "data": { "type": "person", "id": "120045" } }, "media": { "data": null }, "variants": { "data": [ { "type": "variant", "id": "5501" } ], "meta": { "total": 1 } }, "collections": { "data": [ { "type": "collection", "id": "77" } ] }, "imported_from": { "meta": { "included": false } } }, "links": { "self": "https://api.tintup.com/v2/teams/1/assets/5501" } }, { "id": "5501", "type": "variant", "attributes": { "url": "https://cdn.example.com/assets/5501/original.jpg", "expanded_url": "https://cdn.example.com/assets/5501/original.jpg", "mime_type": "image/jpeg", "size": 482113, "dimensions": [ 1920, 1080 ], "duration": null, "thumbnail_url": "https://cdn.example.com/assets/5501/thumbnail.jpg", "source_url": null, "title": "Trail boots hero shot", "description": null, "transformations": null, "enhance": null, "insights": {} } }, { "id": "77", "type": "collection", "attributes": { "name": "Summer campaign" }, "relationships": { "assets": { "meta": { "total": 12, "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "asset_updated": { "post": { "summary": "asset_updated", "description": "Sent when one of the team's assets changes, including bulk updates.\n\n`relationships.object.data` identifies the asset, and `included` contains the asset, its `variants` and its `collections` (each collection with only its `name`).\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "assetUpdatedWebhook", "tags": [ "asset_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `asset_updated` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "asset_updated" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The asset this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the asset, its `variants` and its `collections` (each collection with only its `name`).", "items": { "oneOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/Collection" }, { "$ref": "#/components/schemas/Variant" } ] } } } }, "example": { "data": { "id": "1377455", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "asset_updated" }, "relationships": { "object": { "data": { "type": "asset", "id": "5501" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "5501", "type": "asset", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-14T16:42:07.000Z", "status": "active", "source": "branded", "objects": [ "shoe" ], "source_url": null, "name": "Trail boots hero shot", "description": null, "insights": {}, "alternative_text": "A hiker lacing up brown leather boots.", "tags": [ "summer" ], "emotions": [], "infections": [], "licenses": null, "sfw": true, "imported_from_data": null, "caption": null, "author": null, "post_text": null, "post_title": null, "text": null, "url": "https://cdn.example.com/assets/5501/original.jpg", "thumbnail_url": "https://cdn.example.com/assets/5501/thumbnail.jpg", "expanded_url": "https://cdn.example.com/assets/5501/original.jpg", "duration": null, "dimensions": [ 1920, 1080 ], "mime_type": "image/jpeg", "size": 482113, "download_url": "https://cdn.example.com/assets/5501/original.jpg" }, "relationships": { "person": { "data": { "type": "person", "id": "120045" } }, "media": { "data": null }, "variants": { "data": [ { "type": "variant", "id": "5501" } ], "meta": { "total": 1 } }, "collections": { "data": [ { "type": "collection", "id": "77" } ] }, "imported_from": { "meta": { "included": false } } }, "links": { "self": "https://api.tintup.com/v2/teams/1/assets/5501" } }, { "id": "5501", "type": "variant", "attributes": { "url": "https://cdn.example.com/assets/5501/original.jpg", "expanded_url": "https://cdn.example.com/assets/5501/original.jpg", "mime_type": "image/jpeg", "size": 482113, "dimensions": [ 1920, 1080 ], "duration": null, "thumbnail_url": "https://cdn.example.com/assets/5501/thumbnail.jpg", "source_url": null, "title": "Trail boots hero shot", "description": null, "transformations": null, "enhance": null, "insights": {} } }, { "id": "77", "type": "collection", "attributes": { "name": "Summer campaign" }, "relationships": { "assets": { "meta": { "total": 12, "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "asset_destroyed": { "post": { "summary": "asset_destroyed", "description": "Sent when one of the team's assets is deleted, including bulk deletes.\n\n`relationships.object.data` identifies the deleted asset. The asset no longer exists by the time you receive the event, so don't rely on `included`: it may be empty, or contain the asset as it was just before it was deleted. When it is empty, a webhook `filter` has nothing to match against and the event is delivered anyway.", "operationId": "assetDestroyedWebhook", "tags": [ "asset_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `asset_destroyed` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "asset_destroyed" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The deleted asset.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "Don't rely on it: the asset no longer exists, so this may be empty.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Asset" }, { "$ref": "#/components/schemas/Collection" }, { "$ref": "#/components/schemas/Variant" } ] } } } }, "example": { "data": { "id": "1377456", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "asset_destroyed" }, "relationships": { "object": { "data": { "type": "asset", "id": "5501" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "asset_exported": { "post": { "summary": "asset_exported", "description": "Sent when an asset export (a ZIP file of the requested assets) requested through the API finishes, whether it succeeded or failed. Exports are generated asynchronously, so subscribe to this event instead of polling the export request.\n\n`relationships.object.data` identifies the export request, and `included` contains it. Check its `status`: `success` means `url` links to the file, `failure` means the export failed and `url` is `null`.\n\nThe `url` is a signed link that expires 15 minutes after the event was created, and a retried delivery carries the same link. If it has expired, retrieve the export request from the API to get a fresh one.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "assetExportedWebhook", "tags": [ "asset_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `asset_exported` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "asset_exported" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The export request this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset_export_request" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the export request.", "items": { "$ref": "#/components/schemas/AssetExportRequest" } } } }, "example": { "data": { "id": "1377464", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "asset_exported" }, "relationships": { "object": { "data": { "type": "asset_export_request", "id": "Q2kHzGx9aBcD1g" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "Q2kHzGx9aBcD1g", "type": "asset_export_request", "attributes": { "status": "success", "url": "https://exports.example.com/Q2kHzGx9aBcD1g.zip?X-Amz-Expires=900&X-Amz-Signature=5d41402abc4b2a76" }, "relationships": { "user": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "form_submission_created": { "post": { "summary": "form_submission_created", "description": "Sent when someone submits one of the team's experiences or forms.\n\n`relationships.object.data` identifies the form submission, and `included` contains the form submission, its `files` (as `upload` resources) and the loyalty member (`person`) it was matched to. Unlike in the REST API, the `post`, `experience`/`form` and `person` relationships always carry their linkage.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "formSubmissionCreatedWebhook", "tags": [ "form_submission_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `form_submission_created` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "form_submission_created" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The form submission this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form_submission" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the form submission, its `files` (as `upload` resources) and the loyalty member (`person`) it was matched to. Unlike in the REST API, the `post`, `experience`/`form` and `person` relationships always carry their linkage.", "items": { "oneOf": [ { "$ref": "#/components/schemas/FormSubmission" }, { "$ref": "#/components/schemas/LoyaltyMember" }, { "$ref": "#/components/schemas/Attachment" } ] } } } }, "example": { "data": { "id": "1377457", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "form_submission_created" }, "relationships": { "object": { "data": { "type": "form_submission", "id": "640021" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "640021", "type": "form_submission", "attributes": { "data": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "opt_in": "yes" }, "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15", "remote_ip_city": "Vancouver", "remote_ip_most_specific_subdivision": "BC", "remote_ip_country": "Canada", "referer": "https://www.example.com/contest", "locale": "en", "created_at": "2025-03-14T16:42:07.000Z", "metadata": {}, "city": "Vancouver, BC, Canada" }, "relationships": { "post": { "data": null }, "person": { "data": { "type": "person", "id": "65f3a1c2e4b0a91d2c7e8f10" } }, "experience": { "data": { "type": "experience", "id": "2012" } }, "files": { "data": [ { "type": "upload", "id": "eyJfcmFpbHMiOnsiZGF0YSI6OTg3NjU0LCJwdXIiOiJibG9iX2lkIn19--3b5f0c1d2e" } ] }, "terms": { "meta": { "included": false } } } }, { "id": "eyJfcmFpbHMiOnsiZGF0YSI6OTg3NjU0LCJwdXIiOiJibG9iX2lkIn19--3b5f0c1d2e", "type": "upload", "attributes": { "content_type": "image/jpeg", "url": "https://cdn.example.com/uploads/entry-photo.jpg", "thumbnail_url": "https://cdn.example.com/uploads/entry-photo-thumbnail.jpg" } }, { "id": "65f3a1c2e4b0a91d2c7e8f10", "type": "person", "attributes": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com", "external_id": "CUS-004211", "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-14T16:42:07.000Z", "enrolled_at": "2025-03-14T16:42:07.000Z", "last_interaction_at": "2025-03-14T16:42:07.000Z" } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "form_submission_exported": { "post": { "summary": "form_submission_exported", "description": "Sent when a form submission export (a ZIP file) requested through the API finishes, whether it succeeded or failed. Exports are generated asynchronously, so subscribe to this event instead of polling the export request.\n\n`relationships.object.data` identifies the export request, and `included` contains it. Check its `status`: `success` means `url` links to the file, `failure` means the export failed and `url` is `null`.\n\nThe `url` is a signed link that expires 15 minutes after the event was created, and a retried delivery carries the same link. If it has expired, retrieve the export request from the API to get a fresh one.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "formSubmissionExportedWebhook", "tags": [ "form_submission_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `form_submission_exported` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "form_submission_exported" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The export request this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form_submission_export_request" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the export request.", "items": { "$ref": "#/components/schemas/FormSubmissionExportRequest" } } } }, "example": { "data": { "id": "1377465", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "form_submission_exported" }, "relationships": { "object": { "data": { "type": "form_submission_export_request", "id": "OxZZQtuh5sXIKA" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "OxZZQtuh5sXIKA", "type": "form_submission_export_request", "attributes": { "status": "success", "url": "https://exports.example.com/OxZZQtuh5sXIKA.zip?X-Amz-Expires=900&X-Amz-Signature=5d41402abc4b2a76" }, "relationships": { "experience": { "meta": { "included": false } }, "form": { "meta": { "included": false } }, "user": { "meta": { "included": false } } }, "links": { "self": "https://api.tintup.com/v2/teams/1/experiences/2012/form_submissions/export/requests/OxZZQtuh5sXIKA" } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "post_created": { "post": { "summary": "post_created", "description": "Sent when a post is created on one of the boards of the team. Only posts from SMS, email and public post social feeds send this event.\n\n`relationships.object.data` identifies the post, and `included` contains the post.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "postCreatedWebhook", "tags": [ "post_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `post_created` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "post_created" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The post this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the post.", "items": { "$ref": "#/components/schemas/Post" } } } }, "example": { "data": { "id": "1377458", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "post_created" }, "relationships": { "object": { "data": { "type": "post", "id": "987654321" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "987654321", "type": "post", "attributes": { "highlighted": false, "pinned": false, "tags": [ "contest" ], "alternative_text": null, "title": null, "carousel": false, "attachment_id": null, "external_id": "SM5f1c2e9a7b", "verified": false, "incentivized": false, "text": "Loving my new Acme hiking boots! #AcmeOutdoors", "url": null, "last_moderated_at": null, "status": "public", "status_reasons": [], "hue_probability": null, "custom_field": null, "sentiment": "positive", "image_nsfw": null, "image_phash": null, "image_sentiments": null, "image_objects": null, "type": "sms", "published_at": "2025-03-14T16:42:07.000Z", "rating": null, "media_type": "image", "author": { "name": "Jane Doe", "username": null, "url": null, "image_url": null, "email": null, "phone": "+15555550123", "remote_ip": null, "external_id": null }, "metadata": { "language": "en", "sentiment": "positive" }, "image_url": "https://cdn.example.com/posts/987654321/image.jpg", "video_url": null, "language": null }, "relationships": { "social_feed": { "data": { "type": "social_feed", "id": "31337" } }, "tint": { "data": { "type": "tint", "id": "4242" }, "links": { "self": "https://api.tintup.com/v2/teams/1/tints/4242" } }, "author": { "meta": { "included": false } }, "product_tags": { "meta": { "included": false } }, "replies": { "meta": { "included": false } }, "products": { "meta": { "included": false } }, "cta_associations": { "meta": { "included": false } }, "asset": { "meta": { "included": false } }, "right_requests": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "post_updated": { "post": { "summary": "post_updated", "description": "Sent when a post changes (for example, when it is moderated). Only posts from SMS, email and public post social feeds send this event.\n\n`relationships.object.data` identifies the post, and `included` contains the post.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "postUpdatedWebhook", "tags": [ "post_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `post_updated` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "post_updated" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The post this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the post.", "items": { "$ref": "#/components/schemas/Post" } } } }, "example": { "data": { "id": "1377459", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "post_updated" }, "relationships": { "object": { "data": { "type": "post", "id": "987654321" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "987654321", "type": "post", "attributes": { "highlighted": false, "pinned": false, "tags": [ "contest" ], "alternative_text": null, "title": null, "carousel": false, "attachment_id": null, "external_id": "SM5f1c2e9a7b", "verified": false, "incentivized": false, "text": "Loving my new Acme hiking boots! #AcmeOutdoors", "url": null, "last_moderated_at": null, "status": "public", "status_reasons": [], "hue_probability": null, "custom_field": null, "sentiment": "positive", "image_nsfw": null, "image_phash": null, "image_sentiments": null, "image_objects": null, "type": "sms", "published_at": "2025-03-14T16:42:07.000Z", "rating": null, "media_type": "image", "author": { "name": "Jane Doe", "username": null, "url": null, "image_url": null, "email": null, "phone": "+15555550123", "remote_ip": null, "external_id": null }, "metadata": { "language": "en", "sentiment": "positive" }, "image_url": "https://cdn.example.com/posts/987654321/image.jpg", "video_url": null, "language": null }, "relationships": { "social_feed": { "data": { "type": "social_feed", "id": "31337" } }, "tint": { "data": { "type": "tint", "id": "4242" }, "links": { "self": "https://api.tintup.com/v2/teams/1/tints/4242" } }, "author": { "meta": { "included": false } }, "product_tags": { "meta": { "included": false } }, "replies": { "meta": { "included": false } }, "products": { "meta": { "included": false } }, "cta_associations": { "meta": { "included": false } }, "asset": { "meta": { "included": false } }, "right_requests": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "post_destroyed": { "post": { "summary": "post_destroyed", "description": "Sent when a post is deleted. Only posts from SMS, email and public post social feeds send this event.\n\n`relationships.object.data` identifies the deleted post. The post no longer exists by the time you receive the event, so don't rely on `included`: it may be empty, or contain the post as it was just before it was deleted. When it is empty, a webhook `filter` has nothing to match against and the event is delivered anyway.", "operationId": "postDestroyedWebhook", "tags": [ "post_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `post_destroyed` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "post_destroyed" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The deleted post.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "Don't rely on it: the post no longer exists, so this may be empty.", "items": { "$ref": "#/components/schemas/Post" } } } }, "example": { "data": { "id": "1377460", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "post_destroyed" }, "relationships": { "object": { "data": { "type": "post", "id": "987654321" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "post_exported": { "post": { "summary": "post_exported", "description": "Sent when a board's post export (a CSV file) requested through the API finishes, whether it succeeded or failed. Exports are generated asynchronously, so subscribe to this event instead of polling the export request.\n\n`relationships.object.data` identifies the export request, and `included` contains it. Check its `status`: `success` means `url` links to the file, `failure` means the export failed and `url` is `null`.\n\nThe `url` is a signed link that expires 15 minutes after the event was created, and a retried delivery carries the same link. If it has expired, retrieve the export request from the API to get a fresh one.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "postExportedWebhook", "tags": [ "post_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `post_exported` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "post_exported" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The export request this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post_export_request" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the export request.", "items": { "$ref": "#/components/schemas/PostExportRequest" } } } }, "example": { "data": { "id": "1377466", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "post_exported" }, "relationships": { "object": { "data": { "type": "post_export_request", "id": "Lm4pRt8vWx2YzA" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "Lm4pRt8vWx2YzA", "type": "post_export_request", "attributes": { "status": "success", "url": "https://exports.example.com/Lm4pRt8vWx2YzA.zip?X-Amz-Expires=900&X-Amz-Signature=5d41402abc4b2a76" }, "relationships": { "tint": { "meta": { "included": false } }, "user": { "meta": { "included": false } } }, "links": { "self": "https://api.tintup.com/v2/teams/1/posts/export/requests/Lm4pRt8vWx2YzA" } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "product_feed_created": { "post": { "summary": "product_feed_created", "description": "Sent when a product feed is created.\n\n`relationships.object.data` identifies the product feed, and `included` contains the product feed.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "productFeedCreatedWebhook", "tags": [ "product_feed_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `product_feed_created` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "product_feed_created" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The product feed this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product_feed" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the product feed.", "items": { "$ref": "#/components/schemas/ProductFeed" } } } }, "example": { "data": { "id": "1377461", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "product_feed_created" }, "relationships": { "object": { "data": { "type": "product_feed", "id": "88" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "88", "type": "product_feed", "attributes": { "source": "shopify", "name": "Acme store catalog", "status": "active", "last_ingested_at": "2025-03-14T16:42:07.000Z", "error_message": null, "options": {} }, "relationships": { "product_account": { "meta": { "included": false } }, "catalog": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "product_feed_updated": { "post": { "summary": "product_feed_updated", "description": "Sent when a product feed changes, including status changes after a sync.\n\n`relationships.object.data` identifies the product feed, and `included` contains the product feed.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "productFeedUpdatedWebhook", "tags": [ "product_feed_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `product_feed_updated` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "product_feed_updated" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The product feed this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product_feed" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the product feed.", "items": { "$ref": "#/components/schemas/ProductFeed" } } } }, "example": { "data": { "id": "1377462", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "product_feed_updated" }, "relationships": { "object": { "data": { "type": "product_feed", "id": "88" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "88", "type": "product_feed", "attributes": { "source": "shopify", "name": "Acme store catalog", "status": "active", "last_ingested_at": "2025-03-14T16:42:07.000Z", "error_message": null, "options": {} }, "relationships": { "product_account": { "meta": { "included": false } }, "catalog": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "product_feed_destroyed": { "post": { "summary": "product_feed_destroyed", "description": "Sent when a product feed is deleted.\n\n`relationships.object.data` identifies the deleted product feed. The product feed no longer exists by the time you receive the event, so don't rely on `included`: it may be empty, or contain the product feed as it was just before it was deleted. When it is empty, a webhook `filter` has nothing to match against and the event is delivered anyway.", "operationId": "productFeedDestroyedWebhook", "tags": [ "product_feed_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `product_feed_destroyed` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "product_feed_destroyed" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The deleted product feed.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product_feed" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "Don't rely on it: the product feed no longer exists, so this may be empty.", "items": { "$ref": "#/components/schemas/ProductFeed" } } } }, "example": { "data": { "id": "1377463", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "product_feed_destroyed" }, "relationships": { "object": { "data": { "type": "product_feed", "id": "88" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "teams_user_exported": { "post": { "summary": "teams_user_exported", "description": "Sent when an export of the team's users (a CSV file) requested through the API finishes, whether it succeeded or failed. Exports are generated asynchronously, so subscribe to this event instead of polling the export request.\n\n`relationships.object.data` identifies the export request, and `included` contains it. Check its `status`: `success` means `url` links to the file, `failure` means the export failed and `url` is `null`.\n\nThe `url` is a signed link that expires 15 minutes after the event was created, and a retried delivery carries the same link. If it has expired, retrieve the export request from the API to get a fresh one.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "teamsUserExportedWebhook", "tags": [ "team_user_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `teams_user_exported` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "teams_user_exported" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The export request this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "teams_user_export_request" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the export request.", "items": { "$ref": "#/components/schemas/TeamsUserExportRequest" } } } }, "example": { "data": { "id": "1377467", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "teams_user_exported" }, "relationships": { "object": { "data": { "type": "teams_user_export_request", "id": "Hn7sKd3fGj5LqP" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "Hn7sKd3fGj5LqP", "type": "teams_user_export_request", "attributes": { "status": "success", "url": "https://exports.example.com/Hn7sKd3fGj5LqP.zip?X-Amz-Expires=900&X-Amz-Signature=5d41402abc4b2a76" }, "relationships": { "team": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } }, "transaction_exported": { "post": { "summary": "transaction_exported", "description": "Sent when a loyalty transaction export (a ZIP file) requested through the API finishes, whether it succeeded or failed. Exports are generated asynchronously, so subscribe to this event instead of polling the export request.\n\n`relationships.object.data` identifies the export request, and `included` contains it. Check its `status`: `success` means `url` links to the file, `failure` means the export failed and `url` is `null`.\n\nThe `url` is a signed link that expires 15 minutes after the event was created, and a retried delivery carries the same link. If it has expired, retrieve the export request from the API to get a fresh one.\n\nThe payload below is the default JSON:API document. The webhook's `payload_include`, `payload_fields` and `payload_transformation_template` change it, and its `filter` decides whether the event is sent at all.", "operationId": "transactionExportedWebhook", "tags": [ "transaction_events" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/webhookSignatureHeader" }, { "$ref": "#/components/parameters/webhookApiVersionHeader" }, { "$ref": "#/components/parameters/webhookUserAgentHeader" } ], "requestBody": { "description": "The `transaction_exported` event.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/WebhookEventId" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "attributes": { "type": "object", "required": [ "name", "created_at" ], "properties": { "name": { "type": "string", "description": "The event name.", "enum": [ "transaction_exported" ] }, "created_at": { "$ref": "#/components/schemas/WebhookEventCreatedAt" } } }, "relationships": { "type": "object", "required": [ "object", "team" ], "properties": { "object": { "type": "object", "description": "The export request this event is about.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "transaction_export_request" ] }, "id": { "type": "string", "example": "1" } } } } }, "team": { "$ref": "#/components/schemas/WebhookEventTeamRelationship" } } } } }, "included": { "type": "array", "description": "The sideloaded resources: the export request.", "items": { "$ref": "#/components/schemas/TransactionExportRequest" } } } }, "example": { "data": { "id": "1377468", "type": "event", "attributes": { "created_at": "2025-03-14T16:42:07.000Z", "name": "transaction_exported" }, "relationships": { "object": { "data": { "type": "transaction_export_request", "id": "Tb9cVe1nMr6UwS" } }, "team": { "data": { "type": "team", "id": "1" } } } }, "included": [ { "id": "Tb9cVe1nMr6UwS", "type": "transaction_export_request", "attributes": { "status": "success", "url": "https://exports.example.com/Tb9cVe1nMr6UwS.zip?X-Amz-Expires=900&X-Amz-Signature=5d41402abc4b2a76" }, "relationships": { "user": { "meta": { "included": false } } } } ] } } } }, "responses": { "404": { "$ref": "#/components/responses/webhookDeliveryGone" }, "410": { "$ref": "#/components/responses/webhookDeliveryGone" }, "2XX": { "$ref": "#/components/responses/webhookDeliveryAcknowledged" }, "default": { "$ref": "#/components/responses/webhookDeliveryRetried" } } } } }, "components": { "securitySchemes": { "access_token": { "type": "oauth2", "description": "OAuth 2.0 authorization code flow.", "flows": { "authorizationCode": { "authorizationUrl": "https://id.tintup.com/oauth/authorize", "tokenUrl": "https://id.tintup.com/oauth/token", "refreshUrl": "https://id.tintup.com/oauth/token", "scopes": { "accounts:read": "Read access to accounts", "accounts:write": "Write access to accounts", "activities:read": "Read access to activities", "assets:read": "Read access to assets", "assets:write": "Write access to assets", "authentication_factors:read": "Read access to authentication factors", "authentication_factors:write": "Write access to authentication factors", "campaigns:read": "Read access to campaigns", "campaigns:write": "Write access to campaigns", "collections:read": "Read access to collections", "collections:write": "Write access to collections", "ctas:read": "Read access to CTAs", "ctas:write": "Write access to CTAs", "domains:read": "Read access to domains", "domains:write": "Write access to domains", "ecommerce:read": "Read access to e-commerce engagement metrics", "experiences:read": "Read access to experiences", "experiences:write": "Write access to experiences", "fonts:read": "Read access to fonts", "fonts:write": "Write access to fonts", "form_submissions:read": "Read access to form submissions", "form_submissions:write": "Write access to form submissions", "forms:read": "Read access to forms", "forms:write": "Write access to forms", "identity": "Read access to my user", "identity:write": "Write access to my user", "instint_updates:read": "Read access to InsTINT updates", "instint_updates:write": "Write access to InsTINT updates", "marketing_integrations:read": "Read access to marketing integrations", "marketing_integrations:write": "Write access to marketing integrations", "marketing_integrations_requests:read": "Read access to marketing integration publishing requests", "marketing_integrations_requests:write": "Publish access to marketing integrations", "mixes:read": "Read access to mixes", "mixes:write": "Write access to mixes", "oauth_applications:read": "Read access to OAuth 2.0 applications", "oauth_applications:write": "Write access to OAuth 2.0 applications", "personalizations:read": "Read access to personalizations", "personalizations:write": "Write access to personalizations", "posts:read": "Read access to posts", "posts:write": "Write access to posts", "privacy_requests:read": "Read access to privacy requests", "privacy_requests:write": "Write access to privacy requests", "product_accounts:read": "Read access to product accounts", "product_accounts:write": "Write access to product accounts", "product_feeds:read": "Read access to product feeds", "product_feeds:write": "Write access to product feeds", "products:read": "Read access to products", "products:write": "Write access to products", "rewards:read": "Read access to rewards", "right_request_templates:read": "Read access to right request templates", "right_request_templates:write": "Write access to right request templates", "right_request_terms:read": "Read access to right request terms", "right_request_terms:write": "Write access to right request terms", "right_requests:read": "Read access to right requests", "right_requests:write": "Write access to right requests", "roles:read": "Read access to roles", "roles:write": "Write access to roles", "saved_filters:read": "Read access to saved filters", "saved_filters:write": "Write access to saved filters", "schemas:read": "Read access to schemas", "schemas:write": "Write access to schemas", "social_feeds:read": "Read access to social feeds", "social_feeds:write": "Write access to social feeds", "subaccount_metrics:read": "Read access to account and subaccount metrics", "teams:read": "Read access to teams", "teams:write": "Write access to teams", "tints:read": "Read access to boards", "tints:write": "Write access to boards", "transactions:read": "Read access to transactions", "transactions:write": "Write access to transactions", "users:read": "Read access to team users", "users:write": "Write access to team users", "webhooks:read": "Read access to webhooks", "webhooks:write": "Write access to webhooks" } } } }, "id_token": { "type": "apiKey", "in": "query", "name": "id_token", "description": "A short-lived token required, in addition to an access token, to change sensitive data. See [Changes to Sensitive Data](advocacy/guides/sensitive-data.html)." } }, "requestBodies": { "createOAuthAccessToken": { "description": "The grant to exchange for an access token. Confidential applications authenticate with `client_id` and `client_secret`, either in the body or with HTTP Basic authentication (`Authorization: Basic base64(client_id:client_secret)`).", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "description": "The kind of grant being exchanged.", "enum": [ "authorization_code", "refresh_token" ], "example": "authorization_code" }, "client_id": { "type": "string", "description": "The application's `client_id`. Required unless sent with HTTP Basic authentication.", "example": "3a7c1e0b9d8f4e6a2b5c7d9e1f3a5b7c" }, "client_secret": { "type": "string", "description": "The application's `client_secret`. Required for confidential applications unless sent with HTTP Basic authentication.", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0" }, "code": { "type": "string", "description": "The authorization code received on `redirect_uri`. Required when `grant_type` is `authorization_code`. Codes expire after 5 minutes and can only be used once.", "example": "1b7e4c9a2d5f8e0c3a6b9d2e5f8a1c4b" }, "code_verifier": { "type": "string", "description": "The PKCE code verifier matching the `code_challenge` sent to the authorization endpoint. Required when `grant_type` is `authorization_code` and a `code_challenge` was sent.", "example": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" }, "redirect_uri": { "type": "string", "format": "uri", "description": "The same `redirect_uri` that was sent to the authorization endpoint. Required when `grant_type` is `authorization_code`.", "example": "https://reports.example.com/auth/callback" }, "refresh_token": { "type": "string", "description": "The refresh token returned with a previous access token. Required when `grant_type` is `refresh_token`. The response contains a new refresh token that replaces this one.", "example": "7d2f9b4e1a6c8e3f0b5d7a9c2e4f6a8b" }, "scope": { "type": "string", "description": "A space-delimited list of scopes. With `refresh_token`, it can narrow down the originally granted scopes.", "example": "tints:read posts:read" } } }, "example": { "grant_type": "authorization_code", "client_id": "3a7c1e0b9d8f4e6a2b5c7d9e1f3a5b7c", "client_secret": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "code": "1b7e4c9a2d5f8e0c3a6b9d2e5f8a1c4b", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "https://reports.example.com/auth/callback" } } } }, "createAccount": { "description": "The account to connect. Only account types that use credentials (API keys, passwords, etc.) can be created this way; OAuth-based accounts are connected with [Authenticate an account](#operation-v2-teams-team-id-accounts-new-get).", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewAccount" } } }, "example": { "data": { "type": "account", "attributes": { "type": "sftp", "access_token": "acme-feeds", "secret": "s3cr3t-Pa55word", "site": "sftp://files.example.com/feeds/products.csv" } } } } } }, "createProductFeedRefreshRequest": { "description": "The product feed to refresh and, for `csv` feeds, the CSV file to import.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewProductFeedRefreshRequest" } } }, "examples": { "csv": { "summary": "Import a new CSV file into a `csv` feed", "value": { "data": { "type": "product_feed_refresh_request", "attributes": { "product_feed_id": "12", "url": "https://files.example.com/exports/products.csv" } } } }, "integration": { "summary": "Re-sync a feed from its product account", "value": { "data": { "type": "product_feed_refresh_request", "attributes": { "product_feed_id": "12" } } } } } } } }, "createProduct": { "description": "The product to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewProduct" } } }, "example": { "data": { "type": "product", "attributes": { "product_feed_id": 12, "name": "Acme Runner 2 sneakers", "sku": "ACME-RUN2-BLK-42", "description": "Lightweight running sneakers with a breathable mesh upper.", "brand": "Acme", "family": "Acme Runner 2", "categories": [ "Footwear", "Running" ], "image_url": "https://cdn.example.com/products/acme-runner-2-black.jpg", "url": "https://shop.example.com/products/acme-runner-2", "currency": "USD", "price": "89.00", "availability": "in_stock" } } } } } }, "updateProduct": { "description": "The product attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductUpdate" } } }, "example": { "data": { "id": "1234", "type": "product", "attributes": { "sale_price": "69.00", "sale_price_starts_at": "2025-03-14T00:00:00.000Z", "sale_price_ends_at": "2025-03-31T23:59:59.000Z" } } } } } }, "createScheduledContent": { "description": "The content to schedule.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewScheduledContent" } } } } } }, "updateScheduledContent": { "description": "The attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScheduledContentUpdate" } } } } } }, "createCampaign": { "description": "The campaign to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewCampaign" } } }, "example": { "data": { "type": "campaign", "attributes": { "name": "Summer collection", "starts_at": "2025-06-01T00:00:00.000Z", "ends_at": "2025-08-31T23:59:59.000Z", "label_color": "#f5a623" } } } } } }, "updateCampaign": { "description": "The campaign attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CampaignUpdate" } } }, "example": { "data": { "id": "57", "type": "campaign", "attributes": { "ends_at": "2025-09-15T23:59:59.000Z" } } } } } }, "createProductFeed": { "description": "The product feed to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewProductFeed" } } }, "examples": { "shopify": { "summary": "Sync products from a Shopify product account", "value": { "data": { "type": "product_feed", "attributes": { "source": "shopify", "product_account_id": 7 } } } }, "csv": { "summary": "Import products from a CSV file", "value": { "data": { "type": "product_feed", "attributes": { "source": "csv", "name": "Acme spring collection", "url": "https://files.example.com/exports/products.csv" } } } }, "manual": { "summary": "Manage products using the API", "value": { "data": { "type": "product_feed", "attributes": { "source": "manual", "name": "Acme spring collection" } } } } } } } }, "createProductAccount": { "description": "The product account to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewProductAccount" } } }, "examples": { "woocommerce": { "summary": "Connect a WooCommerce store", "value": { "data": { "type": "product_account", "attributes": { "type": "woocommerce", "site": "https://shop.example.com", "access_token": "ck_4f7e2a9c1b3d5e6f", "secret": "cs_9a8b7c6d5e4f3a2b" } } } }, "s3": { "summary": "Connect an Amazon S3 bucket", "value": { "data": { "type": "product_account", "attributes": { "type": "s3", "site": "us-east-1", "external_id": "acme-product-exports" } } } } } } } }, "updateProductAccount": { "description": "The product account credentials to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductAccountUpdate" } } }, "example": { "data": { "id": "7", "type": "product_account", "attributes": { "access_token": "ck_1a2b3c4d5e6f7a8b", "secret": "cs_8b7a6f5e4d3c2b1a" } } } } } }, "createProductTag": { "description": "The product tag to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewProductTag" } } }, "example": { "data": { "type": "product_tag", "attributes": { "product_id": 1234, "source": "instagram_business", "external_id": "17912345678901234", "attachment_id": "17895695668004550", "x": "50", "y": "4.3333333", "height": "30", "width": "30" } } } } } }, "updateProductTag": { "description": "The product tag attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductTagUpdate" } } }, "example": { "data": { "id": "311", "type": "product_tag", "attributes": { "x": "42.5", "y": "10", "height": "25", "width": "25" } } } } } }, "createMarketingIntegration": { "description": "The marketing integration to connect. Only sources that use credentials can be created this way; other sources are connected with [Authenticate a marketing integration](#operation-v2-teams-team-id-marketing-integrations-new-get).", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewMarketingIntegration" } } }, "example": { "data": { "type": "marketing_integration", "attributes": { "source": "bynder", "access_token": "3f1c9a7e-5d2b-4e8a-9c61-7b0d2e4f8a13|Zm9vYmFyLWNsaWVudC1zZWNyZXQ", "site": "https://acme.bynder.com" } } } } } }, "createMarketingIntegrationRequests": { "description": "The assets or collections to publish. Send a single resource with `application/vnd.api+json`, or several at once with `application/vnd.api+json; ext=bulk`. If any of them is invalid, nothing is created.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewMarketingIntegrationRequest" } } }, "example": { "data": { "type": "marketing_integration_request", "attributes": { "asset_id": 2750981, "folder_id": "41736560" } } } }, "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewMarketingIntegrationRequest" } } } }, "example": { "data": [ { "type": "marketing_integration_request", "attributes": { "asset_id": 2750981, "folder_id": "41736560" } }, { "type": "marketing_integration_request", "attributes": { "collection_id": 1184, "folder_id": "41736560" } } ] } } } }, "createMix": { "description": "The mix to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewMix" } } }, "example": { "data": { "type": "mix", "attributes": { "name": "Lobby screen", "scenes": [ { "layout": "horizontal", "template": "\"logo feed\"", "areas": { "logo": [ { "type": "image", "duration": 10, "name": "Acme logo", "url": "https://cdn.example.com/mixes/acme-logo.png" } ], "feed": [ { "type": "tint", "duration": 30, "name": "Summer campaign board", "tint_id": 42, "personalization_id": 7 } ] } } ] } } } } } }, "deleteMixes": { "description": "The mixes to delete, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MixBulkDelete" } } } }, "example": { "data": [ { "id": "12", "type": "mix" }, { "id": "13", "type": "mix" } ] } } } }, "updateMix": { "description": "The mix changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MixUpdate" } } }, "example": { "data": { "id": "12", "type": "mix", "attributes": { "name": "Lobby screen (summer)" } } } } } }, "createPersonalization": { "description": "The personalization to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewPersonalization" } } }, "example": { "data": { "type": "personalization", "attributes": { "name": "Homepage wall", "theme": "classic_v3", "type": "embed", "tags": [ "website" ] } } } } } }, "deletePersonalizations": { "description": "The personalizations to delete. IDs the user can't access are ignored.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalizationIdentifier" } } } }, "example": { "data": [ { "id": "301", "type": "personalization" }, { "id": "302", "type": "personalization" } ] } } } }, "updatePersonalizations": { "description": "The personalizations to update. If any personalization is invalid, none are updated.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalizationBulkUpdate" } } } }, "example": { "data": [ { "id": "301", "type": "personalization", "attributes": { "status": "archived" } }, { "id": "302", "type": "personalization", "attributes": { "status": "archived" } } ] } } } }, "updatePersonalization": { "description": "The attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalizationUpdate" } } }, "example": { "data": { "type": "personalization", "attributes": { "name": "Homepage wall", "data": { "draft": { "custom_css": ".tint-post { border-radius: 8px; }" }, "published": { "custom_css": ".tint-post { border-radius: 8px; }" } } } } } } } }, "createReply": { "description": "The reply to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewReply" } } }, "example": { "data": { "type": "reply", "attributes": { "text": "Thank you for the kind review, Jane!", "source": "public_post", "external_id": "custom_public_1741970527000_4f3a2b1c9d8e", "visibility": "active" } } } } } }, "updateReply": { "description": "The reply changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReplyUpdate" } } }, "example": { "data": { "id": "88", "type": "reply", "attributes": { "visibility": "inactive" } } } } } }, "createRightRequest": { "description": "The right request to send.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewRightRequest" } } }, "examples": { "instagramBusiness": { "summary": "Request the rights to a post in a board through an Instagram direct message", "value": { "data": { "type": "right_request", "attributes": { "source": "instagram_business", "external_id": "17895695668004550", "account_id": 56, "subaccount_id": "464297566935356|17841401839964064", "hashtag": "AcmeYes", "right_request_term_id": 12, "template_id": 34 } } } }, "externallySourcedPosts": { "summary": "Request the rights to an Instagram post by URL with a custom template", "value": { "data": { "type": "right_request", "attributes": { "source": "externally_sourced_posts", "external_id": "https://www.instagram.com/p/C4xYz12AbCd/", "account_id": 56, "subaccount_id": "464297566935356|17841401839964064", "hashtag": "AcmeYes", "right_request_term_id": 12, "tint_id": 42, "template": "We love this post! If you agree to let Acme Inc. share it, reply {{approval_keyword}}. Terms: {{terms.url}}" } } } } } } } }, "createRightRequestTerm": { "description": "The right request term to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewRightRequestTerm" } } }, "examples": { "text": { "summary": "Terms written in Markdown", "value": { "data": { "type": "right_request_term", "attributes": { "name": "Standard content license", "title": "Acme Inc. Content License Agreement", "logo_url": "https://cdn.example.com/acme/logo.png", "text": "# Content License Agreement\n\nBy replying with the approval hashtag, you grant Acme Inc. a non-exclusive, royalty-free, worldwide\nlicense to use, reproduce, and display your post and its content on its websites, social media\naccounts, and marketing materials. You confirm that you own the content and that it doesn't infringe\non anyone's rights." } } } }, "document": { "summary": "Terms provided as an uploaded document", "value": { "data": { "type": "right_request_term", "attributes": { "name": "Legal-approved license (PDF)", "document": "eyJfcmFpbHMiOnsiZGF0YSI6NDIsInB1ciI6ImJsb2JfaWQifX0=--9f8e7d6c5b4a39281706f5e4d3c2b1a098765432" } } } } } } } }, "createRightRequestTemplate": { "description": "The right request template to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewRightRequestTemplate" } } }, "example": { "data": { "type": "right_request_template", "attributes": { "name": "Instagram repost", "hashtag": "AcmeYes", "template": "Such a great shot! We would love to share this picture on our Instagram page. {{username}} if you agree, please reply {{approval_keyword}} and review our terms at {{terms.url}}" } } } } } }, "updateRightRequestTemplate": { "description": "The right request template changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RightRequestTemplateUpdate" } } }, "example": { "data": { "id": "34", "type": "right_request_template", "attributes": { "hashtag": "AcmeSaysYes" } } } } } }, "createTeam": { "description": "The team to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewTeam" } } }, "example": { "data": { "type": "team", "attributes": { "name": "Acme Inc.", "plan": "tint_starter", "billing_platform_type": "chargify", "billing_platform_token": "tok_9s8d7f6g5h4j3k2l" } } } } } }, "updateTeam": { "description": "The attributes of the team to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamUpdate" } } }, "example": { "data": { "id": "1", "type": "team", "attributes": { "name": "Acme Inc.", "image_url": "https://cdn.example.com/logos/acme.png", "shared_tags": true } } } } } }, "createDomain": { "description": "The domain to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewDomain" } } }, "example": { "data": { "type": "domain", "attributes": { "name": "stories.example.com" } } } } } }, "updateDomain": { "description": "The attributes to update.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DomainUpdate" } } }, "example": { "data": { "type": "domain", "id": "42", "attributes": { "default_experience_id": 318 } } } } } }, "createEmailTemplate": { "description": "The email template to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewEmailTemplate" } } }, "example": { "data": { "type": "email_templates", "attributes": { "name": "Review reply", "type": "review_reply", "locales": { "en": { "from": { "name": "Acme Inc.", "email": "reviews@example.com" }, "subject": "Thanks for your review, {{ post.author.name }}", "body": "

Hi {{ post.author.name }},

\n

Thanks for reviewing us. Here's our reply:

\n
{{ reply.text }}
\n

The {{ team.name }} team

" } } } } } } } }, "deleteEmailTemplates": { "description": "The email templates to delete.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplateBulkDelete" } } } }, "example": { "data": [ { "type": "email_templates", "id": "15" }, { "type": "email_templates", "id": "16" } ] } } } }, "updateEmailTemplate": { "description": "The attributes to update.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplateUpdate" } } }, "example": { "data": { "type": "email_templates", "id": "15", "attributes": { "name": "Post-purchase review request (v2)" } } } } } }, "createFont": { "description": "The font to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewFont" } } }, "example": { "data": { "type": "font", "attributes": { "name": "Quicksand", "upload_id": "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTUsInB1ciI6ImJsb2JfaWQifX0=--6b1f0e3c2d9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c" } } } } } }, "createFontUpload": { "description": "The file to upload.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewUpload" } } }, "example": { "data": { "type": "upload", "attributes": { "filename": "quicksand-regular.woff2", "content_type": "font/woff2", "byte_size": 38416, "checksum": "1B2M2Y8AsgTpgAmY7PhCfg==" } } } } } }, "createTint": { "description": "The board to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewTint" } } }, "example": { "data": { "type": "tint", "attributes": { "name": "Acme Summer Campaign", "private": false, "tags": [ "featured", "follow up" ], "auto_moderation_rules": [ { "conditions": { "text": [ "spam" ] }, "changes": { "status": "private" } } ] } } } } } }, "deleteTints": { "description": "The boards to delete, each identified by its `id`. Boards you don't have access to are ignored.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TintBulkDelete" } } } }, "example": { "data": [ { "id": "42", "type": "tint" }, { "id": "43", "type": "tint" } ] } } } }, "updateTints": { "description": "The boards to update, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TintBulkUpdate" } } } }, "example": { "data": [ { "id": "42", "type": "tint", "attributes": { "status": "inactive" } }, { "id": "43", "type": "tint", "attributes": { "private": true } } ] } } } }, "updateTint": { "description": "The board changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TintUpdate" } } }, "example": { "data": { "id": "42", "type": "tint", "attributes": { "name": "Acme Summer Campaign 2025", "status": "active" } } } } } }, "updateMe": { "description": "The attributes of the authenticated user to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MeUpdate" } } }, "example": { "data": { "type": "user", "attributes": { "first_name": "Jane", "last_name": "Doe", "organization": "Acme Inc." } } } } } }, "createTeamUsers": { "description": "The user to invite, or, with the `ext=bulk` media type, an array of users to invite. When any of the users is invalid, none are invited.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewTeamUser" } } }, "example": { "data": { "type": "user", "attributes": { "email": "john.smith@example.com", "role_id": 3 } } } }, "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewTeamUser" } } } }, "example": { "data": [ { "type": "user", "attributes": { "email": "john.smith@example.com", "role_id": 3 } }, { "type": "user", "attributes": { "email": "maria.garcia@example.com", "role_id": 4, "skip_idp": true } } ] } } } }, "deleteTeamUsers": { "description": "The users to remove from the team.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUserIdentifier" } } } }, "example": { "data": [ { "id": "42", "type": "user" }, { "id": "57", "type": "user" } ] } } } }, "updateTeamUsers": { "description": "The users to update. When any of the users is invalid, none are updated.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUserUpdate" } } } }, "example": { "data": [ { "id": "42", "type": "user", "attributes": { "role_id": 4 } }, { "id": "57", "type": "user", "attributes": { "skip_idp": true } } ] } } } }, "updateTeamUser": { "description": "The membership attributes of the user to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamUserUpdate" } } }, "example": { "data": { "id": "42", "type": "user", "attributes": { "role_id": 4 } } } } } }, "createTeamsUserExportRequest": { "description": "The export request to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewTeamsUserExportRequest" } } }, "example": { "data": { "type": "teams_user_export_request" } } } } }, "createAuthenticationFactor": { "description": "The authentication factor to add to the current user.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewAuthenticationFactor" } } } } } }, "verifyAuthenticationFactor": { "description": "The code used to verify the pending authentication factor.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthenticationFactorForVerify" } } } } } }, "createAuthenticationFactorChallenge": { "description": "Optional. The authentication factor to challenge is taken from the path, so the body can be omitted.", "required": false, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewAuthenticationFactorChallenge" } } } } } }, "createAssets": { "description": "One asset, or several assets using the bulk extension. If any asset is invalid, none are created and a 422 is returned.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NewAsset" } } } } }, "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewAsset" } } } } } }, "deleteAssets": { "description": "The assets to delete. Assets that don't exist or that the user can't access are skipped.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetDelete" } } } } } } }, "updateAssets": { "description": "The assets to update and the attributes to change for each. Assets that don't exist or that the user can't access are skipped.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetBulkUpdate" } } } } } } }, "updateAsset": { "description": "The attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssetUpdate" } } } } } }, "createSocialFeed": { "description": "The social feed to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewSocialFeed" } } }, "example": { "data": { "type": "social_feed", "attributes": { "source": "instagram_business", "type": "hashtags", "tint_id": 42, "account_id": 77, "external_id": "17841400008460056", "search_term": "#acmesummer", "moderated": true } } } } } }, "updateSocialFeeds": { "description": "The social feeds to update, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialFeedBulkUpdate" } } } }, "example": { "data": [ { "id": "311", "type": "social_feed", "attributes": { "status": "inactive" } }, { "id": "312", "type": "social_feed", "attributes": { "status": "inactive" } } ] } } } }, "updateSocialFeed": { "description": "The social feed changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SocialFeedUpdate" } } }, "example": { "data": { "id": "311", "type": "social_feed", "attributes": { "name": "Summer hashtag", "moderated": false } } } } } }, "createExperience": { "description": "The experience to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewExperience" } } }, "example": { "data": { "type": "experience", "attributes": { "type": "sweepstakes", "name": "Summer Sweepstakes 2025", "title": "Win a trip to Hawaii", "slug": "summer-sweepstakes", "domain_id": 3, "cookie_consent": true } } } } } }, "deleteExperiences": { "description": "The experiences to delete. IDs the user can't access are ignored.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceIdentifier" } } } }, "example": { "data": [ { "id": "42", "type": "experience" }, { "id": "43", "type": "experience" } ] } } } }, "updateExperiences": { "description": "The experiences to update. If any experience is invalid, none are updated.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceBulkUpdate" } } } }, "example": { "data": [ { "id": "42", "type": "experience", "attributes": { "status": "archived" } }, { "id": "43", "type": "experience", "attributes": { "status": "archived" } } ] } } } }, "updateExperience": { "description": "The attributes to change. Attributes that are left out are unchanged.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ExperienceUpdate" } } }, "example": { "data": { "type": "experience", "attributes": { "title": "Win a trip to Hawaii", "analytics_type": "google_tag_manager", "analytics_id": "GTM-5XK7Q2P" } } } } } }, "createFormSubmission": { "description": "The form's fields as key/value pairs.", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FormSubmissionFields" }, "example": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FormSubmissionFields" }, "example": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" } } } }, "createFormSubmissionExportRequest": { "description": "The experience and the submissions to export.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewFormSubmissionExportRequest" } } }, "example": { "data": { "type": "form_submission_export_request", "attributes": { "experience_id": 42, "filters": { "created_at": { "$gte": "2025-03-01T00:00:00.000Z", "$lte": "2025-03-31T23:59:59.000Z" } }, "include_files": true } } } } } }, "deletePosts": { "description": "The posts to delete, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostDelete" } } } }, "example": { "data": [ { "id": "9001", "type": "post" }, { "id": "9002", "type": "post" } ] } } } }, "updatePosts": { "description": "The posts to update, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostBulkUpdate" } } } }, "example": { "data": [ { "id": "9001", "type": "post", "attributes": { "status": "public" } }, { "id": "9002", "type": "post", "attributes": { "status": "private", "status_reasons": [ "off_topic" ] } } ] } } } }, "updatePost": { "description": "The post changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PostUpdate" } } }, "example": { "data": { "id": "9001", "type": "post", "attributes": { "status": "public", "highlighted": true, "tags": [ "featured", "follow up" ] } } } } } }, "createTintPost": { "description": "The custom post to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewPost" } } }, "example": { "data": { "type": "post", "attributes": { "text": "Our summer collection just dropped!", "url": "https://example.com/summer", "alternative_text": "A pair of white Acme sneakers on a beach.", "pinned": true, "tags": [ "featured" ], "media": [ "eyJfcmFpbHMiOnsiZGF0YSI6MTIzNDUsInB1ciI6ImJsb2JfaWQifX0=--0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6" ], "author": { "name": "Acme Inc.", "username": "acme", "url": "https://example.com" } } } } } } }, "createPublicTintPost": { "description": "The public post or review to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewPublicPost" } } }, "example": { "data": { "type": "post", "attributes": { "type": "reviews", "title": "Great everyday sneakers", "text": "Super comfortable and true to size. Would buy again!", "rating": 80, "media_url": [ "https://cdn.example.com/uploads/sneakers.jpg" ], "tags": [ "sku:ACME-SNK-001" ], "author": { "name": "Jane Doe", "email": "jane.doe@example.com" } } } } } } }, "createPostsSummary": { "description": "The posts to summarize.", "required": false, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PostsSummaryParameters" }, "example": { "filter": { "rating": { "$gte": 60 }, "tag": "sku:ACME-SNK-001" }, "sort": "-published_at" } } } }, "createPostExportRequest": { "description": "The export to request.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewPostExportRequest" } } }, "example": { "data": { "type": "post_export_request", "attributes": { "tint_id": 42 } } } } } }, "createCollection": { "description": "The collection to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewCollection" } } }, "example": { "data": { "type": "collection", "attributes": { "name": "Summer campaign", "public": false } } } } } }, "deleteCollections": { "description": "The collections to delete, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionBulkDelete" } } } }, "example": { "data": [ { "id": "27", "type": "collection" }, { "id": "28", "type": "collection" } ] } } } }, "updateCollections": { "description": "The collections to update, each identified by its `id`.", "required": true, "content": { "application/vnd.api+json; ext=bulk": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionBulkUpdate" } } } }, "example": { "data": [ { "id": "27", "type": "collection", "attributes": { "status": "archived" } }, { "id": "28", "type": "collection", "attributes": { "status": "archived" } } ] } } } }, "updateCollection": { "description": "The collection changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CollectionUpdate" } } }, "example": { "data": { "id": "27", "type": "collection", "attributes": { "public": true } } } } } }, "createOAuthApplication": { "description": "The OAuth application to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewOAuthApplication" } } } } } }, "updateOAuthApplication": { "description": "The OAuth application attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OAuthApplicationUpdate" } } } } } }, "createWebhook": { "description": "The webhook to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewWebhook" } } }, "example": { "data": { "type": "webhook", "attributes": { "url": "https://hooks.example.com/trueloyal", "description": "Forward new contest entries to our CRM.", "events": [ "form_submission_created" ], "signing_secret": "whsec_8f14e45fceea167a5a36dedd4bea2543", "filter": { "experience_id": "2012" }, "payload_include": [ "object.person" ], "payload_fields": { "form_submission": [ "data", "created_at", "person" ] } } } } } } }, "updateWebhook": { "description": "The webhook changes. Only the attributes you send are changed.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookUpdate" } } }, "example": { "data": { "id": "15", "type": "webhook", "attributes": { "status": "inactive" } } } } } }, "createSavedFilter": { "description": "The saved filter to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewSavedFilter" } } }, "example": { "data": { "type": "saved_filter", "attributes": { "name": "Summer favorites", "filter": { "q": "sneakers", "status": [ "public", "recurring" ], "type": [ "instagram_business", "tiktok" ], "media_type": [ "image" ], "published_at": { "$gte": "2025-06-01T00:00:00.000Z", "$lte": "2025-08-31T23:59:59.000Z" } } } } } } } }, "updateSavedFilter": { "description": "The saved filter changes.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedFilterUpdate" } } }, "example": { "data": { "id": "15", "type": "saved_filter", "attributes": { "name": "Summer favorites (images)", "filter": { "q": "sneakers", "media_type": [ "image" ] } } } } } } }, "createCta": { "description": "The CTA to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewCta" } } } } } }, "updateCta": { "description": "The attributes to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CtaUpdate" } } } } } }, "createCtaAssociation": { "description": "The CTA to apply and the post or saved filter to apply it to.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewCtaAssociation" } } } } } }, "createRole": { "description": "The role to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewRole" } } }, "example": { "data": { "type": "role", "attributes": { "name": "Content Moderator", "description": "Moderates posts and manages rights requests for the brand boards.", "permissions": [ "moderate_tint", "modify_tint", "assets_read" ], "tint_ids": [ 12, 15 ] } } } } } }, "updateRole": { "description": "The attributes of the role to change.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RoleUpdate" } } }, "example": { "data": { "id": "3", "type": "role", "attributes": { "permissions": [ "moderate_tint", "modify_tint", "assets_read", "replies_r" ], "tint_ids": { "+": [ 18 ], "-": [ 12 ] } } } } } } }, "createPrivacyRequest": { "description": "The privacy request to create.", "required": true, "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewPrivacyRequest" } } }, "example": { "data": { "type": "privacy_request", "attributes": { "type": "erasure", "identifier_type": "id", "identifier": "65f3a1c2e4b0a91d2c7e8f10" } } } } } } }, "parameters": { "teamId": { "name": "team_id", "in": "path", "required": true, "description": "The ID of the team.", "schema": { "type": "integer", "example": 1 } }, "accountRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "social_feeds", "subaccounts" ] } } }, "accountFilter": { "name": "filter", "in": "query", "description": "Filters the list of accounts. All filters are combined with AND.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Only returns accounts whose name or username contains this text (case-insensitive).", "example": "acme" }, "type": { "type": "string", "description": "A comma-separated list of account types (see the `type` attribute for possible values). Only returns accounts of these types.", "example": "facebook,instagram_business" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`ok`, `expired`, `pending`). Only returns accounts with one of these statuses.", "example": "expired" }, "capability": { "type": "string", "description": "A comma-separated list of capabilities (`ingest`, `compose`, `syndicate`, `captcha`, `products`, `email`, `events`, `profile`). Only returns accounts whose type has one of these capabilities.", "example": "compose" } } } }, "accountSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "name,-created_at" } }, "pagination": { "name": "page", "in": "query", "description": "Offset pagination. Use `page[size]` to set the number of items per page and `page[number]` to select a page. The response's `links` object contains ready-to-use URLs for the next and previous pages.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "size": { "type": "integer", "description": "The number of items per page.", "default": 25, "minimum": 1 }, "number": { "type": "integer", "description": "The page number to return, starting at 1.", "default": 1, "minimum": 1 } } } }, "accountId": { "name": "account_id", "in": "path", "required": true, "description": "The ID of the account.", "schema": { "type": "integer", "example": 4821 } }, "accountAuthorizationOrigin": { "name": "origin", "in": "query", "description": "When specified, once the user completes the authorization flow, the callback page posts a message to `window.opener` using `window.postMessage` with this value as the target origin. The message is a JSON string of the form `{\"type\": \"account_new\", \"data\": , \"status\": }` (`account_edit` when reauthenticating), where the response body is the account (or errors).", "schema": { "type": "string", "format": "uri", "example": "https://app.example.com" } }, "accountAuthorizationRedirectUri": { "name": "redirect_uri", "in": "query", "description": "When specified, once the user completes the authorization flow, the user is redirected to this URI with a `data` query parameter containing the same JSON message as for `origin`, encoded using Base64. Takes precedence over `origin`.", "schema": { "type": "string", "format": "uri", "example": "https://app.example.com/integrations/callback" } }, "subaccountFilter": { "name": "filter", "in": "query", "description": "Filters the list of subaccounts. All filters are combined with AND.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "A comma-separated list of subaccount IDs (the IDs at the source).", "example": "17841401839964064,104729381726354" }, "q": { "type": "string", "description": "Only returns subaccounts whose name or username contains this text (case-insensitive).", "example": "acme" }, "type": { "type": "string", "description": "A comma-separated list of subaccount types (`profile`, `organization`, `page`, `group`, `public_channel`, `room`, `blog`, `channel`, `instagram`, `board`, `campaign`). For backward compatibility, when `filter` is used without `filter[type]` on a `facebook` account, only `page` subaccounts are returned.", "example": "page" }, "capability": { "type": "string", "description": "A comma-separated list of capabilities (`ingest`, `compose`). Only returns subaccounts that have all of them.", "example": "compose" } } } }, "productFeedId": { "name": "product_feed_id", "in": "path", "required": true, "description": "The ID of the product feed.", "schema": { "type": "integer", "example": 12 } }, "productFeedRefreshRequestId": { "name": "product_feed_refresh_request_id", "in": "path", "required": true, "description": "The ID of the product feed refresh request, as returned when the refresh was requested (an opaque string).", "schema": { "type": "string", "example": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InByb2R1Y3RfaW1wb3J0X3JlcXVlc3R8NDIifQ.c2lnbmF0dXJl" } }, "productFilter": { "name": "filter", "in": "query", "description": "Filters. List filters take comma-separated values and match any of them. Only products of the product feeds you have access to are returned.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "A full-text search on the name, description, SKU, family and brand.", "example": "runner" }, "id": { "type": "string", "description": "A comma-separated list of product IDs.", "example": "1234,1235" }, "sku": { "type": "string", "description": "A comma-separated list of SKUs.", "example": "ACME-RUN2-BLK-42,ACME-RUN2-WHT-42" }, "product_feed_ids": { "type": "string", "description": "A comma-separated list of product feed IDs.", "example": "12,13" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `archived`). Defaults to `active`, so archived products are only returned when requested.", "default": "active", "example": "active,archived" }, "availability": { "type": "string", "description": "A comma-separated list of availabilities (`in_stock`, `out_of_stock`, `preorder`, `available_for_order`, `discontinued`, `pending`).", "example": "in_stock,preorder" }, "source": { "type": "string", "description": "A comma-separated list of product feed sources (for example, `shopify` or `manual`). See the product feed `source` attribute for the possible values.", "example": "shopify,manual" }, "categories": { "type": "string", "description": "A comma-separated list of categories.", "example": "Footwear,Running" }, "brand": { "type": "string", "description": "A comma-separated list of brands.", "example": "Acme" }, "family": { "type": "string", "description": "A comma-separated list of product families.", "example": "Acme Runner 2" }, "created_at": { "type": "object", "description": "Only returns products created in this time range.", "properties": { "$gte": { "type": "string", "format": "date-time", "description": "Only returns products created at or after this time.", "example": "2025-01-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Only returns products created before this time.", "example": "2025-04-01T00:00:00.000Z" } } } } } }, "productSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by (for example, `name`, `price`, `created_at` or `id`). Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "-created_at" } }, "productRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "product_feed" ] }, "example": [ "product_feed" ] } }, "productId": { "name": "product_id", "in": "path", "required": true, "description": "The ID of the product.", "schema": { "type": "integer", "example": 1234 } }, "scheduledContentRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "account", "campaign", "media", "subaccount", "team" ] }, "example": [ "account", "media" ] } }, "scheduledContentFilter": { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "description": "Filters that accept multiple values take a comma-separated list.", "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns contents whose text contains this value (case-insensitive).", "example": "spring collection" }, "mime_type": { "type": "array", "description": "Returns contents with at least one file of these kinds. `text` matches contents without any file.", "items": { "type": "string", "enum": [ "text", "image", "video" ] }, "example": [ "image", "video" ] }, "carousel": { "type": "boolean", "description": "When `true`, only contents with more than one file are returned; when `false`, only contents with at most one file.", "example": true }, "account_id": { "type": "array", "description": "Returns contents published with one of these account IDs. Combined with `subaccount_id` using OR.", "items": { "type": "string" }, "example": [ "1375" ] }, "subaccount_id": { "type": "array", "description": "Returns contents published to one of these subaccount IDs. Combined with `account_id` using OR.", "items": { "type": "string" }, "example": [ "17841400008460056" ] }, "tags": { "type": "array", "description": "Returns contents that have at least one of these tags (case-insensitive).", "items": { "type": "string" }, "example": [ "spring-launch" ] }, "status": { "type": "array", "description": "Returns contents with one of these statuses.", "items": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "example": [ "pending", "failed" ] }, "published_at": { "type": "object", "description": "Filters by scheduled publication time. When omitted, defaults to `{\"$gte\": <14 days ago>}`, so older contents are only returned when this filter is set.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "Published strictly after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "Published at or after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Published strictly before this time.", "example": "2025-04-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Published at or before this time.", "example": "2025-04-01T00:00:00.000Z" } } }, "created_at": { "type": "object", "description": "Filters by creation time.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "Created strictly after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "Created at or after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Created strictly before this time.", "example": "2025-04-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Created at or before this time.", "example": "2025-04-01T00:00:00.000Z" } } } } } }, "scheduledContentId": { "name": "scheduled_content_id", "in": "path", "required": true, "description": "The ID of the scheduled content.", "schema": { "type": "integer", "example": 4821 } }, "campaignFilter": { "name": "filter", "in": "query", "description": "Filters the list of campaigns. All filters are combined with AND. Date filters accept ISO 8601 date-times and the operators `$eq`, `$gt`, `$gte`, `$lt`, and `$lte`, for example `filter[starts_at][$gte]=2025-06-01T00:00:00Z`.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Only returns campaigns whose name contains this text (case-insensitive).", "example": "summer" }, "starts_at": { "$ref": "#/components/schemas/campaignDateFilter" }, "ends_at": { "$ref": "#/components/schemas/campaignDateFilter" } } } }, "campaignSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by (for example `name`, `starts_at`, `ends_at`, `created_at`). Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "starts_at" } }, "campaignId": { "name": "campaign_id", "in": "path", "required": true, "description": "The ID of the campaign.", "schema": { "type": "integer", "example": 57 } }, "productFeedFilter": { "name": "filter", "in": "query", "description": "Filters. List filters take comma-separated values and match any of them.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Only returns product feeds whose name contains this text (case-insensitive).", "example": "spring" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `archived`, `error`).", "example": "active,error" }, "source": { "type": "string", "description": "A comma-separated list of sources. See the product feed `source` attribute for the possible values.", "example": "shopify,csv" } } } }, "productFeedSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by (for example, `name`, `created_at` or `id`). Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "name" } }, "productFeedRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "catalog", "product_account", "products" ] }, "example": [ "product_account" ] } }, "productAccountFilter": { "name": "filter", "in": "query", "description": "Filters. List filters take comma-separated values and match any of them.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "A comma-separated list of statuses (`ok`, `expired`, `pending`).", "example": "ok,expired" }, "type": { "type": "string", "description": "A comma-separated list of product account types. See the `type` attribute for the possible values.", "example": "shopify,woocommerce" } } } }, "productAccountRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "catalogs", "product_feeds" ] }, "example": [ "catalogs" ] } }, "productAccountId": { "name": "product_account_id", "in": "path", "required": true, "description": "The ID of the product account.", "schema": { "type": "integer", "example": 7 } }, "productAccountOrigin": { "name": "origin", "in": "query", "description": "When specified, once the user completes the authorization flow, the response body is posted to the window that opened the authorization page using `window.postMessage`, with this value as the target origin.", "schema": { "type": "string", "example": "https://app.example.com" } }, "productAccountRedirectUri": { "name": "redirect_uri", "in": "query", "description": "When specified, once the user completes the authorization flow, the user is redirected to this URI with a `data` query parameter containing the response encoded using Base64.", "schema": { "type": "string", "format": "uri", "example": "https://app.example.com/integrations/callback" } }, "tintId": { "name": "tint_id", "in": "path", "required": true, "description": "The ID of the board.", "schema": { "type": "integer", "example": 42 } }, "productTagRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "product" ] }, "example": [ "product" ] } }, "productTagId": { "name": "product_tag_id", "in": "path", "required": true, "description": "The ID of the product tag.", "schema": { "type": "integer", "example": 311 } }, "marketingIntegrationId": { "name": "marketing_integration_id", "in": "path", "required": true, "description": "The ID of the marketing integration.", "schema": { "type": "integer", "example": 318 } }, "marketingIntegrationAuthorizationOrigin": { "name": "origin", "in": "query", "description": "When specified, once the user completes the authorization flow, the callback page posts a message to `window.opener` using `window.postMessage` with this value as the target origin. The message is a JSON string of the form `{\"type\": \"marketing_integration_new\", \"data\": , \"status\": }` (`marketing_integration_edit` when reauthenticating), where the response body is the marketing integration (or errors).", "schema": { "type": "string", "format": "uri", "example": "https://app.example.com" } }, "marketingIntegrationAuthorizationRedirectUri": { "name": "redirect_uri", "in": "query", "description": "When specified, once the user completes the authorization flow, the user is redirected to this URI with a `data` query parameter containing the same JSON message as for `origin`, encoded using Base64. Takes precedence over `origin`.", "schema": { "type": "string", "format": "uri", "example": "https://app.example.com/integrations/callback" } }, "mixId": { "name": "mix_id", "in": "path", "required": true, "description": "The ID of the mix.", "schema": { "type": "integer", "example": 12 } }, "mixFilter": { "name": "filter", "in": "query", "description": "Filters the mixes.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns the mixes whose name contains this text (case-insensitive).", "example": "lobby" } } } }, "personalizationFilter": { "name": "filter", "in": "query", "description": "Filters the list of personalizations.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns personalizations whose name contains this text (case-insensitive).", "example": "homepage" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `archived`).", "example": "active" }, "type": { "type": "string", "description": "A comma-separated list of personalization types.", "example": "embed,screen" }, "tags": { "type": "string", "description": "A comma-separated list of tags. Only personalizations that have all of them are returned (case-insensitive).", "example": "website,spring" } } } }, "personalizationSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "name" } }, "personalizationId": { "name": "personalization_id", "in": "path", "required": true, "description": "The ID of the personalization.", "schema": { "type": "integer", "example": 301 } }, "replyRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "user" ] } }, "example": [ "user" ] }, "replyId": { "name": "reply_id", "in": "path", "required": true, "description": "The ID of the reply.", "schema": { "type": "integer", "example": 88 } }, "rightRequestRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. Each relationship is only available when the access token has the matching read scope (`posts:read`, `assets:read`, or `right_request_templates:read`).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "assets", "posts", "template" ] }, "example": [ "posts" ] } }, "rightRequestSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at", "approved_at", "-approved_at", "status", "-status" ] }, "default": [ "-id" ], "example": [ "-approved_at" ] } }, "rightRequestFilter": { "name": "filter", "in": "query", "style": "deepObject", "description": "Filters the right requests. List filters accept a comma-separated list of values and match any of them; time range filters accept one or more operators.", "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "A comma-separated list of statuses: `approved`, `declined`, `deleted`, `error`, `expired`, `missing`, `pending`, `requested`, `soft_approved`, or `token_error`.", "example": "requested,approved" }, "source": { "type": "string", "description": "A comma-separated list of sources: `creator_iq`, `externally_sourced_posts`, `facebook`, `form_submission`, `instagram`, `instagram_business`, `public_post`, `tiktok_business`, or `twitter`.", "example": "instagram_business" }, "user_id": { "type": "string", "description": "A comma-separated list of IDs of the users who created the right requests.", "example": "7,8" }, "account_id": { "type": "string", "description": "A comma-separated list of IDs of the accounts used to send the right requests.", "example": "56" }, "subaccount_id": { "type": "string", "description": "A comma-separated list of IDs of the subaccounts used to send the right requests.", "example": "464297566935356|17841401839964064" }, "created_at": { "$ref": "#/components/schemas/rightRequestTimeRange" }, "approved_at": { "$ref": "#/components/schemas/rightRequestTimeRange" } } }, "example": { "status": "requested,approved", "created_at": { "$gte": "2025-03-01T00:00:00.000Z" } } }, "rightRequestId": { "name": "right_request_id", "in": "path", "required": true, "description": "The ID of the right request.", "schema": { "type": "integer", "example": 1234 } }, "rightRequestMeasureName": { "name": "measure_name", "in": "path", "required": true, "description": "The event to count, either right requests `created` or right requests `approved`.", "schema": { "type": "string", "enum": [ "created", "approved" ], "example": "approved" } }, "rightRequestsMetricsFilter": { "name": "filter", "in": "query", "style": "deepObject", "description": "Filters the metrics. List filters accept a comma-separated list of values and match any of them. Only right requests sent from accounts connected by the current user are counted.", "schema": { "type": "object", "properties": { "time": { "type": "object", "description": "The time range to count events in. Defaults to the last 14 days (`$gte` 14 days ago).", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "Only count events after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "Only count events at or after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Only count events before this time.", "example": "2025-04-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Only count events at or before this time.", "example": "2025-03-31T23:59:59.000Z" } } }, "source": { "type": "string", "description": "A comma-separated list of sources: `creator_iq`, `externally_sourced_posts`, `facebook`, `form_submission`, `instagram`, `instagram_business`, `public_post`, `tiktok_business`, or `twitter`.", "example": "instagram_business,tiktok_business" }, "user_id": { "type": "string", "description": "A comma-separated list of IDs of the users who created the right requests.", "example": "7" }, "tint_id": { "type": "string", "description": "A comma-separated list of board IDs.", "example": "42" }, "account_id": { "type": "string", "description": "A comma-separated list of IDs of the accounts used to send the right requests.", "example": "56" }, "subaccount_id": { "type": "string", "description": "A comma-separated list of IDs of the subaccounts used to send the right requests.", "example": "464297566935356|17841401839964064" } } }, "example": { "time": { "$gte": "2025-03-01T00:00:00.000Z", "$lt": "2025-04-01T00:00:00.000Z" }, "source": "instagram_business" } }, "rightRequestsMetricsGroup": { "name": "group", "in": "query", "description": "A comma-separated list of dimensions to group the metrics by. `time` groups by day. Time buckets are returned newest first.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "time", "time.minute", "time.hour", "time.day", "time.week", "time.month", "time.quarter", "time.year", "time.day_of_week", "time.hour_of_day", "source", "user_id", "account_id", "subaccount_id" ] }, "example": [ "time.day", "source" ] } }, "rightRequestTermRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. `tint` is only available when the access token has the `tints:read` scope.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "tint" ] }, "example": [ "tint" ] } }, "rightRequestTermSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at" ] }, "default": [ "-id" ], "example": [ "name" ] } }, "rightRequestTermFilter": { "name": "filter", "in": "query", "style": "deepObject", "description": "Filters the right request terms.", "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Only return terms whose name, title, or text contains this text (case-insensitive).", "example": "license" } } } }, "rightRequestTermId": { "name": "right_request_term_id", "in": "path", "required": true, "description": "The ID of the right request term.", "schema": { "type": "integer", "example": 12 } }, "rightRequestTemplateRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. `tint` is only available when the access token has the `tints:read` scope.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "tint" ] }, "example": [ "tint" ] } }, "rightRequestTemplateSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "default": [ "-id" ], "example": [ "-updated_at" ] } }, "rightRequestTemplateFilter": { "name": "filter", "in": "query", "style": "deepObject", "description": "Filters the right request templates.", "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Only return templates whose name or template text contains this text (case-insensitive).", "example": "repost" } } } }, "rightRequestTemplateId": { "name": "right_request_template_id", "in": "path", "required": true, "description": "The ID of the right request template.", "schema": { "type": "integer", "example": 34 } }, "teamRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "agent", "assets", "forms", "mixes", "personalizations", "plan", "role", "social_feeds", "tints" ] } }, "example": [ "plan", "role" ] }, "teamFilter": { "name": "filter", "in": "query", "description": "Filters the teams.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns the teams whose name contains the value (case-insensitive).", "example": "acme" } } } }, "teamSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at" ] }, "default": [ "-id" ] }, "example": [ "name" ] }, "domainInclude": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "default_experience" ] } }, "example": [ "default_experience" ] }, "domainId": { "name": "domain_id", "in": "path", "required": true, "description": "The ID of the domain.", "schema": { "type": "integer" }, "example": 42 }, "emailTemplateFilter": { "name": "filter", "in": "query", "description": "Filters the email templates.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns templates whose name or content (sender, subject, or body in any locale) contains this text, case-insensitively.", "example": "review" }, "type": { "type": "string", "description": "A comma-separated list of template types to return. Possible values: `review_solicitation`, `review_solicitation_reminder`, `form_submission`, `influencer`, `review_reply`.", "example": "review_solicitation,review_solicitation_reminder" } } } }, "emailTemplateSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "type", "-type", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "default": [ "-id" ] }, "example": [ "name" ] }, "emailTemplateInclude": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "team" ] } }, "example": [ "team" ] }, "emailTemplateId": { "name": "email_template_id", "in": "path", "required": true, "description": "The ID of the email template.", "schema": { "type": "integer" }, "example": 15 }, "fontSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "default": [ "-id" ] }, "example": [ "name" ] }, "fontId": { "name": "font_id", "in": "path", "required": true, "description": "The ID of the font.", "schema": { "type": "integer" }, "example": 7 }, "fontStylesheetTeamId": { "name": "team_id", "in": "path", "required": true, "description": "The ID of the team. Without an access token, it can also be the name of one of the team's custom domains, so experiences can load fonts from their own domain.", "schema": { "oneOf": [ { "type": "integer", "title": "ID", "example": 1 }, { "type": "string", "title": "Domain name", "format": "hostname", "example": "stories.example.com" } ] } }, "fontIds": { "name": "font_ids", "in": "path", "required": true, "description": "A comma-separated list of font IDs, followed by the `.css` extension in the path (for example `7,9.css`).", "style": "simple", "explode": false, "schema": { "type": "array", "minItems": 1, "items": { "type": "integer" } }, "example": [ 7, 9 ] }, "tintRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "default_personalization", "personalizations", "posts", "recently_active_embed_locations", "rights_terms", "saved_filters", "social_feeds" ] } }, "example": [ "social_feeds" ] }, "tintFilter": { "name": "filter", "in": "query", "description": "Filters the boards.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns the boards whose name or slug contains this text (case-insensitive).", "example": "summer" }, "private": { "type": "string", "description": "Returns the boards whose `private` attribute matches. Use `true` or `false`; a comma-separated list returns both.", "example": "false" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `inactive`) to return.", "example": "active" } } } }, "tintSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "slug", "-slug", "created_at", "-created_at", "last_moderated_at", "-last_moderated_at" ] }, "default": [ "-id" ] }, "example": [ "-last_moderated_at" ] }, "tintEngagementType": { "name": "embed_engagement_type", "in": "path", "required": true, "description": "The board engagement event type to count. Multiple types can be combined in a single path segment, separated by a pipe (`|`), for example `embed_loaded|embed_viewed`. Unknown types are ignored.", "schema": { "type": "string", "enum": [ "embed_post_modal_opened", "embed_post_external_link_opened", "embed_post_cta_clicked", "embed_post_shared", "embed_post_modal_navigate_right", "embed_post_modal_navigate_left", "embed_paginated", "embed_post_author_clicked", "embed_post_product_clicked", "embed_loaded", "embed_viewed" ], "example": "embed_viewed" } }, "tintEngagementMetricsFilter": { "name": "filter", "in": "query", "description": "Filters the engagement events that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tint_id": { "type": "string", "description": "A comma-separated list of board IDs. Defaults to all the boards of the team.", "example": "42,43" }, "personalization_ids": { "type": "string", "description": "A comma-separated list of personalization IDs.", "example": "7" }, "embed_url": { "type": "string", "description": "Returns the events of web pages whose URL starts with this value (case-sensitive).", "example": "https://example.com/summer" }, "time": { "type": "object", "description": "The time range of the events. Defaults to the last 14 days. The UTC offset of the last value is used as the time zone for time-based grouping.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "Only count events after this time.", "example": "2025-03-01T00:00:00-05:00" }, "$gte": { "type": "string", "format": "date-time", "description": "Only count events at or after this time.", "example": "2025-03-01T00:00:00-05:00" }, "$lt": { "type": "string", "format": "date-time", "description": "Only count events before this time.", "example": "2025-03-15T00:00:00-05:00" }, "$lte": { "type": "string", "format": "date-time", "description": "Only count events at or before this time.", "example": "2025-03-14T23:59:59-05:00" } } } } } }, "tintEngagementMetricsGroup": { "name": "group", "in": "query", "description": "A comma-separated list of dimensions to group the metrics by. Time dimensions (`time.*`) return a `time` dimension truncated to the unit (`time.day_of_week` and `time.hour_of_day` return the day or hour number instead).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "time.hour", "time.day", "time.week", "time.month", "time.quarter", "time.year", "time.day_of_week", "time.hour_of_day", "tint_id", "post_id", "personalization_type", "theme", "device_category", "media_type", "embed_url", "remote_ip_country" ] } }, "example": [ "time.day", "tint_id" ] }, "tintEngagementMetricsAggregation": { "name": "aggregation", "in": "query", "description": "How to count events: `count` sums all events, `count_unique` counts unique visitors (approximately).", "schema": { "type": "string", "default": "count", "enum": [ "count", "count_unique" ], "example": "count" } }, "tintSlug": { "name": "tint_slug", "in": "path", "required": true, "description": "The slug of the board, the unique part of its public URL.", "schema": { "type": "string", "example": "acme-summer-campaign" } }, "meInclude": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "authentication_factors", "teams", "teams.role" ] } }, "example": [ "authentication_factors", "teams" ] }, "teamUserRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "role" ] } }, "example": [ "role" ] }, "teamUserFilter": { "name": "filter", "in": "query", "description": "Filters the team's users. `email`, `first_name` and `last_name` are exact matches and are combined; the other filters are combined with them.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Returns the user with exactly this email address.", "example": "jane.doe@example.com" }, "first_name": { "type": "string", "description": "Returns the users with exactly this first name.", "example": "Jane" }, "last_name": { "type": "string", "description": "Returns the users with exactly this last name.", "example": "Doe" }, "skip_idp": { "type": "boolean", "description": "Returns the users whose `skip_idp` attribute has this value.", "example": true }, "q": { "type": "string", "description": "Returns the users whose email address is exactly the value, or whose first or last name contains the value (case-insensitive).", "example": "jane" }, "role_id": { "type": "string", "description": "A comma-separated list of role IDs. Returns the users assigned one of these roles.", "example": "3,4" } } } }, "teamUserSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order. `id` sorts by the order in which users were added to the team.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at", "skip_idp", "-skip_idp" ] }, "default": [ "-id" ] }, "example": [ "-created_at" ] }, "userId": { "name": "user_id", "in": "path", "required": true, "description": "The ID of the user.", "schema": { "type": "integer", "example": 42 } }, "teamsUserExportRequestId": { "name": "teams_user_export_request_id", "in": "path", "required": true, "description": "The ID of the export request, as returned when it was created.", "schema": { "type": "string", "pattern": "^[\\w\\-.]+$", "example": "OxZZQtuh5sXIKA" } }, "authenticationFactorId": { "name": "authentication_factor_id", "in": "path", "required": true, "description": "The ID of an authentication factor of the current user.", "schema": { "type": "integer", "example": 42 } }, "assetRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "collections", "imported_from", "media", "team" ] }, "example": [ "collections" ] } }, "assetSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order.", "explode": false, "schema": { "type": "array", "default": [ "-id" ], "items": { "type": "string", "enum": [ "id", "-id", "created_at", "-created_at", "updated_at", "-updated_at", "size", "-size" ] }, "example": [ "-created_at" ] } }, "assetFilter": { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "description": "Filters that accept multiple values take a comma-separated list.", "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Full-text search over the name (prefix match), description, alternative text and text detected in the image.", "example": "beach picnic" }, "id": { "type": "array", "description": "Only returns assets with one of these IDs.", "items": { "type": "integer" }, "example": [ 190245, 190246 ] }, "collections": { "type": "array", "description": "Only returns assets in one of these collections. Collections the user doesn't have access to are ignored. When omitted, assets in any collection the user has access to, and assets without a collection, are returned.", "items": { "type": "integer" }, "example": [ 48 ] }, "status": { "type": "array", "description": "Only returns assets with one of these statuses.", "default": [ "active" ], "items": { "type": "string", "enum": [ "active", "archived" ] }, "example": [ "active" ] }, "source": { "type": "array", "description": "Only returns assets from one of these sources.", "items": { "$ref": "#/components/schemas/AssetSource" }, "example": [ "branded", "instagram_business" ] }, "mime_type": { "type": "array", "description": "Only returns images, videos, or both.", "items": { "type": "string", "enum": [ "image", "video" ] }, "example": [ "image" ] }, "objects": { "type": "array", "description": "Only returns assets in which one of these objects was detected.", "items": { "type": "string" }, "example": [ "beach" ] }, "emotions": { "type": "array", "description": "Only returns assets in which one of these emotions was detected.", "items": { "type": "string" }, "example": [ "happy" ] }, "tags": { "description": "Either a list of tags (returns assets with at least one of them), or `true`/`false` to return only assets with or without tags.", "oneOf": [ { "title": "List of tags", "type": "array", "items": { "type": "string" } }, { "title": "Has tags", "type": "boolean" } ], "example": [ "spring-launch" ] }, "person_id": { "type": "array", "description": "Only returns assets linked to one of these loyalty members.", "items": { "type": "string" }, "example": [ "65f3a1c2e4b0a91d2c7e8f10" ] }, "sfw": { "type": "boolean", "description": "Only returns assets that are (`true`) or aren't (`false`) safe for work.", "example": true }, "created_at": { "type": "object", "description": "Filters by creation time.", "properties": { "$gte": { "type": "string", "format": "date-time", "description": "Created at or after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Created strictly before this time.", "example": "2025-04-01T00:00:00.000Z" } } } } } }, "assetId": { "name": "asset_id", "in": "path", "required": true, "description": "The ID of the asset.", "schema": { "type": "integer", "example": 190245 } }, "assetStatusFilter": { "name": "filter", "in": "query", "style": "deepObject", "explode": true, "description": "Filters that accept multiple values take a comma-separated list.", "schema": { "type": "object", "properties": { "status": { "type": "array", "description": "Only counts assets with one of these statuses.", "default": [ "active" ], "items": { "type": "string", "enum": [ "active", "archived" ] }, "example": [ "active" ] } } } }, "socialFeedFilter": { "name": "filter", "in": "query", "description": "Filters the social feeds.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tint_id": { "type": "string", "description": "A comma-separated list of board IDs.", "example": "42" }, "source": { "type": "string", "description": "A comma-separated list of sources, for example `instagram_business,tiktok`.", "example": "instagram_business" }, "type": { "type": "string", "description": "A social feed kind, for example `reviews`, `influencer` or `social_listening`. Only applied when `source` is also specified, and every source in `source` must support the kind.", "example": "hashtags" }, "status": { "type": "string", "description": "A comma-separated list of statuses: `active`, `inactive`, `error`, `queued`, `needs_stream`, `streamed`, `token_requested`, `deprecated`, `unknown`.", "example": "active,error" } } } }, "socialFeedRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "account", "form", "right_request_term", "tint" ] } }, "example": [ "tint" ] }, "socialFeedId": { "name": "social_feed_id", "in": "path", "required": true, "description": "The ID of the social feed.", "schema": { "type": "integer", "example": 311 } }, "socialFeedMetricsGroup": { "name": "group", "in": "query", "description": "The period to group the metrics by. `created_at.millennium` returns a single total.", "schema": { "type": "string", "default": "created_at.millennium", "enum": [ "created_at.hour", "created_at.day", "created_at.week", "created_at.month", "created_at.quarter", "created_at.year", "created_at.millennium" ], "example": "created_at.day" } }, "socialFeedMetricsFilter": { "name": "filter", "in": "query", "description": "Filters the periods that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "created_at": { "type": "object", "description": "The time range.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "After this time.", "example": "2025-03-01T00:00:00Z" }, "$gte": { "type": "string", "format": "date-time", "description": "At or after this time.", "example": "2025-03-01T00:00:00Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Before this time.", "example": "2025-04-01T00:00:00Z" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before this time.", "example": "2025-03-31T23:59:59Z" } } } } } }, "experienceRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. Only applies to authenticated requests.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "domain", "form_submission_keys", "submissions", "user" ] } }, "example": [ "domain" ] }, "experienceFilter": { "name": "filter", "in": "query", "description": "Filters the list of experiences.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns experiences whose name, title or slug contains this text (case-insensitive).", "example": "summer" }, "published": { "type": "string", "description": "A comma-separated list of booleans. Returns experiences whose published state matches.", "example": "true" }, "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `archived`).", "example": "active" }, "type": { "type": "string", "description": "A comma-separated list of experience types.", "example": "sweepstakes,contest" }, "domain": { "type": "string", "description": "A comma-separated list of domain IDs.", "example": "3" } } } }, "experienceSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "status,-id" } }, "experienceId": { "name": "experience_id", "in": "path", "required": true, "description": "The ID of the experience.", "schema": { "type": "integer", "example": 42 } }, "formSubmissionFilter": { "name": "filter", "in": "query", "description": "Filters the list of form submissions.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "person_id": { "type": "string", "description": "A comma-separated list of loyalty member IDs. Returns the submissions made by these members.", "example": "65f3a1c2e4b0a91d2c7e8f10,65f3a1c2e4b0a91d2c7e8f11" } } } }, "formSubmissionSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "-created_at" } }, "formSubmissionRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "experience", "files", "post" ] } }, "example": [ "post" ] }, "locale": { "name": "locale", "in": "query", "description": "The locale the form was displayed in, stored in the submission's `locale` attribute.", "schema": { "type": "string", "example": "en" } }, "metadata": { "name": "X-TINT-Metadata", "in": "header", "description": "Extra data to store in the submission's `metadata` attribute, as a URL-encoded query string.", "schema": { "type": "string", "example": "utm_source=newsletter&utm_campaign=spring" } }, "anonymousUid": { "name": "X-TINT-Anonymous-UID", "in": "header", "description": "An identifier of the anonymous visitor, stored with the submission.", "schema": { "type": "string", "example": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" } }, "deviceFingerprint": { "name": "X-TINT-Device-Fingerprint", "in": "header", "description": "A fingerprint of the visitor's device, stored with the submission.", "schema": { "type": "string", "example": "3f9a1c7e2b4d6f80" } }, "formSubmissionId": { "name": "form_submission_id", "in": "path", "required": true, "description": "The ID of the form submission.", "schema": { "type": "integer" }, "example": 893 }, "formSubmissionMetricGroup": { "name": "group", "in": "query", "description": "How to group the submissions. `created_at.{unit}` groups by the beginning of each interval (`created_at` alone is the same as `created_at.millennium`, which returns a single total). `post_id` sums the votes per post of a poll experience. `remote_ip` groups by the submitter's IP address. `data` (or `data.keys`) sums the integer values of each data key.", "schema": { "type": "string", "default": "created_at.millennium", "enum": [ "created_at", "created_at.minute", "created_at.hour", "created_at.day", "created_at.week", "created_at.month", "created_at.quarter", "created_at.year", "created_at.decade", "created_at.century", "created_at.millennium", "post_id", "remote_ip", "data", "data.keys" ], "example": "created_at.day" } }, "formSubmissionMetricFilter": { "name": "filter", "in": "query", "description": "Filters the form submissions that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "created_at": { "type": "object", "description": "Counts only the submissions created in this range.", "properties": { "$eq": { "type": "string", "format": "date-time", "description": "Created at exactly this date and time.", "example": "2025-03-14T16:42:07.000Z" }, "$gt": { "type": "string", "format": "date-time", "description": "Created after this date and time.", "example": "2025-03-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "Created on or after this date and time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Created before this date and time.", "example": "2025-04-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Created on or before this date and time.", "example": "2025-04-01T00:00:00.000Z" } } } } } }, "formSubmissionMetricRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. `post` only applies when grouping by `post_id` for a poll experience.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "post" ] } }, "example": [ "post" ] }, "formSubmissionExportRequestRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "experience", "form", "user" ] } }, "example": [ "experience" ] }, "formSubmissionExportRequestId": { "name": "form_submission_export_request_id", "in": "path", "required": true, "description": "The ID of the export request.", "schema": { "type": "string", "example": "OxZZQtuh5sXIKA" } }, "postFilter": { "name": "filter", "in": "query", "description": "Filters the posts. Unless noted, list filters take a comma-separated list of values and match any of them.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "A full-text search on the text, title, author name and username, and external ID of posts.", "example": "sneakers" }, "id": { "type": "string", "description": "A comma-separated list of post IDs.", "example": "9001,9002" }, "tint_id": { "type": "string", "description": "A comma-separated list of board IDs. Only for `GET /v2/teams/{team_id}/posts`.", "example": "42" }, "social_feed_id": { "type": "string", "description": "A comma-separated list of social feed IDs.", "example": "311" }, "saved_filter_id": { "type": "integer", "description": "The ID of a saved filter of the board whose criteria are used as defaults for the filters that aren't sent. Only for the board endpoints.", "example": 15 }, "status": { "type": "string", "description": "A comma-separated list of statuses: `public`, `private`, `deleted`, `author_deleted`, `privacy_deleted`, `moderation_deleted`, `image_moderation_pending`, `image_moderation_deleted`, `image_moderation_failed`.", "example": "public,private" }, "type": { "type": "string", "description": "A comma-separated list of sources (the posts' `type` attribute), for example `instagram_business`.", "example": "instagram_business,tiktok" }, "media_type": { "type": "string", "description": "A comma-separated list of media types among `text`, `image` and `video`.", "example": "image" }, "highlighted": { "type": "boolean", "description": "Returns only highlighted (`true`) or non-highlighted (`false`) posts.", "example": true }, "pinned": { "type": "boolean", "description": "Returns only pinned (`true`) or non-pinned (`false`) posts.", "example": false }, "verified": { "type": "boolean", "description": "Returns only reviews from verified (`true`) or unverified (`false`) buyers.", "example": true }, "incentivized": { "type": "boolean", "description": "Returns only incentivized (`true`) or non-incentivized (`false`) reviews.", "example": false }, "tag": { "description": "A comma-separated list of tags, `true`/`false` to return posts with or without tags, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "featured,follow up" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "language": { "type": "string", "description": "A comma-separated list of ISO 639-1 language codes.", "example": "en,fr" }, "sentiment": { "description": "A comma-separated list of text sentiments (`positive`, `negative`, `neutral`), or an object with `$in` and/or `$notin` lists. Sentiment is only available for English posts.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "positive" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "image_object": { "description": "A comma-separated list of objects detected in the image, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "shoe" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "image_emotions": { "description": "A comma-separated list of emotions detected in the image, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "happy" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "rating": { "description": "A rating (0 to 100) to match exactly, or an object of operators. `$range` takes a comma-separated list of `from-to` ranges, for example `80-100`.", "oneOf": [ { "title": "Exact rating", "type": "integer", "example": 100 }, { "title": "Operators", "type": "object", "properties": { "$eq": { "type": "integer", "description": "Equal to.", "example": 80 }, "$gt": { "type": "integer", "description": "Greater than.", "example": 60 }, "$gte": { "type": "integer", "description": "Greater than or equal to.", "example": 60 }, "$lt": { "type": "integer", "description": "Less than.", "example": 40 }, "$lte": { "type": "integer", "description": "Less than or equal to.", "example": 40 }, "$range": { "type": "string", "description": "A comma-separated list of inclusive `from-to` ranges.", "example": "0-20,80-100" } } } ] }, "published_at": { "description": "A publication time to match exactly, or an object of operators.", "oneOf": [ { "title": "Exact time", "type": "string", "format": "date-time", "example": "2025-03-14T16:42:07Z" }, { "$ref": "#/components/schemas/PostsTimeRangeFilter" } ] }, "product_id": { "type": "string", "description": "A comma-separated list of tagged product IDs, or `true`/`false` to return posts with or without product tags.", "example": "501" }, "product_sku": { "type": "string", "description": "A comma-separated list of tagged product SKUs, or `true`/`false` to return posts with or without product tags.", "example": "ACME-SNK-001" }, "product_family": { "type": "string", "description": "A comma-separated list of tagged product families.", "example": "sneakers" }, "right_request_status": { "type": "string", "description": "A comma-separated list of statuses of the posts' most recent right request: `approved`, `declined`, `deleted`, `error`, `expired`, `missing`, `pending`, `requested`, `soft_approved`, `token_error`.", "example": "approved" }, "right_request_status_expires_at": { "description": "Filters on when the status of the most recent right request expires. Only applies to approved right requests.", "oneOf": [ { "title": "Exact time", "type": "string", "format": "date-time", "example": "2025-12-31T23:59:59Z" }, { "$ref": "#/components/schemas/PostsTimeRangeFilter" } ] }, "visually_similar_to": { "type": "string", "description": "A post ID or image URL. Returns posts whose image is visually similar, sorted by similarity. Only for the board endpoints.", "example": "9001" } } } }, "postSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Ties are broken by publication time and ID. `score` sorts by relevance to `filter[q]`.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pinned", "-pinned", "published_at", "-published_at", "last_moderated_at", "-last_moderated_at", "rating", "-rating", "score", "-score" ] }, "default": [ "-pinned" ] }, "example": [ "-published_at" ] }, "postRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "asset", "author", "cta_associations", "cta_associations.cta", "product_tags", "products", "products.product", "replies", "right_requests", "social_feed", "tint" ] } }, "example": [ "author", "social_feed" ] }, "postCollapse": { "name": "collapse", "in": "query", "description": "Use `source,external_id` to return a single post for posts ingested in several boards from the same source post. The other copies are returned in the `siblings` relationship, and the response uses offset pagination (`page[offset]`, starting at 0) instead of cursors.", "schema": { "type": "string", "enum": [ "source,external_id" ], "example": "source,external_id" } }, "cursorPagination": { "name": "page", "in": "query", "description": "Cursor pagination. Use `page[size]` to set the number of items per page. Cursors are opaque; don't build them yourself, follow the `links.next` and `links.prev` URLs from the previous response instead.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "size": { "type": "integer", "description": "The number of items per page. Values above 200 are treated as 200.", "default": 25, "minimum": 1, "maximum": 200 }, "before": { "type": "string", "description": "An opaque cursor. Returns the items that come after the cursor position in the current sort order (for example, older posts when sorting by newest first). Used by `links.next`." }, "after": { "type": "string", "description": "An opaque cursor. Returns the items that come before the cursor position in the current sort order (for example, newer posts when sorting by newest first). Used by `links.prev`." } } } }, "postsModeratedMetricsFilter": { "name": "filter", "in": "query", "description": "Filters the moderation events that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tint_id": { "type": "string", "description": "A comma-separated list of board IDs. Defaults to all the boards you have access to.", "example": "42" }, "user_id": { "type": "string", "description": "A comma-separated list of IDs of the users who moderated the posts.", "example": "16891" }, "status": { "type": "string", "description": "A comma-separated list of the statuses the posts were moderated to (`public`, `private`, `deleted`).", "example": "public,private" }, "source": { "type": "string", "description": "A comma-separated list of post sources.", "example": "instagram_business" }, "time": { "type": "object", "description": "The time range (UTC). Defaults to the last 14 days.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "After this time.", "example": "2025-03-01T00:00:00Z" }, "$gte": { "type": "string", "format": "date-time", "description": "At or after this time.", "example": "2025-03-01T00:00:00Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Before this time.", "example": "2025-03-15T00:00:00Z" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before this time.", "example": "2025-03-14T23:59:59Z" } } } } } }, "postsModeratedMetricsGroup": { "name": "group", "in": "query", "description": "A comma-separated list of dimensions to group the metrics by.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "time.hour", "time.day", "time.week", "time.month", "time.quarter", "time.year", "time.day_of_week", "time.hour_of_day", "user_id", "tint_id", "status", "source" ] } }, "example": [ "user_id" ] }, "postEngagementType": { "name": "post_engagement_type", "in": "path", "required": true, "description": "The post engagement event type to count.", "schema": { "type": "string", "enum": [ "embed_post_modal_opened", "embed_post_external_link_opened", "embed_post_cta_clicked", "embed_post_shared", "embed_post_modal_navigate_right", "embed_post_modal_navigate_left", "embed_paginated", "embed_post_author_clicked", "embed_post_product_clicked" ], "example": "embed_post_cta_clicked" } }, "postsEngagementMetricsFilter": { "name": "filter", "in": "query", "description": "Filters the engagement events that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tint_id": { "type": "string", "description": "A comma-separated list of board IDs. Defaults to all the boards of the team.", "example": "42" }, "time": { "$ref": "#/components/schemas/PostsMetricsTimeFilter" } } } }, "postsEngagementMetricsGroup": { "name": "group", "in": "query", "description": "A comma-separated list of dimensions to group the metrics by.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "time.hour", "time.day", "time.week", "time.month", "time.quarter", "time.year", "time.day_of_week", "time.hour_of_day", "tint_id", "post_id", "personalization_type", "theme", "device_category", "media_type" ] } }, "example": [ "post_id" ] }, "postsIngestedMetricsFilter": { "name": "filter", "in": "query", "description": "Filters the ingested posts that are counted.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "tint_id": { "type": "string", "description": "A comma-separated list of board IDs.", "example": "42" }, "social_feed_id": { "type": "string", "description": "A comma-separated list of social feed IDs.", "example": "311" }, "social_feed_source": { "type": "string", "description": "A comma-separated list of numeric social feed source codes.", "example": "21" }, "account_id": { "type": "string", "description": "A comma-separated list of account IDs.", "example": "77" }, "time": { "$ref": "#/components/schemas/PostsMetricsTimeFilter" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/PostsMetricsTimeFilter" } ], "deprecated": true, "description": "Deprecated alias of `time`." } } } }, "postsIngestedMetricsGroup": { "name": "group", "in": "query", "description": "A comma-separated list of dimensions to group the metrics by.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "time.hour", "time.day", "time.week", "time.month", "time.quarter", "time.year", "time.day_of_week", "time.hour_of_day", "social_feed_id", "social_feed_source", "tint_id", "account_id" ] } }, "example": [ "time.day", "social_feed_source" ] }, "postId": { "name": "post_id", "in": "path", "required": true, "description": "The ID of the post.", "schema": { "type": "integer", "example": 9001 } }, "publicPostFilter": { "name": "filter", "in": "query", "description": "Filters the posts. Only public posts are returned. Unless noted, list filters take a comma-separated list of values and match any of them.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "$ref": "#/components/schemas/q" }, "id": { "$ref": "#/components/schemas/id" }, "social_feed_id": { "$ref": "#/components/schemas/social_feed_id" }, "saved_filter_id": { "$ref": "#/components/schemas/saved_filter_id" }, "type": { "$ref": "#/components/schemas/type" }, "media_type": { "$ref": "#/components/schemas/media_type" }, "highlighted": { "$ref": "#/components/schemas/highlighted" }, "pinned": { "$ref": "#/components/schemas/pinned" }, "verified": { "$ref": "#/components/schemas/verified" }, "incentivized": { "$ref": "#/components/schemas/incentivized" }, "tag": { "$ref": "#/components/schemas/tag" }, "language": { "$ref": "#/components/schemas/language" }, "sentiment": { "$ref": "#/components/schemas/sentiment" }, "image_object": { "$ref": "#/components/schemas/image_object" }, "image_emotions": { "$ref": "#/components/schemas/image_emotions" }, "rating": { "$ref": "#/components/schemas/rating" }, "published_at": { "$ref": "#/components/schemas/published_at" }, "product_id": { "$ref": "#/components/schemas/product_id" }, "product_sku": { "$ref": "#/components/schemas/product_sku" }, "product_family": { "$ref": "#/components/schemas/product_family" } } } }, "publicPostRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "author", "cta_associations", "cta_associations.cta", "product_tags", "products", "products.product", "replies", "social_feed" ] } }, "example": [ "author" ] }, "postsSummaryRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "team" ] } }, "example": [ "team" ] }, "postRequestId": { "name": "post_request_id", "in": "path", "required": true, "description": "The ID of the post create request, returned when the post was submitted.", "schema": { "type": "string", "example": "OxZZQtuh5sXIKA" } }, "postExportRequestId": { "name": "post_export_request_id", "in": "path", "required": true, "description": "The ID of the post export request.", "schema": { "type": "string", "example": "OxZZQtuh5sXIKA" } }, "collectionFilter": { "name": "filter", "in": "query", "description": "Filters the collections.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "A comma-separated list of statuses (`active`, `archived`). Defaults to `active`.", "default": "active", "example": "active,archived" }, "q": { "type": "string", "description": "Returns the collections whose name contains this text (case-insensitive).", "example": "summer" } } } }, "collectionSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "default": [ "-id" ] }, "example": [ "name" ] }, "collectionRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "assets" ] } }, "example": [ "assets" ] }, "collectionId": { "name": "collection_id", "in": "path", "required": true, "description": "The ID of the collection.", "schema": { "type": "integer", "example": 27 } }, "oauthApplicationsSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by, such as `id`, `name`, `created_at` or `updated_at`. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "name,-created_at" } }, "oauthApplicationId": { "name": "oauth_application_id", "in": "path", "required": true, "description": "The ID of the OAuth application.", "schema": { "type": "integer", "example": 17 } }, "webhookSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "string", "default": "-id", "example": "-created_at" } }, "webhookId": { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook.", "schema": { "type": "integer", "example": 15 } }, "webhookEventFilter": { "name": "filter", "in": "query", "description": "Filters the webhook events.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "A comma-separated list of statuses (`pending`, `success`, `failure`) to return.", "example": "failure" }, "created_at": { "type": "object", "description": "Returns the events created within this range.", "properties": { "$gt": { "type": "string", "format": "date-time", "example": "2025-03-01T00:00:00Z" }, "$gte": { "type": "string", "format": "date-time", "example": "2025-03-01T00:00:00Z" }, "$lt": { "type": "string", "format": "date-time", "example": "2025-04-01T00:00:00Z" }, "$lte": { "type": "string", "format": "date-time", "example": "2025-04-01T00:00:00Z" } } } } } }, "webhookEventSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order. Defaults to `-id` (newest first).", "explode": false, "schema": { "type": "string", "default": "-id", "example": "-created_at" } }, "webhookEventInclude": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include. `attempts` returns the delivery attempts.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "attempts" ] } }, "example": [ "attempts" ] }, "webhookEventId": { "name": "webhook_event_id", "in": "path", "required": true, "description": "The ID of the webhook event (the `data.id` of the payload we sent).", "schema": { "type": "integer", "example": 1377451 } }, "savedFilterRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "cta_associations", "cta_associations.cta", "tint" ] } }, "example": [ "tint" ] }, "savedFilterId": { "name": "saved_filter_id", "in": "path", "required": true, "description": "The ID of the saved filter.", "schema": { "type": "integer", "example": 15 } }, "ctaRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "tint" ] }, "example": [ "tint" ] } }, "ctaSort": { "name": "sort", "in": "query", "description": "A comma-separated list of fields to sort by. Prefix a field with `-` to sort in descending order.", "explode": false, "schema": { "type": "array", "default": [ "-id" ], "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at", "posts_count", "-posts_count", "saved_filters_count", "-saved_filters_count" ] }, "example": [ "name" ] } }, "ctaId": { "name": "cta_id", "in": "path", "required": true, "description": "The ID of the CTA.", "schema": { "type": "integer", "example": 731 } }, "ctaAssociationRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "cta", "post", "saved_filter" ] }, "example": [ "cta" ] } }, "ctaAssociationId": { "name": "cta_association_id", "in": "path", "required": true, "description": "The ID of the CTA association.", "schema": { "type": "integer", "example": 5120 } }, "roleInclude": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response. Included resources are limited to those you have access to.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "users", "tints", "accounts", "collections", "domains", "fonts", "experiences", "product_accounts", "product_feeds", "personalizations", "oauth_applications", "webhooks", "forms", "mixes" ] } }, "example": [ "users" ] }, "roleFilter": { "name": "filter", "in": "query", "description": "Filters the roles.", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Returns the roles whose name or description contains the value (case-insensitive), or whose ID is the value.", "example": "moderator" }, "permission": { "type": "string", "description": "A comma-separated list of permissions. Returns the roles that have all of these permissions, as well as the roles that have the `all` permission.", "example": "moderate_tint,replies_r" } } } }, "roleSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "-id", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ] }, "default": [ "-id" ] }, "example": [ "name" ] }, "roleId": { "name": "role_id", "in": "path", "required": true, "description": "The ID of the role.", "schema": { "type": "integer", "example": 3 } }, "privacyRequestSort": { "name": "sort", "in": "query", "description": "A comma-separated list of attributes to sort by. Prefix an attribute with `-` to sort in descending order.", "schema": { "type": "string", "default": "-id", "example": "-created_at" } }, "privacyRequestRelationships": { "name": "include", "in": "query", "description": "A comma-separated list of related resources to include in the response.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "team" ] } }, "example": [ "team" ] }, "privacyRequestId": { "name": "privacy_request_id", "in": "path", "required": true, "description": "The ID of the privacy request.", "schema": { "type": "integer", "example": 37 } }, "webhookSignatureHeader": { "name": "X-TINT-Signature", "in": "header", "description": "`timestamp,signature`, where `timestamp` is the Unix time (in seconds) at which the delivery was signed and `signature` is the Base64-encoded HMAC-SHA256 of `timestamp.body`, keyed with the webhook's signing secret. Only sent when the webhook has a signing secret. Every attempt is signed again, so retries carry a new timestamp. See [Webhook Event Signatures](advocacy/guides/webhook-signatures.html).", "schema": { "type": "string", "example": "1741970527,3q2+7wLkO1d0mQx6gU6c1nFQ0J7Jt3r2m4Yy8h1r9Qs=" } }, "webhookApiVersionHeader": { "name": "API-Version", "in": "header", "required": true, "description": "The API version the payload was serialized with, unless the webhook overrides this header.", "schema": { "type": "string", "example": "20190326" } }, "webhookUserAgentHeader": { "name": "User-Agent", "in": "header", "required": true, "description": "Always `TINT Webhook/2.0`, unless the webhook overrides this header.", "schema": { "type": "string", "example": "TINT Webhook/2.0" } } }, "schemas": { "accountTypes": { "type": "string", "description": "The type of account, i.e. the external service it connects to.", "enum": [ "bazaarvoice", "bigcommerce", "creator_iq", "facebook", "flickr", "ftp", "hootsuite", "http", "instagram", "instagram_business", "klaviyo", "linkedin", "magento", "pinterest", "power_reviews", "re_captcha", "s3", "salesforce_commerce_cloud", "sftp", "shopify", "slack", "spark", "threads", "tiktok", "tiktok_business", "tumblr", "twitter", "woocommerce", "youtube" ], "example": "instagram_business" }, "accountStatuses": { "type": "string", "description": "`ok` when the stored credentials are valid, `expired` when they need to be reauthorized, and `pending` while the account is being set up.", "enum": [ "ok", "expired", "pending" ], "example": "ok" }, "accountCapabilities": { "type": "string", "description": "What an account can be used for: `ingest` (collect content for social feeds), `compose` (publish content), `syndicate` (send content to review platforms), `captcha` (protect forms), `products` (import product catalogs), `email`, `events` (send events to a marketing platform), and `profile`.", "enum": [ "ingest", "compose", "syndicate", "captcha", "products", "email", "events", "profile" ], "example": "ingest" }, "ReadOnlyDate": { "type": "string", "format": "date-time", "example": "2020-01-01T00:00:00.000Z", "readOnly": true }, "AccountAttributes": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/accountTypes" } ], "description": "The type of account, i.e. the external service it connects to.", "readOnly": true }, "external_id": { "type": "string", "description": "The ID of this account at the source. For credential-based accounts this is derived from the credentials (for example the host of the `site`, or an MD5 digest of the API key).", "example": "17841401839964064", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/accountStatuses" } ], "readOnly": true }, "name": { "type": [ "string", "null" ], "description": "The display name of the account at the source.", "example": "Acme Inc.", "readOnly": true }, "username": { "type": [ "string", "null" ], "description": "The username or handle of the account at the source, when it has one.", "example": "acme", "readOnly": true }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the account's profile picture, when available.", "example": "https://cdn.example.com/avatars/acme.jpg", "readOnly": true }, "site": { "type": [ "string", "null" ], "description": "The store URL, server URL or AWS region the account is tied to (e.g. for `shopify`, `magento`, `woocommerce`, `ftp`, `http`, `sftp`, and `s3`). `null` for other account types.", "example": null, "readOnly": true }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time when the stored credentials are known to expire, or `null` if they don't expire.", "example": "2025-05-13T16:42:07.000Z", "readOnly": true }, "capabilities": { "type": "array", "description": "What the account can be used for. Determined by the account type.", "readOnly": true, "items": { "$ref": "#/components/schemas/accountCapabilities" }, "example": [ "ingest", "compose" ] }, "meta": { "type": "object", "description": "Additional, source-specific information about the account (for example profile statistics). Empty for most account types.", "additionalProperties": true, "example": {}, "readOnly": true }, "followers_count": { "type": [ "integer", "null" ], "description": "The number of followers of the account at the source, when known.", "example": 12840, "readOnly": true }, "follows_count": { "type": [ "integer", "null" ], "description": "The number of accounts this account follows at the source, when known.", "example": 312, "readOnly": true }, "media_count": { "type": [ "integer", "null" ], "description": "The number of media items published by the account at the source, when known.", "example": 587, "readOnly": true }, "likes_count": { "type": [ "integer", "null" ], "description": "The number of likes received by the account at the source, when known.", "example": null, "readOnly": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The time when the account was connected.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The time when the account was last updated.", "example": "2025-03-14T16:42:07.000Z" } } }, "RelationshipMetaExcluded": { "type": "object", "properties": { "included": { "type": "boolean", "default": false } } }, "Account": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the account.", "example": "4821", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "account" ] }, "attributes": { "$ref": "#/components/schemas/AccountAttributes" }, "relationships": { "type": "object", "readOnly": true, "properties": { "social_feeds": { "type": "object", "description": "The social feeds using this account. Only included when the access token has the `social_feeds:read` scope. `data` is only present when `social_feeds` is included (`include=social_feeds`) and only lists the social feeds of boards the user can access.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the social feed.", "example": "90211" }, "type": { "type": "string", "enum": [ "social_feed" ] } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of social feeds using this account, across the whole team.", "example": 2 } } } } }, "subaccounts": { "type": "object", "description": "The pages, organizations, channels, etc. that can be accessed with this account. `data` is only present when `subaccounts` is included (`include=subaccounts`); otherwise `meta.included` is `false`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the subaccount at the source.", "example": "17841401839964064" }, "type": { "type": "string", "enum": [ "subaccount" ] } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "PaginationLinks": { "type": "object", "description": "Pagination links for a list response. The URLs keep the request's query parameters (filters, sorting and `page[size]`) and only change the page position.", "required": [ "self", "first" ], "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the current page.", "example": "https://api.tintup.com/v2/teams/1/tints?page%5Bnumber%5D=2" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page.", "example": "https://api.tintup.com/v2/teams/1/tints" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. With offset pagination (`page[number]`), it is omitted on the last page. With cursor pagination (`page[before]`/`page[after]`), it is omitted only when the current page is empty.", "example": "https://api.tintup.com/v2/teams/1/tints?page%5Bnumber%5D=3" }, "prev": { "type": "string", "format": "uri", "description": "The URL of the previous page. With offset pagination (`page[number]`), it is omitted on the first page. With cursor pagination (`page[before]`/`page[after]`), it is omitted only when the current page is empty.", "example": "https://api.tintup.com/v2/teams/1/tints?page%5Bnumber%5D=1" } } }, "x-errors": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "An application-specific error code." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "status": { "type": "string", "description": "The HTTP status code, as a string." }, "source": { "type": "object", "description": "The part of the request document that caused the error.", "properties": { "pointer": { "type": "string", "description": "A JSON Pointer to the value in the request document that caused the error." } } } } } } } }, "accountTypesForCreate": { "type": "string", "description": "The type of account to connect with credentials. Other account types can only be connected using the OAuth flow (see [Authenticate an account](#operation-v2-teams-team-id-accounts-new-get)).", "enum": [ "bazaarvoice", "bigcommerce", "creator_iq", "ftp", "http", "magento", "power_reviews", "re_captcha", "s3", "salesforce_commerce_cloud", "sftp", "woocommerce" ], "example": "sftp" }, "NewAccount": { "type": "object", "description": "Connects an account using credentials instead of OAuth. Which attributes are required, or must be omitted, depends on `type`; see each attribute.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "account" ] }, "attributes": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/accountTypesForCreate" }, "access_token": { "type": [ "string", "null" ], "description": "The credential used to connect to the service. Required for every type except `s3`. For `creator_iq` and `bazaarvoice` this is the API key (it must be unique within the team); for `salesforce_commerce_cloud` it is `client_id|client_secret|short_code|organization_id`; for `ftp`, `http`, and `sftp` it is the username (stored as part of the URL).", "example": "acme-feeds", "writeOnly": true }, "secret": { "type": [ "string", "null" ], "description": "The password or API secret. Required for `bazaarvoice`, `woocommerce`, `ftp`, and `http`; optional for `sftp`; must be omitted (or empty) for every other type.", "example": "s3cr3t-Pa55word", "writeOnly": true }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the account at the source. Required for `power_reviews` (merchant ID), `re_captcha` (site key), `bigcommerce` (store hash), and `s3` (bucket name); must be omitted (or empty) for every other type.", "example": null, "writeOnly": true }, "site": { "type": [ "string", "null" ], "description": "Required for `magento`, `woocommerce`, `ftp`, `http`, `sftp`, and `s3`. For `s3` it's an AWS region (e.g. `us-east-1`). Otherwise it's the server URL: `ftp` must start with `ftp://` or `ftps://`, `sftp` with `sftp://`, and `http`, `magento`, and `woocommerce` with `http://` or `https://`. Ignored for other types.", "example": "sftp://files.example.com/feeds/products.csv", "writeOnly": true } } } } }, "Redirect": { "type": "object", "description": "A URL to send the user to.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "An MD5 digest of the URL.", "example": "9e107d9d372bb6826bd81d3542a419d6", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "redirect" ] }, "attributes": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL of the third-party authorization page.", "example": "https://auth.example.com/oauth/authorize?client_id=8f14e45f&response_type=code&state=eyJhbGciOiJIUzI1NiJ9" } } } } }, "subaccountTypes": { "type": "string", "description": "The kind of entity the subaccount represents at the source.", "enum": [ "profile", "organization", "page", "group", "public_channel", "room", "blog", "channel", "instagram", "board", "campaign" ], "example": "page" }, "subaccountCapabilities": { "type": "string", "description": "What a subaccount can be used for: `ingest` (collect content) or `compose` (publish content).", "enum": [ "ingest", "compose" ], "example": "ingest" }, "Subaccount": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the subaccount at the source.", "example": "17841401839964064", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "subaccount" ] }, "attributes": { "type": "object", "readOnly": true, "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/accountTypes" } ], "description": "The type of the account this subaccount belongs to." }, "type": { "oneOf": [ { "$ref": "#/components/schemas/subaccountTypes" }, { "type": "null" } ], "description": "The kind of entity the subaccount represents at the source." }, "name": { "type": [ "string", "null" ], "description": "The display name of the subaccount at the source.", "example": "Acme Inc." }, "username": { "type": [ "string", "null" ], "description": "The username or handle of the subaccount at the source, when it has one.", "example": "acme" }, "biography": { "type": [ "string", "null" ], "description": "The biography or description of the subaccount at the source, when available.", "example": "Outdoor gear for every adventure." }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the subaccount's picture, when available.", "example": "https://cdn.example.com/avatars/acme.jpg" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the subaccount at the source, when available.", "example": "https://www.instagram.com/acme" }, "capabilities": { "type": [ "array", "null" ], "description": "What the subaccount can be used for.", "items": { "$ref": "#/components/schemas/subaccountCapabilities" }, "example": [ "ingest", "compose" ] }, "meta": { "type": "object", "description": "Additional, source-specific information about the subaccount. Often empty.", "additionalProperties": true, "example": {} }, "followers_count": { "type": [ "integer", "null" ], "description": "The number of followers of the subaccount at the source, when known.", "example": 12840 }, "follows_count": { "type": [ "integer", "null" ], "description": "The number of accounts this subaccount follows at the source, when known.", "example": 312 }, "media_count": { "type": [ "integer", "null" ], "description": "The number of media items published by the subaccount at the source, when known.", "example": 587 } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "account": { "type": "object", "description": "The account this subaccount belongs to. `data` is only present when `account` is included (`include=account`); otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the account.", "example": "4821" }, "type": { "type": "string", "enum": [ "account" ] } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "NewProductFeedRefreshRequest": { "type": "object", "required": [ "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_feed_refresh_request" ], "example": "product_feed_refresh_request" }, "attributes": { "type": "object", "required": [ "product_feed_id" ], "properties": { "product_feed_id": { "type": "string", "description": "The ID of the product feed to refresh. Must match the `product_feed_id` in the path.", "example": "12" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "Required for `csv` product feeds, and must be omitted for other feeds. The HTTP or HTTPS URL of a CSV file formatted according to the import requirements.", "example": "https://files.example.com/exports/products.csv" } } } } }, "ProductFeedRefreshRequest": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The opaque ID of the refresh request. Use it to check the status of the refresh.", "example": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6InByb2R1Y3RfaW1wb3J0X3JlcXVlc3R8NDIifQ.c2lnbmF0dXJl", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product_feed_refresh_request" ], "example": "product_feed_refresh_request" }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "description": "`pending` while the feed is being refreshed, then `success` or, when it failed, `failed` for `csv` feeds and `failure` for other feeds.", "enum": [ "pending", "success", "failed", "failure" ], "example": "pending" } } }, "relationships": { "type": "object", "properties": { "product_feed": { "type": "object", "description": "The product feed being refreshed. `data` is only present when `include=product_feed` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product_feed" ], "example": "product_feed" }, "id": { "type": "string", "example": "12" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "statuses": { "type": "string", "description": "`active` products are shown and can be tagged; `archived` products are hidden from lists unless you filter on `archived`.", "enum": [ "active", "archived" ], "example": "active" }, "Product": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the product.", "example": "1234", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product" ], "example": "product" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the product.", "example": "Acme Runner 2 sneakers" }, "description": { "type": [ "string", "null" ], "description": "A description of the product.", "example": "Lightweight running sneakers with a breathable mesh upper." }, "sku": { "type": [ "string", "null" ], "description": "The stock keeping unit (SKU), unique within the product feed.", "example": "ACME-RUN2-BLK-42" }, "brand": { "type": [ "string", "null" ], "description": "The brand of the product.", "example": "Acme" }, "family": { "type": [ "string", "null" ], "description": "The product family, used to group variants of the same product.", "example": "Acme Runner 2" }, "categories": { "type": [ "array", "null" ], "description": "The categories the product belongs to.", "items": { "type": "string" }, "example": [ "Footwear", "Running" ] }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the main image of the product.", "example": "https://cdn.example.com/products/acme-runner-2-black.jpg" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the product page.", "example": "https://shop.example.com/products/acme-runner-2" }, "currency": { "type": [ "string", "null" ], "description": "The currency of `price` and `sale_price`, usually an ISO 4217 code.", "example": "USD" }, "price": { "type": [ "string", "null" ], "description": "The regular price, as a string with two decimals.", "example": "89.00" }, "sale_price": { "type": [ "string", "null" ], "description": "The sale price, as a string with two decimals. Members of the team that owns the product always get it; everyone else only gets it while the sale is going on (`sale_price_starts_at` is in the past and `sale_price_ends_at` is empty or in the future), otherwise it's `null`.", "example": "69.00" }, "sale_price_starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sale starts. Only returned to members of the team that owns the product.", "example": "2025-03-14T00:00:00.000Z" }, "sale_price_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sale ends. Members of the team that owns the product always get it; everyone else only gets it once the sale has started, otherwise it's `null`.", "example": "2025-03-31T23:59:59.000Z" }, "availability": { "type": [ "string", "null" ], "description": "The stock availability of the product.", "enum": [ "in_stock", "out_of_stock", "preorder", "available_for_order", "discontinued", "pending", null ], "example": "in_stock" }, "status": { "allOf": [ { "$ref": "#/components/schemas/statuses" } ], "description": "The status of the product. Only returned to members of the team that owns the product." } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "product_feed": { "type": "object", "description": "The product feed the product belongs to. `data` is only present when `include=product_feed` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product_feed" ], "example": "product_feed" }, "id": { "type": "string", "example": "12" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "availabilities": { "type": "string", "description": "The stock availability of the product.", "enum": [ "in_stock", "out_of_stock", "preorder", "available_for_order", "discontinued", "pending" ], "example": "in_stock" }, "ProductWritableAttributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the product.", "example": "Acme Runner 2 sneakers" }, "description": { "type": [ "string", "null" ], "description": "A description of the product. Blank strings are stored as `null`.", "example": "Lightweight running sneakers with a breathable mesh upper." }, "sku": { "type": "string", "description": "The stock keeping unit (SKU). Must be unique within the product feed (case-insensitive).", "example": "ACME-RUN2-BLK-42" }, "brand": { "type": [ "string", "null" ], "description": "The brand of the product. Blank strings are stored as `null`.", "example": "Acme" }, "family": { "type": [ "string", "null" ], "description": "The product family, used to group variants of the same product (case-insensitive).", "example": "Acme Runner 2" }, "categories": { "type": "array", "description": "The categories the product belongs to. In requests, a comma-separated string (for example, `\"Footwear,Running\"`) is also accepted.", "items": { "type": "string" }, "example": [ "Footwear", "Running" ] }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the main image of the product.", "example": "https://cdn.example.com/products/acme-runner-2-black.jpg" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the product page. Blank strings are stored as `null`.", "example": "https://shop.example.com/products/acme-runner-2" }, "currency": { "type": [ "string", "null" ], "description": "The currency of `price` and `sale_price`, usually an ISO 4217 code. Blank strings are stored as `null`.", "example": "USD" }, "price": { "type": [ "string", "null" ], "description": "The regular price. Returned as a string with two decimals (for example, `\"89.00\"`); `null` when not set or not a number.", "example": "89.00" }, "sale_price": { "type": [ "string", "null" ], "description": "The sale price, returned as a string with two decimals; `null` when not set or not a number.", "example": "69.00" }, "sale_price_starts_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sale starts, or `null` when there is no sale.", "example": "2025-03-14T00:00:00.000Z" }, "sale_price_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the sale ends, or `null` when the sale has no end date.", "example": "2025-03-31T23:59:59.000Z" }, "availability": { "allOf": [ { "$ref": "#/components/schemas/availabilities" } ], "description": "The stock availability of the product. Defaults to `in_stock`." }, "status": { "allOf": [ { "$ref": "#/components/schemas/statuses" } ], "description": "The status of the product. Defaults to `active`." } } }, "NewProduct": { "type": "object", "required": [ "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product" ], "example": "product" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductWritableAttributes" }, { "type": "object", "required": [ "product_feed_id", "name", "sku" ], "properties": { "product_feed_id": { "type": "integer", "description": "The ID of the `manual` product feed to add the product to. Returns `404 Not Found` when the product feed doesn't exist, isn't accessible, or isn't a `manual` feed.", "example": 12 } } } ] } } }, "ProductUpdate": { "type": "object", "required": [ "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the product being updated.", "example": "1234" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product" ], "example": "product" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductWritableAttributes" } ], "description": "The attributes to change. Products of `manual` product feeds accept every attribute below; products of other product feeds are kept in sync with their source, so only `status` is applied and the other attributes are ignored." } } }, "scheduledContentStatus": { "type": "string", "description": "Publishing status. `pending` until the content is published, then `success` if the network accepted it or `failed` otherwise.", "enum": [ "pending", "success", "failed" ], "example": "pending" }, "AssetSource": { "type": "string", "description": "Where the asset comes from. `branded` means it was uploaded directly.", "enum": [ "branded", "creator_iq", "custom", "email", "externally_sourced_posts", "facebook", "flickr", "form_submission", "google_news", "googleplus", "hootsuite", "instagram", "instagram_business", "linkedin", "pinterest", "public_post", "review_trackers", "rss", "slack", "sms", "spark", "threads", "tiktok", "tumblr", "twitter", "vine", "wechat", "youtube" ], "example": "instagram_business" }, "scheduledContentPrivacy": { "type": [ "string", "null" ], "description": "Who can see the published content. Required for TikTok accounts (`everyone`, `followers`, `mutual_followers` or `self_only`; private TikTok accounts can't use `everyone` and public ones can't use `followers`) and YouTube accounts (`everyone`, `self_only` or `unlisted`). Must be empty (`null`) for every other network.", "enum": [ "everyone", "followers", "mutual_followers", "self_only", "unlisted", null ], "example": null }, "ScheduledContentOptions": { "type": "object", "description": "Network-specific publishing options. Only used by TikTok; each option must be `false` (or omitted) when the TikTok account has disabled the corresponding interaction.", "properties": { "allow_comments": { "type": [ "boolean", "null" ], "description": "Whether viewers can comment on the TikTok video.", "example": true }, "allow_combine": { "type": [ "boolean", "null" ], "description": "Whether viewers can use the TikTok video in a Stitch.", "example": false }, "allow_side_by_side": { "type": [ "boolean", "null" ], "description": "Whether viewers can use the TikTok video in a Duet.", "example": false } }, "example": {} }, "UploadIdentifier": { "type": "object", "description": "A reference to an uploaded file.", "properties": { "type": { "type": "string", "enum": [ "upload" ], "example": "upload" }, "id": { "type": "string", "description": "The signed ID of the file.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTQsInB1ciI6ImJsb2JfaWQifX0=--7b1f0c7c3e5e0a9d2b6f4e1c8a3d5f7e9b2c4a6d" } } }, "ScheduledContent": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the scheduled content.", "readOnly": true, "example": "4821" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "scheduled_content" ], "example": "scheduled_content" }, "attributes": { "type": "object", "readOnly": true, "required": [ "status", "text", "published_at", "created_at", "updated_at", "tags", "source", "subaccount_id", "privacy", "options" ], "properties": { "status": { "$ref": "#/components/schemas/scheduledContentStatus" }, "text": { "type": [ "string", "null" ], "description": "The caption to publish. `null` for YouTube and Threads contents without a caption.", "example": "Our spring collection drops Friday. Which color are you picking? 🌸" }, "published_at": { "type": "string", "format": "date-time", "description": "When the content is (or was) scheduled to be published.", "example": "2025-03-14T16:42:07.000Z" }, "created_at": { "type": "string", "format": "date-time", "description": "When the scheduled content was created.", "example": "2025-03-10T09:15:32.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the scheduled content was last updated.", "example": "2025-03-11T13:02:48.000Z" }, "tags": { "type": "array", "description": "Internal labels used to organize and filter scheduled contents.", "items": { "type": "string" }, "example": [ "spring-launch", "instagram" ] }, "source": { "allOf": [ { "$ref": "#/components/schemas/AssetSource" } ], "description": "The network the content is published to, derived from the account's type.", "example": "instagram_business" }, "subaccount_id": { "type": [ "string", "null" ], "description": "The ID, at the source, of the page, profile or organization the content is published to. `null` for networks without subaccounts (X (Twitter), TikTok, YouTube and Threads).", "example": "17841400008460056" }, "privacy": { "$ref": "#/components/schemas/scheduledContentPrivacy" }, "options": { "$ref": "#/components/schemas/ScheduledContentOptions" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "media": { "type": "object", "description": "The files to publish. `data` is only returned when `media` is included; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UploadIdentifier" } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "account": { "type": "object", "description": "The account the content is published with. Only returned when the token has the `accounts:read` scope. `data` is only returned when `account` is included.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account" ], "example": "account" }, "id": { "type": "string", "example": "1375" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "subaccount": { "type": "object", "description": "The subaccount the content is published to. Only returned when the token has the `accounts:read` scope. `data` is only returned when `subaccount` is included, and is `null` when there's no subaccount.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "subaccount" ], "example": "subaccount" }, "id": { "type": "string", "example": "17841400008460056" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "team": { "type": "object", "description": "The team that owns the content. Only returned when the token has the `teams:read` scope. `data` is only returned when `team` is included.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ], "example": "team" }, "id": { "type": "string", "example": "212" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "campaign": { "type": "object", "description": "The campaign the content is associated with. Only returned when the token has the `campaigns:read` scope. `data` is only returned when `campaign` is included, and is `null` when there's no campaign.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "campaign" ], "example": "campaign" }, "id": { "type": "string", "example": "58" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "ScheduledContentWritableAttributes": { "type": "object", "properties": { "text": { "type": [ "string", "null" ], "description": "The caption to publish. Required for every network except YouTube and Threads. Maximum length depends on the network: X (Twitter) 280, Threads 500, Facebook and Hootsuite 2,000, Instagram 2,200, LinkedIn 3,000, TikTok 150 and YouTube 5,000 characters.", "maxLength": 5000, "example": "Our spring collection drops Friday. Which color are you picking? 🌸" }, "title": { "type": [ "string", "null" ], "description": "The video title. Required for YouTube accounts and must be empty for every other network. Write-only: it isn't returned in responses.", "writeOnly": true, "example": null }, "tags": { "type": [ "array", "null" ], "description": "Internal labels used to organize and filter scheduled contents. They aren't published.", "items": { "type": "string" }, "example": [ "spring-launch", "instagram" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When to publish the content. Must be in the future. When omitted on create, the content is published right away.", "example": "2025-03-14T16:42:07.000Z" }, "media": { "type": [ "array", "null" ], "description": "Signed IDs of the files to publish, as returned by a direct upload. The number of files and their type, size, duration, dimensions and aspect ratio are validated against the network's limits (for example, Instagram requires 1 to 10 files, X (Twitter) accepts up to 4, and TikTok and YouTube require exactly 1 video). Facebook posts with more than one file must only contain images. Write-only: published files are returned in the `media` relationship.", "writeOnly": true, "items": { "type": "string" }, "example": [ "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTQsInB1ciI6ImJsb2JfaWQifX0=--7b1f0c7c3e5e0a9d2b6f4e1c8a3d5f7e9b2c4a6d" ] }, "campaign_id": { "type": [ "string", "null" ], "description": "The ID of a campaign of the team to associate the content with. Must be a string of digits.", "pattern": "^\\d+$", "writeOnly": true, "example": "58" }, "privacy": { "$ref": "#/components/schemas/scheduledContentPrivacy" }, "options": { "$ref": "#/components/schemas/ScheduledContentOptions" } } }, "NewScheduledContent": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "scheduled_content" ], "example": "scheduled_content" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ScheduledContentWritableAttributes" }, { "type": "object", "required": [ "account_id" ], "properties": { "account_id": { "type": "string", "description": "The ID of the connected account to publish with, as a string of digits. The account must belong to the user, be in good standing and support publishing. Can't be changed after creation.", "pattern": "^\\d+$", "example": "1375" }, "subaccount_id": { "type": [ "string", "null" ], "description": "The ID, at the source, of the page, profile or organization of the account to publish to. Required for every network except X (Twitter), TikTok, YouTube and Threads. Can't be changed after creation.", "example": "17841400008460056" } } } ] } } }, "ScheduledContentUpdate": { "type": "object", "description": "Only the attributes that are sent are changed; `account_id` and `subaccount_id` can't be changed. `media` is always replaced: omitting it removes the existing files.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the scheduled content.", "example": "4821" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "scheduled_content" ], "example": "scheduled_content" }, "attributes": { "$ref": "#/components/schemas/ScheduledContentWritableAttributes" } } }, "ScheduledContentAggregation": { "type": "object", "required": [ "id", "type", "attributes" ], "readOnly": true, "properties": { "id": { "type": "string", "description": "The aggregated field: `tags`, `account_ids` or `subaccount_ids`.", "enum": [ "tags", "account_ids", "subaccount_ids" ], "example": "account_ids" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "aggregation" ], "example": "aggregation" }, "attributes": { "type": "object", "required": [ "buckets" ], "properties": { "buckets": { "type": "object", "description": "The number of scheduled contents of the team for each value. Keys are tags for `tags`, account IDs for `account_ids`, and `{source}|{subaccount_id}` for `subaccount_ids`.", "additionalProperties": { "type": "integer" }, "example": { "1375": 42, "1402": 7 } } } } } }, "campaignDateFilter": { "type": "object", "description": "A date-time range filter.", "properties": { "$eq": { "type": "string", "format": "date-time", "description": "Equal to.", "example": "2025-06-01T00:00:00.000Z" }, "$gt": { "type": "string", "format": "date-time", "description": "After.", "example": "2025-06-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "At or after.", "example": "2025-06-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Before.", "example": "2025-09-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before.", "example": "2025-08-31T23:59:59.000Z" } } }, "CampaignAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the campaign.", "minLength": 1, "example": "Summer collection" }, "starts_at": { "type": "string", "format": "date-time", "description": "The time when the campaign starts. Must be before `ends_at`.", "example": "2025-06-01T00:00:00.000Z" }, "ends_at": { "type": "string", "format": "date-time", "description": "The time when the campaign ends. Must be after `starts_at`.", "example": "2025-08-31T23:59:59.000Z" }, "label_color": { "type": "string", "description": "The color used to label the campaign in calendars, as a 3- to 6-digit hexadecimal color code.", "pattern": "^#[0-9a-fA-F]{3,6}$", "example": "#f5a623" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The time when the campaign was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The time when the campaign was last updated.", "example": "2025-03-14T16:42:07.000Z" } } }, "Campaign": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the campaign.", "example": "57", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "campaign" ] }, "attributes": { "$ref": "#/components/schemas/CampaignAttributes" }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the campaign.", "example": "https://api.example.com/v2/teams/1024/campaigns/57" } } } } }, "NewCampaign": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "campaign" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/CampaignAttributes" }, { "type": "object", "required": [ "name", "starts_at", "ends_at", "label_color" ] } ] } } }, "CampaignUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the campaign. Optional and ignored; the campaign in the path is updated.", "example": "57" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "campaign" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/CampaignAttributes" } ], "description": "The attributes to change. Omitted attributes keep their current values." } } }, "IdAsStringReadOnly": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the resource.", "example": "1", "readOnly": true } } }, "sourceTypes": { "type": "string", "description": "The source of the products: the type of the product account (product integration) it syncs from, `csv` for a CSV file imported from a URL, or `manual` for products managed using the API.", "enum": [ "bazaarvoice", "bigcommerce", "csv", "facebook", "ftp", "http", "magento", "manual", "s3", "salesforce_commerce_cloud", "sftp", "shopify", "woocommerce" ], "example": "shopify" }, "statuses-2": { "type": "string", "description": "`active` while the product feed is being kept in sync, `archived` once it's no longer synced, and `error` when the last sync or import failed (see `error_message`).", "enum": [ "active", "archived", "error" ], "example": "active" }, "ProductFeedOptions": { "type": "object", "description": "Source-specific options.", "properties": { "delete_files_once_processed": { "type": "boolean", "description": "Whether to delete the file from the server or bucket once it has been imported. Only used when `source` is `ftp`, `sftp` or `s3`.", "default": false, "example": false } } }, "ProductFeed": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_feed" ], "example": "product_feed" }, "attributes": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the product feed. When not given, it's derived from the source: the file name of a `csv` feed, the file path of an `ftp`, `sftp`, `http` or `s3` feed, the catalog name of a `facebook` feed, or the product account name.", "example": "Acme spring collection" }, "source": { "$ref": "#/components/schemas/sourceTypes" }, "status": { "$ref": "#/components/schemas/statuses-2" }, "options": { "$ref": "#/components/schemas/ProductFeedOptions" }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When products were last imported, or `null` if they haven't been imported yet.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "error_message": { "type": [ "string", "null" ], "description": "The reason the last sync or import failed, or `null` when it succeeded.", "example": null, "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "product_account": { "type": "object", "description": "The product account (product integration) the feed syncs from; `data` is `null` for `csv` and `manual` feeds. `data` is only present when `include=product_account` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "product_account" ], "example": "product_account" }, "id": { "type": "string", "example": "7" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "catalog": { "type": "object", "description": "The catalog the feed syncs from (resource type `catalog`, with a `name` attribute); `data` is `null` when the feed has no catalog. `data` is only present when `include=catalog` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "catalog" ], "example": "catalog" }, "id": { "type": "string", "example": "1098765432101234" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "products": { "type": "object", "description": "The products of the feed. Only returned when the access token has the `products:read` scope. `data` (the first 25 products) is only present when `include=products` is requested.", "properties": { "data": { "type": "array", "description": "The first 25 products of the feed.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product" ], "example": "product" }, "id": { "type": "string", "example": "1234" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The total number of products in the feed.", "example": 124 } } } } } } } } } ] }, "NewProductFeed": { "type": "object", "required": [ "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_feed" ], "example": "product_feed" }, "attributes": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/sourceTypes" }, "name": { "type": [ "string", "null" ], "description": "The name of the product feed. Required when `source` is `manual`; optional for `csv`; must be omitted for the other sources (the name is derived from the source).", "example": "Acme spring collection" }, "product_account_id": { "type": [ "integer", "null" ], "description": "The ID of the product account to sync from. Required for every source except `csv` and `manual`, for which it must be omitted. The product account's `type` must match `source`. Except for `facebook`, `ftp`, `http`, `s3` and `sftp`, a product account can only have one product feed.", "example": 7 }, "catalog_id": { "type": [ "string", "null" ], "description": "Required when `source` is `facebook` (the catalog ID), `ftp`, `sftp` or `http` (the path of the CSV file; for `ftp` and `sftp`, a path ending with `/` imports every `.csv` file in that directory), or `s3` (the object key in the bucket). Must be omitted for the other sources. Must be unique for the product account.", "example": "/exports/products.csv" }, "url": { "type": "string", "format": "uri", "description": "Required when `source` is `csv`, and must be omitted otherwise. The HTTP or HTTPS URL of the CSV file to import. Its header row must include the `sku`, `name`, `image_url` and `url` columns.", "example": "https://files.example.com/exports/products.csv", "writeOnly": true }, "options": { "$ref": "#/components/schemas/ProductFeedOptions" } } } } }, "sourceTypes-2": { "type": "string", "description": "The type of product integration.", "enum": [ "bazaarvoice", "bigcommerce", "facebook", "ftp", "http", "magento", "s3", "salesforce_commerce_cloud", "sftp", "shopify", "woocommerce" ], "example": "shopify" }, "productAccountStatuses": { "type": "string", "description": "`ok` when the stored credentials are valid, `expired` when they need to be reauthorized, and `pending` while the integration is being set up.", "enum": [ "ok", "expired", "pending" ], "example": "ok" }, "ProductAccount": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_account" ], "example": "product_account" }, "attributes": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/sourceTypes-2" }, "external_id": { "type": "string", "description": "The ID of the account at the source (for example, the shop domain for `shopify`, the store hash for `bigcommerce`, or the bucket name for `s3`).", "example": "acme.myshopify.com" }, "name": { "type": [ "string", "null" ], "description": "The name of the account at the source, or of the server for `ftp`, `sftp` and `http`.", "example": "acme" }, "username": { "type": [ "string", "null" ], "description": "The username of the account at the source, when the source provides one.", "example": null }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the account's profile image, when the source provides one.", "example": null }, "site": { "type": [ "string", "null" ], "description": "The store or server URL, or the AWS region for `s3`. `null` when the type doesn't use one.", "example": "https://acme.myshopify.com/" }, "status": { "$ref": "#/components/schemas/productAccountStatuses" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the stored credentials expire, or `null` if they don't expire or the expiry is unknown.", "example": null }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the product account was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the product account was last updated.", "example": "2025-03-14T16:42:07.000Z" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "catalogs": { "type": "object", "description": "The catalogs available in the account (resource type `catalog`, with a `name` attribute), fetched from the source. `data` is only present when `include=catalogs` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "catalog" ], "example": "catalog" }, "id": { "type": "string", "example": "1098765432101234" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "product_feeds": { "type": "object", "description": "The product feeds that sync from this account. Only returned when the access token has the `product_feeds:read` scope. `data` is only present when `include=product_feeds` is requested.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product_feed" ], "example": "product_feed" }, "id": { "type": "string", "example": "12" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of product feeds that sync from this account.", "example": 1 } } } } } } } } } ] }, "ProductAccountCredentials": { "type": "object", "properties": { "site": { "type": [ "string", "null" ], "description": "Where the products are fetched from. Required when `type` is `magento`, `woocommerce` or `http` (an `http://` or `https://` store or server URL), `ftp` (an `ftp://` or `ftps://` URL), `sftp` (an `sftp://` URL), or `s3` (the AWS region of the bucket, such as `us-east-1`). Ignored for the other types. The same site can only be connected once per team.", "example": "https://shop.example.com" }, "access_token": { "type": [ "string", "null" ], "description": "The access token or username, depending on `type`: the API key (`bazaarvoice`), the API access token (`bigcommerce`, `magento`), the consumer key (`woocommerce`), the username (`ftp`, `sftp`, `http`), or `client_id|client_secret|short_code|organization_id` (`salesforce_commerce_cloud`). Required for every type except `s3` (where it must be omitted) and `http` (where it's only required together with `secret`, for basic authentication).", "writeOnly": true, "example": "ck_4f7e2a9c1b3d5e6f" }, "secret": { "type": [ "string", "null" ], "description": "The secret or password, depending on `type`: the consumer secret (`woocommerce`) or the password (`ftp`, `sftp`, `http`). Required when `type` is `woocommerce` or `ftp`, or `http` with an `access_token`. Must be omitted for the other types.", "writeOnly": true, "example": "cs_9a8b7c6d5e4f3a2b" }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the account at the source, for types where it can't be determined automatically: the store hash (`bigcommerce`, checked against the BigCommerce API) or the bucket name (`s3`). Required for those types; derived from the other credentials otherwise.", "example": "acme-product-exports" } } }, "NewProductAccount": { "type": "object", "required": [ "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_account" ], "example": "product_account" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductAccountCredentials" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of product integration. `facebook` and `shopify` accounts can't be created this way; use the authorization flow (`GET /v2/teams/{team_id}/product_accounts/new`) instead.", "enum": [ "bazaarvoice", "bigcommerce", "ftp", "http", "magento", "s3", "salesforce_commerce_cloud", "sftp", "woocommerce" ], "example": "woocommerce" } } } ] } } }, "ProductAccountUpdate": { "type": "object", "required": [ "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the product account being updated.", "example": "7" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product_account" ], "example": "product_account" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductAccountCredentials" } ], "description": "The credentials to change. The `type` of a product account can't be changed; the same per-type rules as on creation apply to the resulting credentials." } } }, "ProductAccountAuthorizationRedirect": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "An MD5 digest of the URL.", "example": "5d41402abc4b2a76b9719d911017c592" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "redirect" ], "example": "redirect" }, "attributes": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL of the third-party authorization page. It's valid for 10 minutes.", "example": "https://acme.myshopify.com/admin/oauth/authorize?client_id=3f2a1b&scope=read_products&state=eyJhbGciOiJIUzI1NiJ9" } } } } }, "ProductTagCoordinates": { "type": "object", "properties": { "x": { "type": [ "string", "number", "null" ], "minimum": 0, "maximum": 100, "description": "The x coordinate of the upper-left corner of the bounding box, as a percentage of the media's width (0 to 100). Returned as a decimal number encoded as a string. Required when any of `y`, `height` or `width` is set.", "example": "50" }, "y": { "type": [ "string", "number", "null" ], "minimum": 0, "maximum": 100, "description": "The y coordinate of the upper-left corner of the bounding box, as a percentage of the media's height (0 to 100). Returned as a decimal number encoded as a string. Required when any of `x`, `height` or `width` is set.", "example": "4.3333333" }, "height": { "type": [ "string", "number", "null" ], "minimum": 0, "maximum": 100, "description": "The height of the bounding box, as a percentage of the media's height (0 to 100). Returned as a decimal number encoded as a string. Required when any of `x`, `y` or `width` is set.", "example": "30" }, "width": { "type": [ "string", "number", "null" ], "minimum": 0, "maximum": 100, "description": "The width of the bounding box, as a percentage of the media's width (0 to 100). Returned as a decimal number encoded as a string. Required when any of `x`, `y` or `height` is set.", "example": "30" } } }, "SocialFeedSource": { "type": "string", "description": "The network or channel the content comes from.", "enum": [ "creator_iq", "custom", "email", "externally_sourced_posts", "facebook", "flickr", "form_submission", "google_news", "hootsuite", "instagram_business", "linkedin", "mission", "pinterest", "public_post", "review_trackers", "rss", "slack", "sms", "spark", "threads", "tiktok", "tiktok_business", "tumblr", "twitter", "youtube" ], "example": "instagram_business" }, "NewProductTag": { "type": "object", "required": [ "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "product_tag" ], "example": "product_tag" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductTagCoordinates" }, { "type": "object", "required": [ "product_id", "source", "external_id" ], "properties": { "product_id": { "type": "integer", "description": "The ID of the product to tag. Must be a product of a product feed you have access to.", "example": 1234 }, "source": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedSource" } ], "description": "The source of the post the product is tagged in." }, "external_id": { "type": "string", "description": "The ID, at the source, of the post the product is tagged in. The post must be on the board.", "example": "1368999965880557573" }, "attachment_id": { "type": [ "string", "null" ], "description": "The ID of the media the product is tagged in, for posts with several media (for example, a carousel). Required when the post has attachments, and must match one of them.", "example": "17895695668004550" } } } ] } } }, "ProductTag": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the product tag.", "example": "311", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product_tag" ], "example": "product_tag" }, "attributes": { "type": "object", "properties": { "x": { "type": [ "string", "null" ], "description": "The x coordinate of the upper-left corner of the bounding box, as a percentage of the media's width (a decimal number encoded as a string), or `null` when the tag has no bounding box.", "example": "50" }, "y": { "type": [ "string", "null" ], "description": "The y coordinate of the upper-left corner of the bounding box, as a percentage of the media's height, or `null` when the tag has no bounding box.", "example": "4.3333333" }, "height": { "type": [ "string", "null" ], "description": "The height of the bounding box, as a percentage of the media's height, or `null` when the tag has no bounding box.", "example": "30" }, "width": { "type": [ "string", "null" ], "description": "The width of the bounding box, as a percentage of the media's width, or `null` when the tag has no bounding box.", "example": "30" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the product tag was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the product tag was last updated.", "example": "2025-03-14T16:42:07.000Z" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "product": { "type": "object", "description": "The tagged product. `data` is only present when `include=product` is requested; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product" ], "example": "product" }, "id": { "type": "string", "example": "1234" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "ProductTagUpdate": { "type": "object", "required": [ "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the product tag being updated.", "example": "311" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "product_tag" ], "example": "product_tag" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ProductTagCoordinates" }, { "type": "object", "properties": { "product_id": { "type": "integer", "description": "The ID of the product to tag instead. Must be a product of a product feed you have access to.", "example": 1234 } } } ], "description": "The attributes to change. The post a product tag belongs to (`source`, `external_id` and `attachment_id`) can't be changed." } } }, "marketingIntegrationSources": { "type": "string", "description": "The external service the marketing integration connects to.", "enum": [ "adobe_experience_manager", "brandfolder", "bynder", "dropbox", "facebook", "google_drive", "hubspot", "mailchimp", "salesforce_marketing_cloud", "twitter", "widen_collective" ], "example": "bynder" }, "MarketingIntegrationAttributes": { "type": "object", "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/marketingIntegrationSources" } ], "readOnly": true }, "status": { "type": "string", "description": "`ready` when the integration can be used, `error` when the stored credentials no longer work, `inactive` when the integration was disabled, and `incomplete` while it's being set up.", "enum": [ "error", "inactive", "ready", "incomplete" ], "example": "ready", "readOnly": true }, "site": { "type": [ "string", "null" ], "format": "uri", "description": "The API endpoint of the marketing integration, for sources that require one.", "example": "https://acme.bynder.com", "readOnly": true }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the account at the source. When not provided, it defaults to the host of `site`.", "example": "acme.bynder.com", "readOnly": true }, "name": { "type": [ "string", "null" ], "description": "The display name of the account at the source, when available.", "example": "Acme Inc.", "readOnly": true }, "username": { "type": [ "string", "null" ], "description": "The username or email address of the account at the source, when available.", "example": "jane.doe@example.com", "readOnly": true }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the account's picture at the source, when available.", "example": "https://cdn.example.com/avatars/acme.png", "readOnly": true } } }, "MarketingIntegration": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the marketing integration.", "example": "318", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "marketing_integration" ] }, "attributes": { "$ref": "#/components/schemas/MarketingIntegrationAttributes" } } }, "marketingIntegrationSourcesForCreate": { "type": "string", "description": "The external service to connect with credentials. `dropbox`, `facebook`, `hubspot`, and `mailchimp` can only be connected using the OAuth flow (see [Authenticate a marketing integration](#operation-v2-teams-team-id-marketing-integrations-new-get)). A `twitter` integration can only be added once per team.", "enum": [ "adobe_experience_manager", "brandfolder", "bynder", "google_drive", "salesforce_marketing_cloud", "twitter", "widen_collective" ], "example": "bynder" }, "NewMarketingIntegration": { "type": "object", "description": "Connects a marketing integration using credentials instead of OAuth. Which attributes are required depends on `source`; see each attribute.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "marketing_integration" ] }, "attributes": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/marketingIntegrationSourcesForCreate" }, "access_token": { "type": "string", "description": "The credentials used to connect to the source. Required when `source` is `adobe_experience_manager` (`username|password`), `brandfolder` (API key), `bynder` or `salesforce_marketing_cloud` (`client_id|client_secret`), `twitter`, or `widen_collective` (API key).", "example": "3f1c9a7e-5d2b-4e8a-9c61-7b0d2e4f8a13|Zm9vYmFyLWNsaWVudC1zZWNyZXQ", "writeOnly": true }, "site": { "type": "string", "format": "uri", "description": "The API endpoint of the source. Required when `source` is `adobe_experience_manager` or `bynder` (must start with `http://` or `https://`), or `salesforce_marketing_cloud` (must match `https://.rest.marketingcloudapis.com`). The same endpoint can only be connected once per team.", "example": "https://acme.bynder.com", "writeOnly": true }, "external_id": { "type": "string", "description": "The ID of the account at the source. Required when `source` is `twitter`.", "example": "1567890123456789012", "writeOnly": true } } } } }, "Folder": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the folder at the source. Its format depends on the marketing integration (for example a path for `dropbox`, or an ad account ID for `facebook`).", "example": "41736560", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "marketing_integration_folder" ] }, "attributes": { "type": "object", "readOnly": true, "properties": { "name": { "type": "string", "description": "The name (or full path) of the folder at the source.", "example": "Marketing assets" } } } } }, "NewMarketingIntegrationRequest": { "type": "object", "description": "Publishes an asset, or every asset of a collection, to a folder of the marketing integration.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "marketing_integration_request" ] }, "attributes": { "type": "object", "required": [ "folder_id" ], "properties": { "asset_id": { "type": "integer", "description": "The ID of the asset to publish. Required unless `collection_id` is provided; can't be combined with `collection_id`.", "example": 2750981, "writeOnly": true }, "collection_id": { "type": "integer", "description": "The ID of a collection whose assets are all published (one request is created per asset). Required unless `asset_id` is provided; can't be combined with `asset_id`.", "example": 1184, "writeOnly": true }, "folder_id": { "type": "string", "description": "The ID of the folder at the source to upload to, as returned by [Retrieve a list of marketing integration folders](#operation-v2-teams-team-id-marketing-integrations-marketing-integration-id-folders-get).", "example": "41736560" }, "marketing_integration_id": { "type": "integer", "description": "Defaults to the marketing integration in the path. If provided, it must be a marketing integration of the team; the asset is still published to the marketing integration in the path.", "example": 318, "writeOnly": true } } } } }, "marketingIntegrationRequestStatuses": { "type": "string", "description": "`pending` while the asset is being uploaded, then `success` or `failure`.", "enum": [ "pending", "success", "failure" ], "example": "pending" }, "MarketingIntegrationRequest": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the marketing integration request.", "example": "70412", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "marketing_integration_request" ] }, "attributes": { "type": "object", "readOnly": true, "properties": { "status": { "$ref": "#/components/schemas/marketingIntegrationRequestStatuses" }, "folder_id": { "type": [ "string", "null" ], "description": "The ID of the folder at the source the asset is uploaded to.", "example": "41736560" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "marketing_integration": { "type": "object", "description": "The marketing integration the asset is published to. Only included when the access token has the `marketing_integrations:read` scope.", "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the marketing integration.", "example": "318" }, "type": { "type": "string", "enum": [ "marketing_integration" ] } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "asset": { "type": "object", "description": "The asset being published. Only included when the access token has the `assets:read` scope.", "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the asset.", "example": "2750981" }, "type": { "type": "string", "enum": [ "asset" ] } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "MixType": { "type": "string", "description": "The resource type. Always `mix`.", "enum": [ "mix" ], "example": "mix" }, "MixAreaItem": { "type": "object", "description": "An item displayed in an area of a scene.", "required": [ "type", "duration" ], "properties": { "type": { "type": "string", "description": "The kind of item to display.", "enum": [ "image", "video", "youtube", "vimeo", "tint", "url" ], "example": "image" }, "duration": { "type": "integer", "description": "How long the item is displayed, in seconds.", "minimum": 1, "example": 10 }, "name": { "type": [ "string", "null" ], "description": "A label that identifies the item.", "example": "Acme logo" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the image, video, YouTube or Vimeo video, or web page. Required when `type` isn't `tint`.", "example": "https://cdn.example.com/mixes/acme-logo.png" }, "tint_id": { "type": [ "integer", "null" ], "description": "The ID of the board to display. Required when `type` is `tint`.", "example": null }, "personalization_id": { "type": [ "integer", "null" ], "description": "The ID of the personalization used to display the board. Only used when `type` is `tint`.", "example": null } } }, "MixScene": { "type": "object", "description": "A scene of the mix, which splits the screen into named areas.", "required": [ "template", "areas" ], "properties": { "layout": { "type": "string", "description": "The name of the layout the template was built from, used by the editor.", "enum": [ "fullscreen", "horizontal", "vertical", "hero_top_right", "hero_top_left", "hero_bottom_right", "hero_bottom_left" ], "example": "horizontal" }, "template": { "type": "string", "description": "The layout of the areas, using the same syntax as the CSS [grid-template](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template) property, except that area names can't be `.`. The area names must be quoted.", "example": "\"logo feed\"" }, "areas": { "type": "object", "description": "The items to display in each area, keyed by area name. Every area named in `template` must be defined, and no other areas are allowed.", "minProperties": 1, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/MixAreaItem" } }, "example": { "logo": [ { "type": "image", "duration": 10, "name": "Acme logo", "url": "https://cdn.example.com/mixes/acme-logo.png" } ], "feed": [ { "type": "tint", "duration": 30, "name": "Summer campaign board", "tint_id": 42, "personalization_id": 7 } ] } } } }, "MixScenes": { "type": "array", "description": "The scenes of the mix, played in order. At least one scene is required.", "minItems": 1, "items": { "$ref": "#/components/schemas/MixScene" } }, "PublicMix": { "type": "object", "description": "The public representation of a mix, which only includes its scenes.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the mix.", "example": "12", "readOnly": true }, "type": { "$ref": "#/components/schemas/MixType" }, "attributes": { "type": "object", "properties": { "scenes": { "$ref": "#/components/schemas/MixScenes" } } } } }, "MixName": { "type": "string", "description": "The name of the mix.", "minLength": 1, "example": "Lobby screen" }, "Mix": { "type": "object", "description": "A mix, a playlist of scenes shown on displays.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the mix.", "example": "12", "readOnly": true }, "type": { "$ref": "#/components/schemas/MixType" }, "attributes": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/MixName" }, "scenes": { "$ref": "#/components/schemas/MixScenes" }, "created_at": { "type": "string", "format": "date-time", "description": "When the mix was created.", "example": "2025-02-10T15:00:00.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the mix was last updated.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true } } } } }, "NewMix": { "type": "object", "description": "The mix to create.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/MixType" }, "attributes": { "type": "object", "required": [ "name", "scenes" ], "properties": { "name": { "$ref": "#/components/schemas/MixName" }, "scenes": { "$ref": "#/components/schemas/MixScenes" } } } } }, "MixBulkDelete": { "type": "object", "description": "A mix to delete, identified by its `id`. Mixes you don't have access to are ignored.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the mix.", "example": "12" }, "type": { "$ref": "#/components/schemas/MixType" } } }, "MixUpdate": { "type": "object", "description": "The mix changes. The `id` is optional; the mix is identified by the URL. `scenes` replaces all existing scenes.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the mix.", "example": "12" }, "type": { "$ref": "#/components/schemas/MixType" }, "attributes": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/MixName" }, "scenes": { "$ref": "#/components/schemas/MixScenes" } } } } }, "personalizationTypes": { "type": "string", "description": "Where the personalization is used.", "enum": [ "embed", "screen", "email", "tile", "ad", "shoppable", "event", "mobile", "not_available", "reviews", "virtual_event" ], "example": "embed" }, "personalizationTheme": { "type": "string", "description": "The theme (layout) the personalization is based on.", "minLength": 1, "example": "classic_v3" }, "PersonalizationDataVersion": { "type": "object", "description": "The personalization's settings, as edited in the personalization editor.", "additionalProperties": true, "properties": { "custom_css": { "type": "string", "description": "Custom CSS applied to the display. Can't contain HTML or JavaScript.", "example": ".tint-post { border-radius: 8px; }" }, "popup_custom_css": { "type": "string", "description": "Custom CSS applied to the post popup. Can't contain HTML or JavaScript.", "example": ".tint-popup { background: #fff; }" } } }, "personalizationStatuses": { "type": "string", "description": "Whether the personalization is `active` or `archived`. Archived personalizations aren't publicly available.", "enum": [ "active", "archived" ], "example": "active" }, "PersonalizationBase": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the personalization.", "readOnly": true, "example": "301" }, "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "attributes": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/personalizationTypes" }, "theme": { "$ref": "#/components/schemas/personalizationTheme" }, "data": { "type": "object", "description": "The personalization's settings (see `draft` and `published`). Unauthenticated requests only receive `published`.", "properties": { "draft": { "$ref": "#/components/schemas/PersonalizationDataVersion" }, "published": { "$ref": "#/components/schemas/PersonalizationDataVersion" } } }, "name": { "type": "string", "description": "The name of the personalization. Only returned to authenticated requests.", "example": "Homepage wall" }, "status": { "allOf": [ { "$ref": "#/components/schemas/personalizationStatuses" } ], "description": "Whether the personalization is `active` or `archived`. Only returned to authenticated requests." }, "tags": { "type": "array", "description": "Tags used to organize personalizations. Only returned to authenticated requests.", "items": { "type": "string" }, "example": [ "website", "spring" ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the personalization was created. Only returned to authenticated requests.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the personalization was last updated. Only returned to authenticated requests.", "example": "2025-03-18T09:12:44.000Z" } } } } }, "PersonalizationData": { "type": "object", "description": "The personalization's settings. `draft` holds the settings being edited and `published` the settings in use. When updating, both must be sent.", "required": [ "draft", "published" ], "properties": { "draft": { "$ref": "#/components/schemas/PersonalizationDataVersion" }, "published": { "$ref": "#/components/schemas/PersonalizationDataVersion" } } }, "PersonalizationWritableAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the personalization. Can't be blank.", "minLength": 1, "example": "Homepage wall" }, "theme": { "$ref": "#/components/schemas/personalizationTheme" }, "type": { "$ref": "#/components/schemas/personalizationTypes" }, "status": { "$ref": "#/components/schemas/personalizationStatuses" }, "tags": { "description": "Tags used to organize personalizations, as an array or a comma-separated string. Replaces all tags.", "anyOf": [ { "title": "List of tags", "type": "array", "items": { "type": "string" } }, { "title": "Comma-separated list", "type": "string" } ], "example": [ "website", "spring" ] }, "data": { "$ref": "#/components/schemas/PersonalizationData" } } }, "NewPersonalization": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/PersonalizationWritableAttributes" }, { "type": "object", "required": [ "theme" ], "properties": { "name": { "type": "string", "default": "Untitled Personalization" }, "type": { "allOf": [ { "$ref": "#/components/schemas/personalizationTypes" } ], "default": "embed" }, "status": { "allOf": [ { "$ref": "#/components/schemas/personalizationStatuses" } ], "default": "active" } } } ] } } }, "PersonalizationIdentifier": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the personalization.", "example": "301" }, "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" } } }, "PersonalizationBulkUpdate": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the personalization to update.", "example": "301" }, "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/PersonalizationWritableAttributes" } ], "description": "The attributes to change. All attributes are validated, but only `name`, `theme`, `tags` and `status` are saved; `type` and `data` are ignored." } } }, "PersonalizationUpdate": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/PersonalizationWritableAttributes" } ], "description": "The attributes to change. Attributes that are left out are unchanged." } } }, "ReplyType": { "type": "string", "description": "The resource type. Always `reply`.", "enum": [ "reply" ], "example": "reply" }, "ReplyText": { "type": "string", "description": "The text of the reply. Plain text only (HTML isn't allowed), from 1 to 500 characters.", "minLength": 1, "maxLength": 500, "example": "Thank you for the kind review, Jane!" }, "ReplyVisibility": { "type": "string", "description": "Whether the reply is shown publicly with the post (`active`) or only visible to the team (`inactive`).", "enum": [ "active", "inactive" ], "example": "active" }, "NewReply": { "type": "object", "description": "The reply to create.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/ReplyType" }, "attributes": { "type": "object", "required": [ "text", "source", "external_id" ], "properties": { "text": { "$ref": "#/components/schemas/ReplyText" }, "source": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedSource" } ], "description": "The source of the post the reply is for (the post's `type` attribute).", "example": "public_post" }, "external_id": { "type": "string", "description": "The ID, at the source, of the post the reply is for (the post's `external_id` attribute). The post must belong to a board you have access to.", "example": "custom_public_1741970527000_4f3a2b1c9d8e" }, "visibility": { "allOf": [ { "$ref": "#/components/schemas/ReplyVisibility" } ], "default": "active" } } } } }, "Reply": { "type": "object", "description": "A reply to a post.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the reply.", "example": "88", "readOnly": true }, "type": { "$ref": "#/components/schemas/ReplyType" }, "attributes": { "type": "object", "properties": { "text": { "$ref": "#/components/schemas/ReplyText" }, "external_id": { "type": "string", "description": "The ID, at the source, of the post the reply is for (the post's `external_id` attribute).", "example": "custom_public_1741970527000_4f3a2b1c9d8e" }, "visibility": { "$ref": "#/components/schemas/ReplyVisibility" }, "created_at": { "type": "string", "format": "date-time", "description": "When the reply was created.", "example": "2025-03-15T10:12:45.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the reply was last updated.", "example": "2025-03-15T10:12:45.000Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "user": { "type": "object", "description": "The user who wrote the reply.", "properties": { "data": { "type": "object", "description": "Only returned when included.", "properties": { "type": { "type": "string", "enum": [ "user" ], "example": "user" }, "id": { "type": "string", "example": "16891" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "ReplyUpdate": { "type": "object", "description": "The reply changes. Only `text` and `visibility` can be changed.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the reply. Optional; the reply is identified by the URL.", "example": "88" }, "type": { "$ref": "#/components/schemas/ReplyType" }, "attributes": { "type": "object", "properties": { "text": { "$ref": "#/components/schemas/ReplyText" }, "visibility": { "$ref": "#/components/schemas/ReplyVisibility" } } } } }, "rightRequestTimeRange": { "type": "object", "description": "A time range. Combine operators to set both bounds.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "Only include right requests after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$gte": { "type": "string", "format": "date-time", "description": "Only include right requests at or after this time.", "example": "2025-03-01T00:00:00.000Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Only include right requests before this time.", "example": "2025-04-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Only include right requests at or before this time.", "example": "2025-03-31T23:59:59.000Z" } } }, "RightRequestStatus": { "type": "string", "description": "The status of the right request. `pending` means the request hasn't been sent yet, `requested` means it was sent and is waiting for the author's reply, `approved` means the author agreed to the terms, `soft_approved` means it was approved without an explicit reply from the author, and `declined` means the author refused. `expired`, `missing`, `deleted`, `error`, and `token_error` mean the request couldn't be completed (for example, because the post was deleted or the account's access token is no longer valid).", "enum": [ "approved", "declined", "deleted", "error", "expired", "missing", "pending", "requested", "soft_approved", "token_error" ], "example": "approved" }, "RightRequestBase": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request" ], "example": "right_request" }, "attributes": { "type": "object", "readOnly": true, "properties": { "hashtag": { "type": [ "string", "null" ], "description": "The hashtag, without the leading `#`, the author must reply with to approve the request. `null` for requests that don't use a hashtag.", "example": "AcmeYes" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the right request was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the right request was last updated.", "example": "2025-03-15T09:12:44.000Z" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the author approved the request, or `null` if it hasn't been approved.", "example": "2025-03-15T09:12:44.000Z", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/RightRequestStatus" } ], "readOnly": true }, "status_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current status expires, for example when a request that is still waiting for a reply will be marked as `expired`. `null` when the status doesn't expire.", "example": null, "readOnly": true }, "text": { "type": [ "string", "null" ], "description": "The message that was sent to the author, followed by the approval message, if any. `null` when no message has been generated.", "example": "Such a great shot! We would love to share this picture on our Instagram page. @janedoe if you agree, please reply #AcmeYes and review our terms at https://example.com/terms/12", "readOnly": true }, "source": { "type": [ "string", "null" ], "description": "The network the post comes from. Note that it uses the post source names, so requests created with the `externally_sourced_posts` source are reported as `externally_sourced_posts_account`.", "enum": [ "creator_iq", "externally_sourced_posts_account", "facebook", "form_submission", "instagram_business", "public_post", "tiktok_business", "twitter", null ], "example": "instagram_business", "readOnly": true }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the post at the source or, for requests created with the `externally_sourced_posts` source, the URL of the Instagram post.", "example": "17895695668004550", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "posts": { "type": "object", "description": "The posts, across all of the team's boards, the rights were requested for. Only present when the access token has the `posts:read` scope. `data` is only returned when `include=posts` is used.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "example": "987654" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "assets": { "type": "object", "description": "The assets created from the post once the request was approved. Only present when the access token has the `assets:read` scope. `data` is only returned when `include=assets` is used.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asset" ], "example": "asset" }, "id": { "type": "string", "example": "789" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "template": { "type": "object", "description": "The right request template used to generate the message. Only present when the access token has the `right_request_templates:read` scope. `data` is only returned when `include=template` is used, and is `null` when a custom template was used.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "right_request_template" ], "example": "right_request_template" }, "id": { "type": "string", "example": "34" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "RightRequest": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "$ref": "#/components/schemas/RightRequestBase" } ], "example": { "id": "1234", "type": "right_request", "attributes": { "hashtag": "AcmeYes", "created_at": "2025-03-14T16:42:07.000Z", "updated_at": "2025-03-15T09:12:44.000Z", "approved_at": "2025-03-15T09:12:44.000Z", "status": "approved", "status_expires_at": null, "text": "Such a great shot! We would love to share this picture on our Instagram page. @janedoe if you agree, please reply #AcmeYes and review our terms at https://example.com/terms/12", "source": "instagram_business", "external_id": "17895695668004550" }, "relationships": { "posts": { "meta": { "included": false } }, "assets": { "meta": { "included": false } }, "template": { "meta": { "included": false } } } } }, "RightRequestSourceForCreate": { "type": "string", "description": "Where the post comes from, which also determines how the request is sent: `instagram_business` sends a direct message from an Instagram Business account, `externally_sourced_posts` requests the rights to an Instagram post that isn't in any board yet (by URL), `tiktok_business` replies from a TikTok Business account, and `twitter` replies from an X (Twitter) account.", "enum": [ "externally_sourced_posts", "instagram_business", "tiktok_business", "twitter" ], "example": "instagram_business" }, "NewRightRequest": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request" ], "example": "right_request" }, "attributes": { "type": "object", "required": [ "account_id", "external_id", "hashtag", "right_request_term_id", "source" ], "properties": { "source": { "$ref": "#/components/schemas/RightRequestSourceForCreate" }, "external_id": { "type": "string", "description": "The ID of the post at the source. When `source` is `externally_sourced_posts`, the URL of an Instagram post on `instagram.com` instead (its query string is removed). For other sources, the post must exist in one of the team's boards. Rejected if an active (`pending`, `requested`, `approved`, or `soft_approved`) right request already exists for the same post.", "minLength": 1, "example": "17895695668004550" }, "account_id": { "type": "integer", "description": "The ID of the account used to send the request, which must be connected by the current user: an X (Twitter) account when `source` is `twitter`, a TikTok Business account when `source` is `tiktok_business`, and an Instagram Business account otherwise.", "minimum": 1, "example": 56 }, "subaccount_id": { "type": [ "string", "null" ], "description": "The ID of the Instagram Business subaccount (page) of `account_id` used to send the request. Required unless `source` is `twitter` or `tiktok_business`, in which case it must be omitted.", "example": "464297566935356|17841401839964064" }, "hashtag": { "type": "string", "description": "The hashtag, without the leading `#`, the author must reply with to approve the request. Must be a single valid hashtag (no spaces or punctuation other than underscores).", "minLength": 1, "example": "AcmeYes" }, "right_request_term_id": { "type": "integer", "description": "The ID of one of the team's right request terms the author is asked to agree to.", "minimum": 1, "example": 12 }, "template_id": { "type": "integer", "description": "The ID of the right request template used to generate the message sent to the author. Required unless `template` is given; the two are mutually exclusive.", "example": 34 }, "template": { "type": "string", "description": "A custom Liquid template used to generate the message sent to the author, instead of a saved template. Required unless `template_id` is given; the two are mutually exclusive. Available variables: `{{approval_keyword}}` (the hashtag, with `#`), `{{terms.url}}`, `{{account.subaccount.username}}`, `{{source}}`, and `{{posts}}` (each with `url`, `attachment_type`, and `author.username`). The legacy variables `{{hashtag}}`, `{{terms_url}}`, `{{username}}` (the post author, with `@`), and `{{mention}}` (the subaccount, with `@`) are still supported.", "example": "Such a great shot! We would love to share this picture on our Instagram page. @{{posts.first.author.username}} if you agree, please reply {{approval_keyword}} and review our terms at {{terms.url}}" }, "tint_id": { "type": "integer", "description": "The ID of the board in which to create the post once the request is approved. Required when `source` is `externally_sourced_posts`, and must be omitted otherwise.", "example": 42 } } } } }, "RightRequestsMetric": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "A random identifier generated for each metric row. It isn't stable across requests.", "example": "f42c2ba98b72afee69976d52875fe313", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "right_requests_metric" ], "example": "right_requests_metric" }, "attributes": { "type": "object", "readOnly": true, "properties": { "count": { "type": "integer", "description": "The number of right requests created or approved (depending on `measure_name`) in this group.", "example": 128 }, "dimensions": { "type": [ "object", "null" ], "description": "The values of the grouping dimensions for this row, or `null` when the `group` query parameter isn't used (or only groups by `account_id` or `subaccount_id`, which are exposed through the `account` relationship instead).", "properties": { "source": { "type": "string", "description": "The source of the right requests. Only present when grouping by `source`.", "example": "instagram_business" }, "user_id": { "type": [ "string", "null" ], "description": "The ID of the user who created the right requests, as a string. Only present when grouping by `user_id`.", "example": "7" }, "time": { "type": "string", "description": "The start of the time bucket (UTC), truncated to the requested unit. Only present when grouping by a `time` dimension other than `time.day_of_week` and `time.hour_of_day`.", "example": "2025-03-14 00:00:00.000000000" }, "day_of_week": { "type": "integer", "description": "The day of the week, from 0 (Sunday) to 6 (Saturday). Only present when grouping by `time.day_of_week`.", "minimum": 0, "maximum": 6, "example": 5 }, "hour_of_day": { "type": "integer", "description": "The hour of the day (UTC), from 0 to 23. Only present when grouping by `time.hour_of_day`.", "minimum": 0, "maximum": 23, "example": 16 }, "time.day_of_week": { "type": "integer", "description": "Same as `day_of_week`.", "minimum": 0, "maximum": 6, "example": 5 }, "time.hour_of_day": { "type": "integer", "description": "Same as `hour_of_day`.", "minimum": 0, "maximum": 23, "example": 16 } }, "example": { "source": "instagram_business", "time": "2025-03-14 00:00:00.000000000" } } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "user": { "type": "object", "description": "The user who created the right requests. Only present when grouping by `user_id` and the access token has the `users:read` scope.", "properties": { "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "account": { "type": "object", "description": "The account used to send the right requests. Only present when grouping by `account_id` and the access token has the `accounts:read` scope.", "properties": { "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "RightRequestTermBase": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request_term" ], "example": "right_request_term" }, "attributes": { "type": "object", "readOnly": true, "properties": { "name": { "type": "string", "description": "The internal name of the terms, used to pick them when creating a right request.", "example": "Standard content license" }, "title": { "type": [ "string", "null" ], "description": "The title displayed on the terms page (in its `title` HTML element). Omitted when a document is attached.", "example": "Acme Inc. Content License Agreement" }, "text": { "type": [ "string", "null" ], "description": "The terms, formatted with Markdown. Omitted when a document is attached.", "example": "# Content License Agreement\n\nBy replying with the approval hashtag, you grant Acme Inc. a non-exclusive, royalty-free, worldwide license\nto use, reproduce, and display your post and its content on its websites, social media accounts, and\nmarketing materials. You confirm that you own the content and that it doesn't infringe on anyone's rights." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the logo displayed on the terms page, or `null` for no logo.", "example": "https://cdn.example.com/acme/logo.png" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The short URL of the public terms page sent to the author. Generated when the terms are created.", "example": "https://example.com/terms/12" }, "status": { "type": "string", "description": "`published` terms can be used in new right requests. Deleted terms are `archived`; they are only returned by the endpoint that retrieves a single right request term.", "enum": [ "archived", "published" ], "example": "published" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the terms were created.", "example": "2025-03-01T10:15:30.000Z" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board the terms are limited to. Only present when the access token has the `tints:read` scope.", "properties": { "data": { "type": [ "object", "null" ], "description": "The board, or `null` when the terms can be used with any board.", "properties": { "type": { "type": "string", "enum": [ "tint" ], "example": "tint" }, "id": { "type": "string", "example": "42" } }, "example": null } } }, "document": { "type": "object", "description": "The document containing the terms. Only present when a document is attached.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "upload" ], "example": "upload" }, "id": { "type": "string", "description": "The signed ID of the attached document.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6NDIsInB1ciI6ImJsb2JfaWQifX0=--9f8e7d6c5b4a39281706f5e4d3c2b1a098765432" } } } } } } } } }, "RightRequestTerm": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "$ref": "#/components/schemas/RightRequestTermBase" } ], "example": { "id": "12", "type": "right_request_term", "attributes": { "name": "Standard content license", "title": "Acme Inc. Content License Agreement", "text": "# Content License Agreement\n\nBy replying with the approval hashtag, you grant Acme Inc. a non-exclusive, royalty-free, worldwide license to\nuse, reproduce, and display your post and its content on its websites, social media accounts, and marketing\nmaterials. You confirm that you own the content and that it doesn't infringe on anyone's rights.", "logo_url": "https://cdn.example.com/acme/logo.png", "url": "https://example.com/terms/12", "status": "published", "created_at": "2025-03-01T10:15:30.000Z" }, "relationships": { "tint": { "data": null } } } }, "NewRightRequestTerm": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request_term" ], "example": "right_request_term" }, "attributes": { "type": "object", "description": "Either `text` or `document` is required, but not both.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The internal name of the terms, used to pick them when creating a right request.", "minLength": 1, "example": "Standard content license" }, "title": { "type": [ "string", "null" ], "description": "The title displayed on the terms page (in its `title` HTML element). Can't contain HTML. Must be omitted when `document` is given.", "example": "Acme Inc. Content License Agreement" }, "text": { "type": [ "string", "null" ], "description": "The terms, formatted with Markdown. Can't contain HTML. Required, with at least 100 characters, unless `document` is given, in which case it must be omitted.", "minLength": 100, "example": "# Content License Agreement\n\nBy replying with the approval hashtag, you grant Acme Inc. a non-exclusive, royalty-free, worldwide license\nto use, reproduce, and display your post and its content on its websites, social media accounts, and\nmarketing materials. You confirm that you own the content and that it doesn't infringe on anyone's rights." }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The HTTP or HTTPS URL of the logo displayed on the terms page.", "example": "https://cdn.example.com/acme/logo.png" }, "document": { "type": "string", "description": "The signed ID, as returned by a direct upload for right request terms, of a PDF or Word document (up to 20 MB) containing the terms. When given, `text` and `title` must be omitted.", "writeOnly": true, "example": "eyJfcmFpbHMiOnsiZGF0YSI6NDIsInB1ciI6ImJsb2JfaWQifX0=--9f8e7d6c5b4a39281706f5e4d3c2b1a098765432" } } } } }, "RightRequestTemplateBase": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request_template" ], "example": "right_request_template" }, "attributes": { "type": "object", "readOnly": true, "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the template, or `null` if it doesn't have one.", "example": "Instagram repost" }, "hashtag": { "type": "string", "description": "The hashtag, without the leading `#`, the author must reply with to approve the request. `yes` when the template doesn't define one.", "example": "AcmeYes" }, "template": { "type": "string", "description": "The Liquid template used to generate the message sent to the author. See the `template` attribute of right requests for the available variables.", "example": "Such a great shot! We would love to share this picture on our Instagram page. {{username}} if you agree, please reply {{approval_keyword}} and review our terms at {{terms.url}}" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the template was created.", "example": "2025-02-20T14:05:12.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the template was last updated.", "example": "2025-03-10T08:30:45.000Z" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board the template is limited to. Only present when the access token has the `tints:read` scope.", "properties": { "data": { "type": [ "object", "null" ], "description": "The board, or `null` when the template can be used with any board.", "properties": { "type": { "type": "string", "enum": [ "tint" ], "example": "tint" }, "id": { "type": "string", "example": "42" } }, "example": null } } } } } } }, "RightRequestTemplate": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "$ref": "#/components/schemas/RightRequestTemplateBase" } ], "example": { "id": "34", "type": "right_request_template", "attributes": { "name": "Instagram repost", "hashtag": "AcmeYes", "template": "Such a great shot! We would love to share this picture on our Instagram page. {{username}} if you agree, please reply {{approval_keyword}} and review our terms at {{terms.url}}", "created_at": "2025-02-20T14:05:12.000Z", "updated_at": "2025-03-10T08:30:45.000Z" }, "relationships": { "tint": { "data": null } } } }, "RightRequestTemplateAttributesForWrite": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the template.", "example": "Instagram repost" }, "hashtag": { "type": "string", "description": "The hashtag, without the leading `#`, the author must reply with to approve the request. Must be a single valid hashtag (no spaces or punctuation other than underscores).", "minLength": 1, "example": "AcmeYes" }, "template": { "type": "string", "description": "The Liquid template used to generate the message sent to the author. Available variables: `{{approval_keyword}}` (the hashtag, with `#`), `{{terms.url}}`, `{{account.subaccount.username}}`, `{{source}}`, and `{{posts}}` (each with `url`, `attachment_type`, and `author.username`). The legacy variables `{{hashtag}}`, `{{terms_url}}`, `{{username}}` (the post author, with `@`), and `{{mention}}` (the subaccount, with `@`) are still supported.", "minLength": 1, "example": "Such a great shot! We would love to share this picture on our Instagram page. {{username}} if you agree, please reply {{approval_keyword}} and review our terms at {{terms.url}}" } } }, "NewRightRequestTemplate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request_template" ], "example": "right_request_template" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/RightRequestTemplateAttributesForWrite" }, { "type": "object", "required": [ "hashtag", "template" ] } ] } } }, "RightRequestTemplateUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the template. Optional; the template to update is identified by the `right_request_template_id` path parameter.", "example": "34" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "right_request_template" ], "example": "right_request_template" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/RightRequestTemplateAttributesForWrite" } ], "description": "Only the attributes given are changed. `hashtag` and `template` can't be set to an empty value." } } }, "TeamAttributes": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the team.", "example": "Acme Inc." }, "image_url": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https?://", "description": "The URL of the team's logo. Must be an `http` or `https` URL. `null` when not set.", "example": "https://cdn.example.com/logos/acme.png" }, "url_shortener_type": { "type": "string", "description": "The service used to shorten links. `bitly` requires a `url_shortener_access_token`.", "enum": [ "tintly", "bitly" ], "default": "tintly", "example": "tintly" }, "onboarding": { "type": "string", "description": "The progress of the team's onboarding.", "enum": [ "started", "skipped", "completed" ], "default": "started", "example": "completed" }, "shared_tags": { "description": "Whether tags from a post are copied to the associated assets once rights are acquired: `true` copies every tag, `false` copies none, and an array of tags copies only those tags.", "oneOf": [ { "title": "All or none", "type": "boolean" }, { "title": "List of tags", "type": "array", "items": { "type": "string" } } ], "default": false, "example": [ "summer", "ugc" ] }, "mcp_enabled": { "type": "boolean", "description": "Whether AI assistants can access the team's data through the MCP server. Changing it requires the `team_security` permission.", "default": false, "example": true } } }, "TeamSsoAttributes": { "type": "object", "description": "Single sign-on (SAML and OpenID Connect) settings.", "properties": { "saml_enabled": { "type": "boolean", "description": "Whether signing in using SAML is enabled.", "default": false, "example": true }, "idp_entity_id": { "type": [ "string", "null" ], "description": "SAML - The Identity Provider entity ID (Identity Provider Issuer). `null` when not set.", "example": "https://idp.example.com/metadata" }, "idp_sso_target_url": { "type": [ "string", "null" ], "format": "uri", "description": "SAML - The Identity Provider Single Sign-On URL. `null` when not set.", "example": "https://idp.example.com/sso/saml" }, "idp_cert": { "type": [ "string", "null" ], "description": "SAML - The X.509 certificate of the Identity Provider, in PEM format. `null` when not set.", "example": "-----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAwIBAgIEbGx0ZTANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdV\n-----END CERTIFICATE-----" }, "force_authn": { "type": "boolean", "description": "SAML - Whether the Identity Provider should re-authenticate users even when they already have a session with it (`ForceAuthn`).", "default": false, "example": false }, "authn_requests_signed": { "type": "boolean", "description": "SAML - Whether the authentication requests sent to the Identity Provider are signed.", "default": false, "example": false }, "want_assertions_signed": { "type": "boolean", "description": "SAML - Whether the assertions from the Identity Provider must be signed.", "default": false, "example": true }, "want_assertions_encrypted": { "type": "boolean", "description": "SAML - Whether the assertions from the Identity Provider must be encrypted.", "default": false, "example": false }, "saml_jit_provisioning": { "type": "boolean", "description": "SAML - Whether users who sign in using SAML for the first time are added to the team automatically (just-in-time provisioning).", "default": false, "example": true }, "oidc_enabled": { "type": "boolean", "description": "Whether signing in using OpenID Connect is enabled. When `true`, `oidc_identifier`, `oidc_secret`, `oidc_scope` and `oidc_issuer` are required.", "default": false, "example": false }, "oidc_identifier": { "type": [ "string", "null" ], "description": "OpenID Connect - The client ID issued by the provider. `null` when not set.", "example": "0oa1b2c3d4e5f6g7h8i9" }, "oidc_secret": { "type": [ "string", "null" ], "description": "OpenID Connect - The client secret issued by the provider. `null` when not set.", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0" }, "oidc_scope": { "type": [ "string", "null" ], "description": "OpenID Connect - The space-separated scopes to request from the provider. `null` when not set.", "example": "openid email profile" }, "oidc_issuer": { "type": [ "string", "null" ], "description": "OpenID Connect - The issuer URL of the provider. When none of the endpoint URLs are set, they are discovered from the issuer. `null` when not set.", "example": "https://login.example.com" }, "oidc_authorization_endpoint": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https://", "description": "OpenID Connect - The authorization endpoint URL. Must be an `https` URL. `null` when not set.", "example": "https://login.example.com/oauth2/v1/authorize" }, "oidc_token_endpoint": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https://", "description": "OpenID Connect - The token endpoint URL. Must be an `https` URL. `null` when not set.", "example": "https://login.example.com/oauth2/v1/token" }, "oidc_userinfo_endpoint": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https://", "description": "OpenID Connect - The UserInfo endpoint URL. Must be an `https` URL. `null` when not set.", "example": "https://login.example.com/oauth2/v1/userinfo" }, "oidc_jwks_uri": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https://", "description": "OpenID Connect - The JSON Web Key Set URL. Must be an `https` URL. `null` when not set.", "example": "https://login.example.com/oauth2/v1/keys" } } }, "RolePermission": { "type": "string", "description": "A permission granted by a role. Permissions that start with `new_` (and `accounts_new`) automatically grant access to resources created in the future, and the suffixes `_r`, `_cu` and `_d` mean read, create/update and delete respectively. `all` grants every permission.", "enum": [ "all", "accounts_create", "accounts_delete", "accounts_new", "accounts_read", "activities_cu", "activities_d", "activities_r", "anomaly_detection", "anomaly_detection_cu", "anomaly_detection_d", "assets_archive", "assets_delete", "assets_edit", "assets_publish", "assets_read", "campaigns", "campaigns_cu", "campaigns_d", "challenge", "challenge_cu", "challenge_d", "change_billing", "community_u", "create_tint", "customers", "customers_cu", "customers_d", "delete_tint", "design", "design_cu", "design_d", "domains_cu", "domains_d", "domains_r", "experiences_cu", "experiences_d", "experiences_publish", "experiences_r", "fonts_cu", "fonts_d", "fonts_r", "form_submissions_d", "form_submissions_r", "forms_cu", "forms_d", "forms_publish", "forms_r", "mixes_cu", "mixes_d", "mixes_r", "moderate_tint", "moderation", "moderation_cu", "modify_tint", "new_collections", "new_domains", "new_experiences", "new_fonts", "new_forms", "new_mixes", "new_oauth_applications", "new_personalizations", "new_product_accounts", "new_product_feeds", "new_tints_access", "new_webhooks", "notifications", "notifications_cu", "notifications_d", "oauth_applications_cu", "oauth_applications_d", "oauth_applications_r", "ownership_tint", "personalizations_cu", "personalizations_d", "personalizations_r", "posts_tag_product", "product_accounts_cu", "product_accounts_d", "product_accounts_r", "product_feeds_cu", "product_feeds_d", "product_feeds_r", "products_cu", "products_d", "products_r", "program_settings", "program_settings_cu", "program_settings_d", "replies_cu", "replies_d", "replies_r", "reports", "rewards_cu", "rewards_d", "rewards_r", "roles_cu", "roles_d", "roles_r", "schemas_cu", "schemas_d", "schemas_r", "streak", "streak_cu", "streak_d", "team_security", "teams_users_cu", "teams_users_d", "teams_users_r", "transactions_cu", "transactions_d", "transactions_r", "webhooks_cu", "webhooks_d", "webhooks_r" ], "example": "moderate_tint" }, "TeamRelationships": { "type": "object", "readOnly": true, "description": "Resources related to the team. Unless stated otherwise, `data` is only present when the relationship is requested with `include`; to-many relationships then contain the first page of resources.", "properties": { "role": { "type": "object", "description": "The role the authenticated user is assigned in the team.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "example": "3" } } } } }, "plan": { "type": "object", "description": "The team's effective plan (its limits and features). The plan resource shares the team's ID.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "plan" ] }, "id": { "type": "string", "example": "1" } } } } }, "agent": { "type": "object", "description": "The support agent assigned to the team. `data` is `null` when none is assigned.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "example": "7" } } } } }, "tints": { "type": "object", "description": "The boards the authenticated user has access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "tint" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "active_tints_count": { "type": "integer", "description": "The number of active boards in the team.", "example": 4 }, "count": { "type": "integer", "description": "The number of boards in the team.", "example": 6 } } } } }, "social_feeds": { "type": "object", "description": "The social feeds of the boards the authenticated user has access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "social_feed" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "active_count": { "type": "integer", "description": "The number of active social feeds in the team.", "example": 12 }, "inactive_count": { "type": "integer", "description": "The number of inactive social feeds in the team.", "example": 3 }, "access_error_count": { "type": "integer", "description": "The number of social feeds in the team that can't be refreshed because of an access error.", "example": 1 }, "active_social_feeds_count": { "type": "integer", "description": "Deprecated. Use `active_count` instead.", "deprecated": true, "example": 12 }, "inactive_social_feeds_count": { "type": "integer", "description": "Deprecated. Use `inactive_count` instead.", "deprecated": true, "example": 3 } } } } }, "posts": { "type": "object", "description": "Always an empty list; only used to return usage information in `meta`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "posts_ingested_from_beginning_of_month": { "type": "integer", "description": "The number of posts ingested by the team since the beginning of the month.", "example": 18250 } } } } }, "assets": { "type": "object", "description": "The team's assets.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of assets in the team.", "example": 320 }, "uploaded_count": { "type": "integer", "description": "The number of assets uploaded directly to the team.", "example": 45 }, "total": { "type": "integer", "description": "Deprecated. Use `count` instead.", "deprecated": true, "example": 320 }, "uploaded_total": { "type": "integer", "description": "Deprecated. Use `uploaded_count` instead.", "deprecated": true, "example": 45 } } } } }, "mixes": { "type": "object", "description": "The mixes the authenticated user has access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "mix" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of mixes in the team.", "example": 2 } } } } }, "forms": { "type": "object", "description": "The forms the authenticated user has access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of forms in the team.", "example": 5 }, "published_count": { "type": "integer", "description": "The number of published forms in the team.", "example": 3 } } } } }, "personalizations": { "type": "object", "description": "The personalizations the authenticated user has access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ] }, "id": { "type": "string", "example": "1" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of personalizations in the team.", "example": 8 } } } } } } }, "Team": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "team" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/TeamAttributes" }, { "$ref": "#/components/schemas/TeamSsoAttributes" }, { "type": "object", "required": [ "name", "image_url", "url_shortener_type", "onboarding", "shared_tags", "plan_expires_at", "plan_changed_at", "self_service", "rewards_platform_id", "rewards_platform_key", "permissions", "created_at", "updated_at" ], "properties": { "plan": { "type": "string", "readOnly": true, "description": "The identifier of the team's plan. The plan is also available through the `plan` relationship.", "example": "tint_professional" }, "plan_expires_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the team's plan expires. `null` when it doesn't expire.", "example": "2026-03-14T00:00:00.000Z" }, "plan_changed_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the team's plan was last changed. `null` when it never changed.", "example": "2025-03-14T16:42:07.000Z" }, "self_service": { "type": "boolean", "readOnly": true, "description": "Whether the team is on a self-service plan.", "example": false }, "rewards_platform_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The team's merchant ID on the rewards platform. `null` when not configured.", "example": "mrc_4f7a2b9c" }, "rewards_platform_key": { "type": [ "string", "null" ], "readOnly": true, "description": "The team's merchant key on the rewards platform. `null` when not configured.", "example": "7d1e3c5a9b2f4e6d8c0a1b3d5f7e9c2a" }, "permissions": { "type": "array", "readOnly": true, "uniqueItems": true, "description": "The permissions the authenticated user has in the team, from their role. A role with the `all` permission lists every permission.", "items": { "$ref": "#/components/schemas/RolePermission" }, "example": [ "moderate_tint", "modify_tint", "assets_read" ] }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the authenticated user joined the team.", "example": "2024-11-02T10:05:44.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the authenticated user's membership in the team was last updated.", "example": "2025-03-14T16:42:07.000Z" } } } ] }, "relationships": { "$ref": "#/components/schemas/TeamRelationships" } } } ] }, "TeamWritableAttributes": { "type": "object", "properties": { "url_shortener_access_token": { "type": "string", "writeOnly": true, "description": "The Bitly access token. Required when `url_shortener_type` is `bitly`, and must be omitted otherwise.", "example": "3f2a9c0e7b6d4e1f8a5c2b9d0e7f6a1b3c4d5e6f" }, "billing_platform_token": { "type": "string", "writeOnly": true, "description": "A payment token for the team's credit card, generated with Chargify.js.", "example": "tok_9s8d7f6g5h4j3k2l" } } }, "NewTeam": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "team" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/TeamAttributes" }, { "$ref": "#/components/schemas/TeamWritableAttributes" }, { "type": "object", "required": [ "name", "plan", "billing_platform_type", "billing_platform_token" ], "properties": { "plan": { "type": "string", "description": "The self-service plan to subscribe to.", "enum": [ "free", "tint_starter", "tint_growth", "tint_professional", "trial_plan_3" ], "example": "tint_starter" }, "billing_platform_type": { "type": "string", "description": "The billing platform that processes the payment token.", "enum": [ "chargify" ], "example": "chargify" } } } ] } } }, "TeamUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the team. Optional; the team is identified by the URL.", "example": "1" }, "type": { "type": "string", "enum": [ "team" ] }, "attributes": { "description": "The attributes to change. Attributes that are omitted are left unchanged.", "allOf": [ { "$ref": "#/components/schemas/TeamAttributes" }, { "$ref": "#/components/schemas/TeamSsoAttributes" }, { "$ref": "#/components/schemas/TeamWritableAttributes" } ] } } }, "DomainExperienceIdentifier": { "type": "object", "description": "A resource identifier for an experience.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "experience" ] }, "id": { "type": "string", "description": "The ID of the experience.", "example": "318" } } }, "Domain": { "description": "A custom domain on which the team's experiences can be published.", "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the domain.", "example": "42", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "domain" ] }, "attributes": { "type": "object", "required": [ "name", "status", "created_at", "updated_at" ], "properties": { "name": { "type": "string", "format": "hostname", "description": "The fully qualified domain name. Domain names are unique across all teams (case-insensitive).", "example": "stories.example.com", "readOnly": true }, "status": { "type": "string", "description": "The state of the domain's SSL certificate. `pending` while the certificate is being issued (shortly after the domain is created or renamed), then `valid`.", "enum": [ "pending", "valid" ], "example": "valid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When the domain was created.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the domain was last updated.", "example": "2025-03-18T09:15:32.000Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "required": [ "default_experience" ], "properties": { "default_experience": { "type": "object", "description": "The experience shown at the root of the domain. Always present; `data` is `null` when no default experience is set. Add `include=default_experience` to embed the experience in `included`.", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/DomainExperienceIdentifier" }, { "type": "null" } ] } } } } }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the domain.", "example": "https://api.tintup.com/v2/teams/1/domains/42" } } } } } ] }, "experienceTypes": { "type": "string", "description": "The kind of experience.", "enum": [ "sweepstakes", "contest", "countdown", "landing_page", "tag_o_war", "contributor", "poll", "counter", "link_in_bio", "survey", "event", "influencer" ], "example": "sweepstakes" }, "experienceAnalyticsTypes": { "type": [ "string", "null" ], "description": "The analytics provider `analytics_id` belongs to. Required when `analytics_id` is set.", "enum": [ "google_analytics", "google_tag_manager", null ], "example": "google_tag_manager" }, "experienceCaptchaTypes": { "type": [ "string", "null" ], "description": "The captcha provider used to protect the form. `captcha_type`, `captcha_public_key` and `captcha_private_key` must be set together.", "enum": [ "google_recaptcha", "h_captcha", null ], "example": null }, "ExperiencePublicAttributes": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/experienceTypes" }, "title": { "type": [ "string", "null" ], "description": "The page title, shown in the browser tab and search results.", "example": "Win a trip to Hawaii" }, "description": { "type": [ "string", "null" ], "description": "The page description, used in search results and link previews.", "example": "Enter our summer sweepstakes for a chance to win a trip for two." }, "analytics_id": { "type": [ "string", "null" ], "description": "The analytics measurement ID (`G-…` for Google Analytics, `GTM-…` for Google Tag Manager).", "example": "GTM-5XK7Q2P" }, "analytics_type": { "$ref": "#/components/schemas/experienceAnalyticsTypes" }, "captcha_type": { "$ref": "#/components/schemas/experienceCaptchaTypes" }, "captcha_public_key": { "type": [ "string", "null" ], "description": "The captcha provider's public site key.", "example": null }, "cookie_consent": { "type": "boolean", "description": "Whether a cookie consent banner is displayed.", "example": true }, "noindex": { "type": "boolean", "description": "Whether search engines are asked not to index the experience.", "example": false }, "favicon_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the favicon.", "example": "https://cdn.example.com/favicons/acme.png" }, "maximum_image_size": { "type": "integer", "description": "The maximum size of an uploaded image in bytes.", "readOnly": true, "example": 104857600 }, "maximum_video_size": { "type": "integer", "description": "The maximum size of an uploaded video in bytes.", "readOnly": true, "example": 1048576000 }, "bypass_mime_type_validation": { "type": "boolean", "description": "Whether uploads to the experience skip MIME type validation.", "readOnly": true, "example": false } } }, "experienceStatuses": { "type": "string", "description": "`active` experiences can be published; `archived` experiences are taken offline.", "enum": [ "active", "archived" ], "example": "active" }, "ExperienceSections": { "type": "array", "description": "The experience's sections, in display order. Each section is an object with a `sectionType`.", "items": { "type": "object", "additionalProperties": true }, "example": [ { "sectionType": "banner", "data": { "content": { "title": "Win a trip to Hawaii" } } }, { "sectionType": "form", "data": { "content": { "fields": [ { "key": "email", "type": "email" } ] } } } ] }, "ExperienceData": { "type": "object", "description": "The content of the experience, as edited in the Experience Builder. Each part has a `draft` and a `published` version. Publishing (changing `published` to a non-empty list) requires the experience to be `active` and room in the plan's limit of published experiences.", "additionalProperties": true, "properties": { "draft": { "$ref": "#/components/schemas/ExperienceSections" }, "published": { "$ref": "#/components/schemas/ExperienceSections" }, "locales": { "type": "object", "description": "The locales the experience is available in.", "properties": { "draft": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "example": [ { "value": "en", "isDefault": true } ] }, "published": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "example": [ { "value": "en", "isDefault": true } ] } } }, "translations": { "type": "object", "description": "Translated strings, keyed by locale.", "properties": { "draft": { "type": "object", "additionalProperties": true, "example": { "en": {} } }, "published": { "type": "object", "additionalProperties": true, "example": { "en": {} } } } }, "customFonts": { "type": "object", "description": "The custom fonts used by the experience.", "properties": { "draft": { "type": "object", "additionalProperties": true, "example": {} }, "published": { "type": "object", "additionalProperties": true, "example": {} } } } } }, "ExperiencePublicLinks": { "type": "object", "readOnly": true, "properties": { "public": { "type": "string", "format": "uri", "description": "The public URL of the experience. Only present when the experience has a `slug`.", "example": "https://contests.example.com/summer-sweepstakes" } } }, "ExperienceBase": { "type": "object", "description": "An experience, as returned to authenticated requests.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the experience.", "readOnly": true, "example": "42" }, "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ExperiencePublicAttributes" }, { "type": "object", "properties": { "name": { "type": "string", "description": "An internal name used to tell experiences apart.", "example": "Summer Sweepstakes 2025" }, "status": { "$ref": "#/components/schemas/experienceStatuses" }, "slug": { "type": [ "string", "null" ], "description": "The part of the public URL that identifies the experience. Unique within the team.", "example": "summer-sweepstakes" }, "data": { "$ref": "#/components/schemas/ExperienceData" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the experience was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the experience was last updated.", "example": "2025-03-18T09:12:44.000Z" } } } ] }, "relationships": { "type": "object", "readOnly": true, "properties": { "domain": { "type": "object", "description": "The custom domain the experience is served from. `data` is always present.", "properties": { "data": { "type": [ "object", "null" ], "description": "`null` when the experience uses the default domain.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "domain" ], "example": "domain" }, "id": { "type": "string", "description": "The ID of the domain.", "example": "3" } } } } }, "form_submission_keys": { "type": "object", "description": "The keys of the experience's form fields and submitted data. `data` is only present when `form_submission_keys` is listed in the `include` query parameter; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form_submission_key" ], "example": "form_submission_key" }, "id": { "type": "string", "description": "The key.", "example": "email" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "user": { "type": "object", "description": "The team that owns the experience (named `user` for backward compatibility). Only present when the access token has the `users:read` scope. `data` is only present when `user` is listed in the `include` query parameter; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "team" ], "example": "team" }, "id": { "type": "string", "description": "The ID of the team.", "example": "1" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "submissions": { "type": "object", "description": "The experience's form submissions. Only present when the access token has the `form_submissions:read` scope. `data` (the first page of submissions) and the pagination links are only present when `submissions` is listed in the `include` query parameter.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form_submission" ], "example": "form_submission" }, "id": { "type": "string", "description": "The ID of the form submission.", "example": "88213" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL of the experience's form submissions.", "example": "https://api.tintup.com/v2/teams/1/experiences/42/form_submissions" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page of submissions. Only present when there are submissions.", "example": "https://api.tintup.com/v2/teams/1/experiences/42/form_submissions" }, "next": { "type": "string", "format": "uri", "description": "The URL of the second page of submissions, when there is one.", "example": "https://api.tintup.com/v2/teams/1/experiences/42/form_submissions?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total number of submissions.", "example": 1289 }, "count": { "type": "integer", "description": "Same as `total`.", "example": 1289 } } } } } } }, "links": { "$ref": "#/components/schemas/ExperiencePublicLinks" } } }, "NewDomain": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "domain" ] }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "format": "hostname", "description": "The fully qualified domain name, without scheme or path. It must not already be in use by any team (case-insensitive). Point the domain's DNS at the experience hosting servers before creating it so the SSL certificate can be issued. The name can't be changed after creation.", "example": "stories.example.com" } } } } }, "DomainUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "domain" ] }, "id": { "type": "string", "description": "The ID of the domain. Optional; the domain is identified by the URL.", "example": "42" }, "attributes": { "type": "object", "description": "Only `default_experience_id` can be updated; any other attribute is ignored.", "properties": { "default_experience_id": { "type": [ "integer", "null" ], "description": "The ID of the experience to show at the root of the domain, or `null` to remove it. The experience must be accessible to the user and already be published on this domain.", "example": 318 } } } } }, "EmailTemplateName": { "type": "string", "description": "The name of the template, shown in the dashboard.", "minLength": 1, "example": "Post-purchase review request" }, "EmailTemplateType": { "type": "string", "description": "What the template is used for: `review_solicitation` (asking a customer for a review), `review_solicitation_reminder` (a follow-up to a review request), `form_submission` (sent after a form is submitted), `influencer` (outreach to influencers), or `review_reply` (a reply to a review).", "enum": [ "review_solicitation", "review_solicitation_reminder", "form_submission", "influencer", "review_reply" ], "example": "review_solicitation" }, "EmailTemplateLocale": { "type": "object", "description": "The email content for one locale.", "required": [ "from", "subject", "body" ], "properties": { "from": { "type": "object", "description": "The sender of the email.", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "The sender's display name.", "minLength": 1, "example": "Acme Inc." }, "email": { "type": "string", "format": "email", "description": "The sender's email address.", "example": "reviews@example.com" } } }, "subject": { "type": "string", "description": "The subject line, as a [Liquid](https://shopify.github.io/liquid/) template. It's rendered with the same variables as `body`.", "minLength": 1, "example": "Thanks for your review, {{ post.author.name }}" }, "body": { "type": "string", "description": "The body of the email, as a [Liquid](https://shopify.github.io/liquid/) template that renders to HTML. The variables depend on the template's `type`:\n\n- `form_submission`: `form` (`id`, `name`, `type`) and `form_submission` (the submitted fields, keyed by field name).\n- `review_reply`: `team` (`id`, `name`, `image_url`), `post` (`title`, `text`, `rating`, `published_at`, `author`) and `reply` (`text`).", "minLength": 1, "example": "

Hi {{ post.author.name }},

\n

Thanks for reviewing us. Here's our reply:

\n
{{ reply.text }}
\n

The {{ team.name }} team

" } } }, "EmailTemplateLocales": { "type": "object", "description": "The content of the email for each locale, keyed by locale code (for example `en` or `fr-CA`). At least one locale is required, and each locale requires a non-blank `from.name`, `from.email`, `subject`, and `body`. Unknown keys are ignored.", "minProperties": 1, "additionalProperties": { "$ref": "#/components/schemas/EmailTemplateLocale" }, "example": { "en": { "from": { "name": "Acme Inc.", "email": "reviews@example.com" }, "subject": "Thanks for your review, {{ post.author.name }}", "body": "

Hi {{ post.author.name }},

\n

Thanks for reviewing us. Here's our reply:

\n
{{ reply.text }}
\n

The {{ team.name }} team

" }, "fr": { "from": { "name": "Acme Inc.", "email": "reviews@example.com" }, "subject": "Merci pour votre avis, {{ post.author.name }}", "body": "

Bonjour {{ post.author.name }},

\n

Merci pour votre avis. Voici notre réponse :

\n
{{ reply.text }}
\n

L'équipe {{ team.name }}

" } } }, "EmailTemplate": { "description": "A reusable, localized email used by review requests, forms, and influencer outreach.", "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the email template.", "example": "15", "readOnly": true }, "type": { "type": "string", "description": "The resource type. Note that it is the plural `email_templates`.", "enum": [ "email_templates" ] }, "attributes": { "type": "object", "required": [ "name", "type", "locales", "created_at", "updated_at" ], "properties": { "name": { "$ref": "#/components/schemas/EmailTemplateName" }, "type": { "$ref": "#/components/schemas/EmailTemplateType" }, "locales": { "$ref": "#/components/schemas/EmailTemplateLocales" }, "created_at": { "type": "string", "format": "date-time", "description": "When the email template was created.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the email template was last updated.", "example": "2025-03-18T09:15:32.000Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "required": [ "team" ], "properties": { "team": { "type": "object", "description": "The team that owns the template. `data` is only present when requested with `include=team`; otherwise the relationship contains `meta.included: false`.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "team" ] }, "id": { "type": "string", "description": "The ID of the team.", "example": "1" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } } ] }, "NewEmailTemplate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "email_templates" ] }, "attributes": { "type": "object", "required": [ "name", "type", "locales" ], "properties": { "name": { "$ref": "#/components/schemas/EmailTemplateName" }, "type": { "$ref": "#/components/schemas/EmailTemplateType" }, "locales": { "$ref": "#/components/schemas/EmailTemplateLocales" } } } } }, "EmailTemplateBulkDelete": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "email_templates" ] }, "id": { "type": "string", "description": "The ID of an email template to delete. IDs that don't belong to the team are ignored.", "example": "15" } } }, "EmailTemplateUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "email_templates" ] }, "id": { "type": "string", "description": "The ID of the email template. Optional; the template is identified by the URL.", "example": "15" }, "attributes": { "type": "object", "description": "The attributes to change. Omitted attributes keep their current value. The template's `type` can't be changed and is ignored.", "properties": { "name": { "$ref": "#/components/schemas/EmailTemplateName" }, "locales": { "allOf": [ { "$ref": "#/components/schemas/EmailTemplateLocales" } ], "description": "The content of the email for each locale. Replaces all existing locales, so include every locale to keep." } } } } }, "Font": { "description": "A custom web font that can be used in the team's experiences.", "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the font.", "example": "7", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "font" ] }, "attributes": { "type": "object", "required": [ "name", "url", "format", "metrics", "created_at", "updated_at" ], "properties": { "name": { "type": "string", "description": "The font family name, used as `font-family` in the generated stylesheet.", "example": "Quicksand", "readOnly": true }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "A signed URL to the font file. It expires at the end of the current week, so don't store it; fetch the font again or use the `css` link instead. `null` if the font has no file.", "example": "https://storage.example.com/fonts/quicksand-regular.woff2?X-Amz-Expires=604800&X-Amz-Signature=3f9a1c0b7d", "readOnly": true }, "format": { "type": [ "string", "null" ], "description": "The font file format, detected from the uploaded file's content type. `null` if the content type isn't recognized.", "enum": [ "woff", "woff2", "truetype", "opentype", "embedded_opentype", "svg", null ], "example": "woff2", "readOnly": true }, "metrics": { "type": "object", "description": "Vertical metrics read from the font file, in font units. Empty when the file couldn't be parsed (for example WOFF, WOFF2, or SVG files); individual keys are omitted when unavailable.", "properties": { "ascent": { "type": "integer", "description": "The distance from the baseline to the top of the tallest glyph.", "example": 1000 }, "descent": { "type": "integer", "description": "The distance from the baseline to the bottom of the lowest glyph (usually negative).", "example": -250 }, "units_per_em": { "type": "integer", "description": "The number of font units per em.", "example": 1000 } }, "example": { "ascent": 1000, "descent": -250, "units_per_em": 1000 }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When the font was created.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the font was last updated.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true } } }, "links": { "type": "object", "readOnly": true, "properties": { "css": { "type": "string", "format": "uri", "description": "A stylesheet declaring the font's `@font-face` rule. It can be used without an access token.", "example": "https://api.tintup.com/v2/teams/1/fonts/7.css" } } } } } ] }, "NewFont": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "font" ] }, "attributes": { "type": "object", "required": [ "upload_id" ], "properties": { "upload_id": { "type": "string", "description": "The `id` of an upload created with the font upload endpoint, once the file has been uploaded to the upload's `url`. The upload must belong to the same team.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTUsInB1ciI6ImJsb2JfaWQifX0=--6b1f0e3c2d9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c", "writeOnly": true }, "name": { "type": "string", "description": "The font family name. Defaults to the name stored in the font file or, if it can't be read, to the uploaded file name.", "example": "Quicksand" } } } } }, "NewUpload": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "upload" ] }, "attributes": { "type": "object", "required": [ "filename", "content_type", "byte_size", "checksum" ], "properties": { "filename": { "type": "string", "description": "The name of the file being uploaded.", "example": "quicksand-regular.woff2" }, "content_type": { "type": "string", "description": "The MIME type of the file.", "enum": [ "font/woff", "font/woff2", "font/ttf", "font/otf", "application/font-woff", "application/x-font-ttf", "application/vnd.ms-fontobject", "image/svg+xml" ], "example": "font/woff2" }, "byte_size": { "type": "integer", "description": "The size of the file in bytes. Fonts are limited to 5 MB.", "minimum": 1, "maximum": 5242880, "example": 38416 }, "checksum": { "type": "string", "description": "The Base64-encoded MD5 digest of the file.", "example": "1B2M2Y8AsgTpgAmY7PhCfg==" } } } } }, "Upload": { "description": "A pending direct upload. Upload the file to `url` with `headers`, then use `id` as the font's `upload_id`.", "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The signed ID of the upload. Pass it as `upload_id` when creating the font.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTUsInB1ciI6ImJsb2JfaWQifX0=--6b1f0e3c2d9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c", "readOnly": true }, "type": { "type": "string", "description": "The resource type.", "enum": [ "upload" ] }, "attributes": { "type": "object", "required": [ "url", "headers" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to upload the file's bytes to, with an HTTP `PUT` request. The URL expires after a few minutes.", "example": "https://uploads.example.com/9f8e7d6c5b4a3f2e1d0c?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=8c1d2e3f4a", "readOnly": true }, "headers": { "type": "object", "description": "The HTTP headers to send, unchanged, with the upload request.", "additionalProperties": { "type": "string" }, "example": { "Content-Type": "font/woff2", "Content-MD5": "1B2M2Y8AsgTpgAmY7PhCfg==" }, "readOnly": true } } } } }, "TintType": { "type": "string", "description": "The resource type. Always `tint`.", "enum": [ "tint" ], "example": "tint" }, "AutoModerationRule": { "type": "object", "description": "An auto-moderation rule applied to new posts. When a post matches the `conditions`, the `changes` are applied to it. Each rule supports a single condition key and a single change.", "required": [ "conditions", "changes" ], "properties": { "conditions": { "type": "object", "description": "The condition to match. Only one key is supported per rule.", "minProperties": 1, "maxProperties": 1, "properties": { "text": { "type": "array", "description": "Matches posts whose text contains any of these keywords.", "items": { "type": "string" }, "example": [ "spam", "giveaway" ] }, "author.username": { "type": "array", "description": "Matches posts whose author has any of these usernames.", "items": { "type": "string" }, "example": [ "janedoe" ] }, "author.remote_ip": { "type": "array", "description": "Matches posts submitted from any of these IP addresses. IP addresses are anonymized, so a specific address (/32) matches the entire block of 256 addresses (/24) it belongs to.", "items": { "type": "string" }, "example": [ "203.0.113.0" ] }, "metadata.image_nsfw": { "type": "object", "description": "Matches posts whose image NSFW score (from 0 to 1) is in the range. Use `$gte` and `$lt` together to make matching posts private, or `$gte` alone to delete them. The lower bound must not exceed the upper bound.", "properties": { "$gte": { "type": "number", "format": "float", "description": "The inclusive lower bound of the NSFW score.", "minimum": 0, "maximum": 1, "example": 0.7 }, "$lt": { "type": "number", "format": "float", "description": "The exclusive upper bound of the NSFW score.", "minimum": 0, "maximum": 1, "example": 0.9 } } } } }, "changes": { "type": "object", "description": "The change to apply to matching posts.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "The moderation status to give matching posts. `deleted` is only used by `metadata.image_nsfw` rules with a single `$gte` bound; text, username and IP address rules accept `public` and `private`.", "enum": [ "public", "private", "deleted" ], "example": "private" } } } }, "example": { "conditions": { "text": [ "spam" ] }, "changes": { "status": "private" } } }, "TintAttributes": { "type": "object", "description": "The attributes of a board.", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the board.", "example": "Acme Summer Campaign" }, "slug": { "type": [ "string", "null" ], "description": "The unique part of the board's public URL. It defaults to the board's ID and can't be changed through the API.", "example": "acme-summer-campaign", "readOnly": true }, "public_channel": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated. The board ID as a string, or `null`.", "example": null, "readOnly": true }, "status": { "type": "string", "description": "Whether the board is active. Only returned to authenticated requests.", "enum": [ "active", "inactive" ], "example": "active" }, "private": { "type": "boolean", "description": "Whether the board is private. Only returned to authenticated requests.", "example": false }, "tags": { "type": [ "array", "null" ], "description": "The tags available to categorize posts in the board. Only returned to authenticated requests.", "items": { "type": "string" }, "example": [ "featured", "follow up" ] }, "auto_moderation_rules": { "type": "array", "description": "The auto-moderation rules applied to new posts, in order. Only returned to authenticated requests.", "items": { "$ref": "#/components/schemas/AutoModerationRule" }, "example": [ { "conditions": { "text": [ "spam" ] }, "changes": { "status": "private" } } ] }, "last_moderated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a post of the board was last moderated, or `null` if none has been. Only returned to authenticated requests.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When the board was created. Only returned to authenticated requests.", "example": "2025-01-06T09:15:00.000Z", "readOnly": true } } }, "TintRelationships": { "type": "object", "description": "The board's relationships. Unless a relationship is requested with the `include` query parameter, only `meta.included: false` is returned (except for `default_personalization`, whose `data` is always returned).", "readOnly": true, "properties": { "personalizations": { "type": "object", "description": "Deprecated. Always empty; use `default_personalization` or the personalizations endpoints instead.", "deprecated": true, "properties": { "data": { "type": "array", "items": { "type": "object" }, "maxItems": 0, "example": [] }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "default_personalization": { "type": "object", "description": "The personalization used by default to display the board. Only returned to unauthenticated requests or when the access token has the `personalizations:read` scope.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "id": { "type": "string", "example": "7" } }, "description": "The default personalization, or `null` if the board doesn't have one." } } }, "social_feeds": { "type": "object", "description": "The board's social feeds. Only returned to unauthenticated requests (which exclude social feeds whose status is `token_requested`) or when the access token has the `social_feeds:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "social_feed" ], "example": "social_feed" }, "id": { "type": "string", "example": "311" } } } }, "meta": { "type": "object", "properties": { "included": { "type": "boolean", "description": "`false` when the relationship wasn't requested with the `include` query parameter.", "example": false }, "total": { "type": "integer", "deprecated": true, "description": "Deprecated. Use `count` instead.", "example": 3 }, "count": { "type": "integer", "description": "The number of social feeds in the board.", "example": 3 }, "access_error_count": { "type": "integer", "description": "The number of social feeds whose account needs to be reauthorized.", "example": 0 } } } } }, "posts": { "type": "object", "description": "The board's 25 most recent posts (pinned posts first). Only returned to unauthenticated requests or when the access token has the `posts:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "example": "9001" } } } }, "links": { "type": "object", "description": "Links to the board's posts, only returned when included and the board has posts.", "properties": { "first": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts" }, "next": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts?page%5Bbefore%5D=MTc0MTk3MDUyN3w5MDAxfDA%3D" }, "previous": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts?page%5Bafter%5D=MTc0MTk3MDUyN3w5MDAxfDA%3D" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "saved_filters": { "type": "object", "description": "The board's saved filters. Only returned when the access token has the `saved_filters:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "saved_filter" ], "example": "saved_filter" }, "id": { "type": "string", "example": "15" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "recently_active_embed_locations": { "type": "object", "description": "The web pages where the board was recently displayed. Only returned to authenticated requests.", "properties": { "data": { "type": "array", "description": "Only returned when included. The IDs are the embed URLs.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recently_active_embed_location" ], "example": "recently_active_embed_location" }, "id": { "type": "string", "example": "https://example.com/summer" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "rights_terms": { "type": "object", "description": "The right request terms available to the board. Only returned when the access token has the `right_request_terms:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "right_request_term" ], "example": "right_request_term" }, "id": { "type": "string", "example": "5" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } }, "TintLinks": { "type": "object", "description": "Links related to the board.", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the board: the team URL for authenticated requests, the public (slug) URL otherwise.", "example": "https://api.tintup.com/v2/teams/1/tints/42" }, "public_post_terms": { "type": "string", "format": "uri", "description": "The URL of the public post terms and conditions. Only relevant if the board has a social feed whose `source` is `public_post`.", "example": "https://app.tintup.com/public_post_terms/acme-summer-campaign" }, "websocket": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated. The real-time updates URL, or `null`.", "example": null } } }, "Tint": { "type": "object", "description": "A board. Attributes marked as only returned to authenticated requests are omitted when the board is retrieved without an access token.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the board.", "example": "42", "readOnly": true }, "type": { "$ref": "#/components/schemas/TintType" }, "attributes": { "$ref": "#/components/schemas/TintAttributes" }, "relationships": { "$ref": "#/components/schemas/TintRelationships" }, "links": { "$ref": "#/components/schemas/TintLinks" } } }, "TintWritableAttributes": { "type": "object", "description": "Attributes that can be sent when creating or updating a board.", "properties": { "name": { "type": [ "string", "null" ], "description": "The name of the board.", "example": "Acme Summer Campaign" }, "private": { "type": "boolean", "description": "Whether the board is private. Posts of a private board aren't available publicly.", "default": false, "example": false }, "tags": { "type": "array", "description": "The tags available to categorize posts in the board. A comma-separated string is also accepted. Duplicates (ignoring case) are removed. Removing a tag also removes it from the board's posts.", "items": { "type": "string" }, "example": [ "featured", "follow up" ] }, "auto_moderation_rules": { "type": "array", "description": "The auto-moderation rules applied to new posts, in order. Rules that don't match the supported shapes are ignored. Sending this attribute replaces all existing rules.", "items": { "$ref": "#/components/schemas/AutoModerationRule" }, "example": [ { "conditions": { "text": [ "spam" ] }, "changes": { "status": "private" } }, { "conditions": { "metadata.image_nsfw": { "$gte": 0.9 } }, "changes": { "status": "deleted" } } ] }, "default_personalization_id": { "type": [ "integer", "null" ], "description": "The ID of the personalization used by default to display the board. It must be a personalization you have access to. It can only be changed on a board that already has a default personalization.", "writeOnly": true, "example": 7 } } }, "NewTint": { "type": "object", "description": "The board to create.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/TintType" }, "attributes": { "$ref": "#/components/schemas/TintWritableAttributes" } } }, "TintBulkDelete": { "type": "object", "description": "A board to delete.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the board.", "example": "42" }, "type": { "$ref": "#/components/schemas/TintType" } } }, "TintUpdate": { "type": "object", "description": "The board changes. Only the attributes sent are changed. The `id` is optional; the board is identified by the URL.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the board.", "example": "42" }, "type": { "$ref": "#/components/schemas/TintType" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/TintWritableAttributes" }, { "type": "object", "properties": { "status": { "type": "string", "description": "Whether the board is active.", "enum": [ "active", "inactive" ], "example": "active" } } } ] } } }, "TintBulkUpdate": { "allOf": [ { "$ref": "#/components/schemas/TintUpdate" }, { "type": "object", "description": "A board to update, identified by its `id`. In bulk updates, only `name`, `private`, `status` and `tags` are saved; other attributes are ignored.", "required": [ "id" ] } ] }, "MetricId": { "type": "string", "description": "A random identifier generated for each metric in the response. It isn't stable across requests.", "example": "f42c2ba98b72afee69976d52875fe313", "readOnly": true }, "MetricCount": { "type": "integer", "description": "The number of events (or posts) in the group.", "example": 1284, "readOnly": true }, "TintIdentifier": { "type": "object", "description": "A resource identifier for a board.", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/TintType" }, "id": { "type": "string", "description": "The ID of the board.", "example": "42" } } }, "PostType": { "type": "string", "description": "The resource type. Always `post`.", "enum": [ "post" ], "example": "post" }, "PostsEngagementMetric": { "type": "object", "description": "The number of engagement events, for one group of dimensions.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/MetricId" }, "type": { "type": "string", "description": "The resource type. Always `embed_engagement_metric`.", "enum": [ "embed_engagement_metric" ], "example": "embed_engagement_metric" }, "attributes": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/MetricCount" }, "dimensions": { "type": [ "object", "null" ], "description": "The values of the dimensions requested with the `group` query parameter for this group, or `null` when the metrics aren't grouped. Time dimensions are returned as both `time` and `created_at` (the start of the period), or as `day_of_week`/`time.day_of_week` (0 is Sunday) and `hour_of_day`/`time.hour_of_day`.", "additionalProperties": true, "readOnly": true, "example": { "tint_id": "42", "time": "2025-03-14T00:00:00.000-04:00", "created_at": "2025-03-14T00:00:00.000-04:00" } } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board. Only returned when grouping by `tint_id`.", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/TintIdentifier" }, { "type": "null" } ] } } }, "post": { "type": "object", "description": "The post. Only returned when grouping by `post_id`.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "$ref": "#/components/schemas/PostType" }, "id": { "type": "string", "example": "9001" } } } } } } } } }, "name": { "type": [ "string", "null" ], "description": "The name of the board.", "example": "Acme Summer Campaign" }, "slug": { "type": [ "string", "null" ], "description": "The unique part of the board's public URL. It defaults to the board's ID and can't be changed through the API.", "example": "acme-summer-campaign", "readOnly": true }, "public_channel": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated. The board ID as a string, or `null`.", "example": null, "readOnly": true }, "personalizations": { "type": "object", "description": "Deprecated. Always empty; use `default_personalization` or the personalizations endpoints instead.", "deprecated": true, "properties": { "data": { "type": "array", "items": { "type": "object" }, "maxItems": 0, "example": [] }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "default_personalization": { "type": "object", "description": "The personalization used by default to display the board. Only returned to unauthenticated requests or when the access token has the `personalizations:read` scope.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ], "example": "personalization" }, "id": { "type": "string", "example": "7" } }, "description": "The default personalization, or `null` if the board doesn't have one." } } }, "social_feeds": { "type": "object", "description": "The board's social feeds. Only returned to unauthenticated requests (which exclude social feeds whose status is `token_requested`) or when the access token has the `social_feeds:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "social_feed" ], "example": "social_feed" }, "id": { "type": "string", "example": "311" } } } }, "meta": { "type": "object", "properties": { "included": { "type": "boolean", "description": "`false` when the relationship wasn't requested with the `include` query parameter.", "example": false }, "total": { "type": "integer", "deprecated": true, "description": "Deprecated. Use `count` instead.", "example": 3 }, "count": { "type": "integer", "description": "The number of social feeds in the board.", "example": 3 }, "access_error_count": { "type": "integer", "description": "The number of social feeds whose account needs to be reauthorized.", "example": 0 } } } } }, "posts": { "type": "object", "description": "The board's 25 most recent posts (pinned posts first). Only returned to unauthenticated requests or when the access token has the `posts:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "example": "9001" } } } }, "links": { "type": "object", "description": "Links to the board's posts, only returned when included and the board has posts.", "properties": { "first": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts" }, "next": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts?page%5Bbefore%5D=MTc0MTk3MDUyN3w5MDAxfDA%3D" }, "previous": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/tints/42/posts?page%5Bafter%5D=MTc0MTk3MDUyN3w5MDAxfDA%3D" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "PublicTint": { "type": "object", "description": "The public representation of a board, returned when the board is retrieved by slug without an access token. With an access token, the full representation is returned instead.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the board.", "example": "42", "readOnly": true }, "type": { "$ref": "#/components/schemas/TintType" }, "attributes": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/name" }, "slug": { "$ref": "#/components/schemas/slug" }, "public_channel": { "$ref": "#/components/schemas/public_channel" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "personalizations": { "$ref": "#/components/schemas/personalizations" }, "default_personalization": { "$ref": "#/components/schemas/default_personalization" }, "social_feeds": { "$ref": "#/components/schemas/social_feeds" }, "posts": { "$ref": "#/components/schemas/posts" } } }, "links": { "$ref": "#/components/schemas/TintLinks" } } }, "UserAttributes": { "type": "object", "description": "The profile of a user.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "The user's first name. `null` when not set.", "example": "Jane" }, "last_name": { "type": [ "string", "null" ], "description": "The user's last name. `null` when not set.", "example": "Doe" }, "organization": { "type": [ "string", "null" ], "description": "The name of the organization the user works for. `null` when not set.", "example": "Acme Inc." }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the user's profile picture. Must be an `http` or `https` URL; send `null` to remove it (an empty string is rejected). `null` when not set.", "example": "https://cdn.example.com/avatars/jane-doe.png" }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "The user's email address. Must be unique across all users.", "example": "jane.doe@example.com" } } }, "MeAttributes": { "type": "object", "properties": { "default_authentication_factor_id": { "type": [ "integer", "null" ], "description": "The ID of the authentication factor to use by default when signing in. Required (can't be `null`) once the user has an active authentication factor other than recovery codes.", "example": 5 }, "temporary_support_access_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When set, grants our support team temporary access to the account until that time. Must be between 1 and 28 days from now; send `null` to revoke access. Returned as `null` once the time has passed.", "example": "2025-03-21T16:42:07.000Z" } } }, "Me": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "example": "42" }, "type": { "type": "string", "enum": [ "user" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/UserAttributes" }, { "$ref": "#/components/schemas/MeAttributes" }, { "type": "object", "required": [ "first_name", "last_name", "organization", "image_url", "email", "created_at", "updated_at" ], "properties": { "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the user signed up.", "example": "2024-11-02T10:05:44.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the user's profile was last updated.", "example": "2025-03-14T16:42:07.000Z" } } } ] }, "relationships": { "type": "object", "readOnly": true, "properties": { "authentication_factors": { "type": "object", "description": "The user's authentication factors. `data` is only present when the relationship is requested with `include=authentication_factors`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_factor" ] }, "id": { "type": "string", "example": "5" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the user's authentication factors.", "example": "https://api.tintup.com/v2/authentication_factors" } } } } }, "teams": { "type": "object", "description": "The teams the user is a member of. `data` is only present when the relationship is requested with `include=teams`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "example": "1" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the user's teams.", "example": "https://api.tintup.com/v2/teams" } } } } } } }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the authenticated user.", "example": "https://api.tintup.com/v2/me" } } } } } ] }, "MeUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the user. Optional; the user is always the owner of the access token.", "example": "42" }, "type": { "type": "string", "enum": [ "user" ] }, "attributes": { "description": "The attributes to change. Attributes that are omitted are left unchanged. Changing `email` or `password`, or setting `temporary_support_access_ends_at`, requires an `id_token`.", "allOf": [ { "$ref": "#/components/schemas/UserAttributes" }, { "$ref": "#/components/schemas/MeAttributes" }, { "type": "object", "properties": { "password": { "type": "string", "format": "password", "writeOnly": true, "minLength": 12, "description": "The new password. Must have at least 12 characters, including an uppercase letter, a lowercase letter, a digit and one of the special characters `#?!@$%^&*+~-`, and must not repeat the same character or word three times in a row.", "example": "Violet-Harbor-2025" } } } ] } } }, "TeamUserMembershipAttributes": { "type": "object", "properties": { "skip_idp": { "type": "boolean", "description": "Whether the user can sign in without going through the team's identity provider (SAML or OpenID Connect).", "default": false, "example": false } } }, "TeamUser": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "description": "The ID of the user.", "example": "42" }, "type": { "type": "string", "description": "Team members are represented as `user` resources.", "enum": [ "user" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/UserAttributes" }, { "$ref": "#/components/schemas/TeamUserMembershipAttributes" }, { "type": "object", "required": [ "first_name", "last_name", "organization", "image_url", "email", "skip_idp", "created_at", "updated_at" ], "properties": { "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the user was added to the team.", "example": "2025-01-08T13:22:10.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the user's membership (role or `skip_idp`) was last updated.", "example": "2025-03-14T16:42:07.000Z" } } } ] }, "relationships": { "type": "object", "readOnly": true, "properties": { "role": { "type": "object", "description": "The role assigned to the user in the team. `data` is only present when the relationship is requested with `include=role`.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "role" ] }, "id": { "type": "string", "example": "3" } } } } } } } } } ] }, "TeamUserRoleId": { "type": "object", "properties": { "role_id": { "type": "integer", "writeOnly": true, "description": "The ID of the role to assign to the user in the team. Use `include=role` to see a member's role in responses.", "example": 3 } } }, "NewTeamUser": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "user" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/TeamUserMembershipAttributes" }, { "$ref": "#/components/schemas/TeamUserRoleId" }, { "type": "object", "required": [ "email", "role_id" ], "properties": { "email": { "type": "string", "format": "email", "writeOnly": true, "description": "The email address of the user to invite. An account is created for email addresses that don't have one yet. You can't invite yourself.", "example": "john.smith@example.com" }, "role_id": { "description": "The ID of the role to assign to the user. Must be one of the team's roles." } } } ] } } }, "TeamUserIdentifier": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the user.", "example": "42" }, "type": { "type": "string", "enum": [ "user" ] } } }, "TeamUserUpdate": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the user. Required in bulk updates to identify the user; ignored when updating a single user, which is identified by the URL.", "example": "42" }, "type": { "type": "string", "enum": [ "user" ] }, "attributes": { "description": "The attributes to change. Attributes that are omitted are left unchanged.", "allOf": [ { "$ref": "#/components/schemas/TeamUserMembershipAttributes" }, { "$ref": "#/components/schemas/TeamUserRoleId" } ] } } }, "NewTeamsUserExportRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "teams_user_export_request" ] }, "attributes": { "type": "object", "properties": { "filters": { "type": "object", "description": "Reserved for future use. Filters are currently ignored and every user of the team is exported.", "example": {} } } } } }, "exportStatus": { "type": "string", "description": "`pending` while the export is being generated, then `success` or `failure`.", "enum": [ "pending", "success", "failure" ], "example": "pending", "readOnly": true }, "ExportUrl": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the CSV export. Once the `status` attribute is `success`, every request returns a new signed URL, valid for 15 minutes, for up to 30 days. `null` until then.", "example": null, "readOnly": true }, "TeamsUserExportRequest": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the export request.", "example": "OxZZQtuh5sXIKA", "readOnly": true }, "type": { "type": "string", "enum": [ "teams_user_export_request" ] }, "attributes": { "type": "object", "required": [ "status", "url" ], "properties": { "status": { "$ref": "#/components/schemas/exportStatus" }, "url": { "$ref": "#/components/schemas/ExportUrl" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "team": { "type": "object", "description": "The team whose users are exported. `data` is only present when the relationship is requested with `include=team`.", "properties": { "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" }, "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "example": "1" } } } } } } } } }, "AuthenticationFactorType": { "type": "string", "description": "The resource type.", "enum": [ "authentication_factor" ], "example": "authentication_factor" }, "authenticationFactorStatuses": { "type": "string", "description": "`pending` until the authentication factor is verified, then `active`. Recovery codes and `email` factors are `active` as soon as they are created.", "enum": [ "pending", "active" ] }, "authenticationFactorTypes": { "type": "string", "description": "The kind of authentication factor. `recovery_code` is a single backup code, `out_of_band` sends a code by email, SMS, voice call or fax, and `one_time_password` uses an authenticator app (TOTP).", "enum": [ "recovery_code", "out_of_band", "one_time_password" ] }, "AuthenticationFactor": { "type": "object", "description": "An authentication factor (second factor) of the current user.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the authentication factor.", "example": "42", "readOnly": true }, "type": { "$ref": "#/components/schemas/AuthenticationFactorType" }, "attributes": { "type": "object", "required": [ "status", "type", "channel", "external_id", "provisioning_url", "created_at" ], "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/authenticationFactorStatuses" } ], "example": "pending", "readOnly": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/authenticationFactorTypes" } ], "example": "one_time_password" }, "channel": { "type": [ "string", "null" ], "description": "How the code is delivered. Only set when `type` is `out_of_band`; `null` otherwise.", "enum": [ "sms", "voice", "email", "fax", null ], "example": null }, "external_id": { "type": [ "string", "null" ], "description": "The phone or fax number, in E.164 format, that codes are sent to. Only set when `type` is `out_of_band` and `channel` is `sms`, `voice` or `fax`; `null` otherwise.", "example": null }, "provisioning_url": { "type": [ "string", "null" ], "format": "uri", "description": "The `otpauth://` URL to add the authentication factor to an authenticator app (usually shown as a QR code). Only set while a `one_time_password` authentication factor is `pending`; `null` otherwise.", "example": "otpauth://totp/TrueLoyal:jane.doe%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=TrueLoyal", "readOnly": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the authentication factor was created.", "example": "2025-03-14T16:42:07.000Z" } } } } }, "authenticationFactorOutOfBandChannels": { "type": "string", "description": "How the code of an `out_of_band` authentication factor is delivered.", "enum": [ "sms", "voice", "email", "fax" ] }, "NewAuthenticationFactor": { "type": "object", "description": "The authentication factor to add. Which attributes are allowed depends on `type` and `channel`: `channel` is required for (and only allowed with) `out_of_band`, and `external_id` is required for (and only allowed with) the `sms`, `voice` and `fax` channels.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/AuthenticationFactorType" }, "attributes": { "type": "object", "required": [ "type" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/authenticationFactorTypes" } ], "description": "The kind of authentication factor. A user can have only one authentication factor per `type` and `channel` combination.", "example": "out_of_band" }, "channel": { "allOf": [ { "$ref": "#/components/schemas/authenticationFactorOutOfBandChannels" } ], "description": "How the code is delivered. Required when `type` is `out_of_band` and must be omitted otherwise.", "example": "sms" }, "external_id": { "type": "string", "description": "The phone or fax number to send codes to, in E.164 format (a `+` followed by up to 15 digits). Required when `channel` is `sms`, `voice` or `fax` and must be omitted otherwise.", "pattern": "^\\+[1-9]\\d{1,14}$", "example": "+16045550123" } } } } }, "AuthenticationFactorForVerify": { "type": "object", "description": "The code used to verify a pending authentication factor.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the authentication factor. Ignored; the path parameter is used instead.", "example": "42" }, "type": { "$ref": "#/components/schemas/AuthenticationFactorType" }, "attributes": { "type": "object", "required": [ "challenge" ], "properties": { "challenge": { "type": "string", "description": "The code received by SMS, voice call or fax, or generated by the authenticator app.", "example": "492817", "writeOnly": true }, "otp_attempt": { "type": "string", "deprecated": true, "description": "Deprecated. Use `challenge` instead. Only used when `challenge` is omitted.", "example": "492817", "writeOnly": true } } } } }, "AuthenticationFactorChallengeType": { "type": "string", "description": "The resource type.", "enum": [ "authentication_factor_challenge" ], "example": "authentication_factor_challenge" }, "NewAuthenticationFactorChallenge": { "type": "object", "description": "The challenge to create. The authentication factor is taken from the path.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/AuthenticationFactorChallengeType" }, "attributes": { "type": "object", "properties": { "authentication_factor_id": { "type": "integer", "description": "The ID of the authentication factor to challenge. Ignored; the `authentication_factor_id` path parameter is used instead.", "example": 42, "writeOnly": true } } } } }, "AuthenticationFactorChallenge": { "type": "object", "description": "A code that was just sent for a pending `out_of_band` authentication factor.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The identifier of the SMS, voice call or fax used to deliver the code.", "example": "SM5e0c7a1f9b3d4e2a8c6f0b1d3e5a7c9f", "readOnly": true }, "type": { "$ref": "#/components/schemas/AuthenticationFactorChallengeType" }, "attributes": { "type": "object", "required": [ "retry_at" ], "properties": { "retry_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When a new code can be requested for this authentication factor (30 seconds after this one was sent).", "example": "2025-03-14T16:42:37.000Z" } } } } }, "assetStatus": { "type": "string", "description": "`active` assets are visible in the asset manager; `archived` assets are hidden from it by default.", "enum": [ "active", "archived" ], "example": "active" }, "Asset": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the asset.", "readOnly": true, "example": "190245" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "asset" ], "example": "asset" }, "attributes": { "type": "object", "readOnly": true, "required": [ "status", "source", "url", "mime_type", "size", "dimensions" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the asset was created.", "example": "2025-03-10T09:15:32.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the asset was last updated.", "example": "2025-03-14T16:42:07.000Z" }, "status": { "$ref": "#/components/schemas/assetStatus" }, "source": { "allOf": [ { "$ref": "#/components/schemas/AssetSource" } ], "description": "Where the asset comes from. Assets created through the API are `branded`; assets imported from right requests or form submissions keep the source of the original content.", "example": "branded" }, "name": { "type": [ "string", "null" ], "description": "The asset's name.", "example": "Beach picnic with the Acme cooler" }, "description": { "type": [ "string", "null" ], "description": "A longer description of the asset.", "example": "Customer photo submitted during the summer campaign." }, "alternative_text": { "type": [ "string", "null" ], "description": "Text describing the image for screen readers. When not set by a user, it may contain an automatically generated description.", "example": "Two friends sitting on a beach towel next to a red cooler." }, "caption": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated. Same value as `alternative_text`.", "example": "Two friends sitting on a beach towel next to a red cooler." }, "tags": { "type": "array", "description": "Tags of the asset, without case-insensitive duplicates.", "items": { "type": "string" }, "example": [ "spring-launch", "ugc" ] }, "objects": { "type": [ "array", "null" ], "description": "Objects detected in the image or video (lowercase). `null` until the asset has been analyzed.", "items": { "type": "string" }, "example": [ "beach", "cooler", "person" ] }, "emotions": { "type": [ "array", "null" ], "description": "Emotions detected on faces in the image. `null` when not analyzed or for videos.", "items": { "type": "string" }, "example": [ "happy" ] }, "infections": { "type": [ "array", "null" ], "description": "Malware detected in the file, if any.", "items": { "type": "string" }, "example": null }, "licenses": { "type": [ "boolean", "null" ], "description": "Whether license information (such as copyright metadata) was found in the file. `null` when not checked.", "example": false }, "sfw": { "type": [ "boolean", "null" ], "description": "Whether the file is safe for work. `null` when not checked.", "example": true }, "insights": { "type": [ "object", "null" ], "description": "Attention insights for images, with `metrics` (scores keyed by metric name) and `heatmap` (the attention heat map). `null` when not analyzed.", "additionalProperties": true, "example": null }, "imported_from_data": { "type": [ "object", "null" ], "description": "Details about the content the asset was imported from (such as the author and the original post for right requests, or the submitter for form submissions). Empty or `null` for uploaded assets.", "additionalProperties": true, "example": {} }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL the asset was imported from. `null` for direct uploads.", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "expanded_url": { "type": [ "string", "null" ], "format": "uri", "description": "Same value as `source_url`.", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "download_url": { "type": [ "string", "null" ], "format": "uri", "description": "Same value as `source_url`.", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the stored file.", "example": "https://media.example.com/assets/190245/beach-picnic.jpg" }, "thumbnail_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of a thumbnail of the image or video. `null` when no thumbnail is available.", "example": "https://media.example.com/assets/190245/thumbnail.jpg" }, "mime_type": { "type": "string", "description": "The file's media type.", "example": "image/jpeg" }, "size": { "type": "integer", "description": "The file size in bytes.", "example": 2483910 }, "dimensions": { "type": "array", "description": "The width and height of the image or video, in pixels.", "minItems": 2, "maxItems": 2, "items": { "type": [ "integer", "null" ] }, "example": [ 1080, 1350 ] }, "duration": { "type": [ "number", "null" ], "description": "The video duration in seconds. `null` for images.", "example": null }, "author": { "type": "null", "deprecated": true, "description": "Deprecated. Always `null`; see `imported_from_data`.", "example": null }, "text": { "type": "null", "deprecated": true, "description": "Deprecated. Always `null`; see `imported_from_data`.", "example": null }, "post_title": { "type": "null", "deprecated": true, "description": "Deprecated. Always `null`; see `imported_from_data`.", "example": null }, "post_text": { "type": "null", "deprecated": true, "description": "Deprecated. Always `null`; see `imported_from_data`.", "example": null } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "media": { "type": "object", "description": "The file uploaded directly for this asset. Always returned; `data` is `null` for imported assets.", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/UploadIdentifier" }, { "type": "null" } ], "example": null } } }, "person": { "type": "object", "description": "The loyalty member who created the content, when known. Always returned.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person" ], "example": "person" }, "id": { "type": [ "string", "null" ], "description": "The loyalty member's ID, or `null` when the asset isn't linked to a loyalty member.", "example": null } } } } }, "team": { "type": "object", "description": "The team that owns the asset. Only returned when the token has the `teams:read` scope. `data` is only returned when `team` is included.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ], "example": "team" }, "id": { "type": "string", "example": "212" } } }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the team.", "example": "https://api.tintup.com/v2/teams/212" } } } } }, "collections": { "type": "object", "description": "The collections the asset belongs to. `data` is only returned when `collections` is included; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "collection" ], "example": "collection" }, "id": { "type": "string", "example": "48" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "imported_from": { "type": "object", "description": "The right request or form submission the asset was imported from. Only returned for assets imported from a right request when the token has the `right_requests:read` scope, or from a form submission when it has the `form_submissions:read` scope. `data` is only returned when `imported_from` is included.", "properties": { "data": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "right_request", "form_submission" ], "example": "right_request" }, "id": { "type": "string", "example": "7710" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "variants": { "type": "object", "deprecated": true, "description": "Deprecated. Each asset has a single variant, the asset itself (see `Variant`). `data` is present when `variants` is included, and always in webhook payloads.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "variant" ], "example": "variant" }, "id": { "type": "string", "description": "The ID of the variant, the same as the asset's ID.", "example": "190245" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 } } } } } } }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the asset.", "example": "https://api.tintup.com/v2/teams/212/assets/190245" } } } } }, "AssetsListMeta": { "type": "object", "readOnly": true, "properties": { "aggregations": { "type": "object", "description": "The number of matching assets for each value, computed over the team's assets with the requested `status`. A key is `null` when there's nothing to aggregate.", "properties": { "objects": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "example": { "beach": 18, "person": 42 } }, "sources": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "example": { "branded": 120, "instagram_business": 64 } }, "mime_types": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "example": { "image": 170, "video": 14 } }, "tags": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "example": { "spring-launch": 31, "ugc": 77 } }, "emotions": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" }, "example": { "happy": 25 } } } } } }, "AssetTagsInput": { "description": "Tags to set on the asset, either as a list (or a comma-separated string) that replaces the existing tags, or as an object with `+` (tags to add) and/or `-` (tags to remove). Duplicates are removed case-insensitively.", "oneOf": [ { "type": "array", "title": "Replace", "items": { "type": "string" }, "example": [ "spring-launch", "ugc" ] }, { "type": "string", "title": "Replace (comma-separated)", "example": "spring-launch,ugc" }, { "type": "object", "title": "Add or remove", "properties": { "+": { "description": "Tags to add, as a list or a comma-separated string.", "oneOf": [ { "title": "List", "type": "array", "items": { "type": "string" } }, { "title": "Comma-separated list", "type": "string" } ], "example": [ "approved" ] }, "-": { "description": "Tags to remove, as a list or a comma-separated string.", "oneOf": [ { "title": "List", "type": "array", "items": { "type": "string" } }, { "title": "Comma-separated list", "type": "string" } ], "example": [ "needs-review" ] } } } ], "example": [ "spring-launch", "ugc" ] }, "AssetCollectionIdsInput": { "description": "Collections the asset belongs to, either as a list of collection IDs (or a comma-separated string) that replaces the collections the user has access to (collections the user can't access are kept), or as an object with `+` (collection IDs to add) and/or `-` (collection IDs to remove). Every ID must be a collection the user has access to. Write-only: use the `collections` relationship to read them.", "writeOnly": true, "oneOf": [ { "type": "array", "title": "Replace", "items": { "type": "integer" }, "example": [ 48, 52 ] }, { "type": "string", "title": "Replace (comma-separated)", "example": "48,52" }, { "type": "object", "title": "Add or remove", "properties": { "+": { "description": "Collection IDs to add, as a list or a comma-separated string.", "oneOf": [ { "title": "List", "type": "array", "items": { "type": "integer" } }, { "title": "Comma-separated list", "type": "string" } ], "example": [ 52 ] }, "-": { "description": "Collection IDs to remove, as a list or a comma-separated string.", "oneOf": [ { "title": "List", "type": "array", "items": { "type": "integer" } }, { "title": "Comma-separated list", "type": "string" } ], "example": [ 48 ] } } } ], "example": [ 48, 52 ] }, "AssetWritableAttributes": { "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/assetStatus" } ], "default": "active" }, "name": { "type": [ "string", "null" ], "description": "The asset's name, used in search.", "example": "Beach picnic with the Acme cooler" }, "title": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated alias of `name`.", "writeOnly": true, "example": "Beach picnic with the Acme cooler" }, "description": { "type": [ "string", "null" ], "description": "A longer description of the asset, used in search.", "example": "Customer photo submitted during the summer campaign." }, "alternative_text": { "type": [ "string", "null" ], "description": "Text describing the image for screen readers.", "example": "Two friends sitting on a beach towel next to a red cooler." }, "tags": { "$ref": "#/components/schemas/AssetTagsInput" }, "collection_ids": { "$ref": "#/components/schemas/AssetCollectionIdsInput" } } }, "NewAsset": { "type": "object", "description": "Specify either `source_url` or `media`. The file is downloaded and analyzed asynchronously, and counts toward the plan's limit of uploaded assets.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "asset" ], "example": "asset" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/AssetWritableAttributes" }, { "type": "object", "properties": { "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the image or video to import. Must start with `http://` or `https://`. Required unless `media` is set, and can't be combined with it.", "pattern": "^https?://", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "media": { "type": [ "string", "null" ], "description": "The signed ID of a file uploaded directly, as returned by a direct upload. Can't be combined with `source_url`.", "writeOnly": true, "example": "eyJfcmFpbHMiOnsiZGF0YSI6ODgyMTUsInB1ciI6ImJsb2JfaWQifX0=--1c3e5a7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8a0c" }, "parent_id": { "type": [ "integer", "null" ], "description": "The ID of an asset of the team this asset was derived from.", "writeOnly": true, "example": 190233 } } } ] } } }, "AssetBulkCreateRequest": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the request, also sent in the completion websocket message.", "readOnly": true, "example": "3f9c1a7e5b2d4c86a0e1" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "asset_bulk_create_request" ], "example": "asset_bulk_create_request" }, "attributes": { "type": "object", "readOnly": true, "required": [ "status" ], "properties": { "status": { "type": "string", "description": "`pending` while the assets are being created, then `success` if all of them were created or `failure` otherwise.", "enum": [ "pending", "success", "failure" ], "example": "pending" } } } } }, "AssetDelete": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the asset to delete.", "example": "190245" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "asset" ], "example": "asset" } } }, "AssetUpdate": { "type": "object", "description": "Only the attributes that are sent are changed.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the asset.", "example": "190245" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "asset" ], "example": "asset" }, "attributes": { "$ref": "#/components/schemas/AssetWritableAttributes" } } }, "AssetBulkUpdate": { "allOf": [ { "$ref": "#/components/schemas/AssetUpdate" }, { "type": "object", "required": [ "id" ] } ] }, "AssetAggregation": { "type": "object", "required": [ "id", "type", "attributes" ], "readOnly": true, "properties": { "id": { "type": "string", "description": "The aggregated field.", "enum": [ "emotions", "mime_types", "objects", "sources", "tags" ], "example": "tags" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "aggregation" ], "example": "aggregation" }, "attributes": { "type": "object", "required": [ "buckets" ], "properties": { "buckets": { "type": "object", "description": "The number of the team's assets for each value.", "additionalProperties": { "type": "integer" }, "example": { "spring-launch": 31, "ugc": 77 } } } } } }, "SocialFeedType": { "type": "string", "description": "The resource type. Always `social_feed`.", "enum": [ "social_feed" ], "example": "social_feed" }, "SocialFeedKind": { "type": [ "string", "null" ], "description": "The kind of social feed (stored as its account type). The valid values depend on the `source`: `facebook`: `account`, `page`, `others`, `hashtag`, `groups`, `tagged`, `ratings`, `influencer`; `instagram_business`: `mentioned`, `posted`, `tagged`, `hashtags`, `stories`, `comments`, `influencer`, `social_listening`; `twitter`: `username`, `hashtag`, `list`, `favorites`, `geocode`, `influencer`; `threads`: `posted`, `keyword`, `mentioned`, `influencer`; `youtube`: `channel`, `playlist`, `posted`, `keyword`; `flickr`: `user`, `hashtag`, `posted`; `tumblr`: `account`, `hashtag`; `tiktok`: `account`; `tiktok_business`: `account`, `mentioned`; `hootsuite`: `account`, `scheduled_posts`; `linkedin`: `person`, `company`, `tagged`, `mentioned`; `google_news`: `keyword`, `location`, `topic`; `public_post`: `post`, `reviews`; `form_submission`: `form`, `experience`; `creator_iq`: `campaign`. Other sources don't have kinds.", "example": "hashtags" }, "SocialFeedStatus": { "type": "string", "description": "The status of the social feed. `active` feeds ingest posts and `inactive` feeds don't. The other values are set by the system: `error` when the account needs to be reauthorized, `queued`, `needs_stream` and `streamed` while ingestion is being set up, `token_requested` while waiting for an influencer to authorize access, `deprecated` when the source is no longer supported, and `unknown`.", "enum": [ "active", "inactive", "error", "queued", "needs_stream", "streamed", "token_requested", "deprecated", "unknown" ], "example": "active" }, "PreProcessingRule": { "type": "object", "description": "A pre-processing rule. When a social feed has pre-processing rules, only content matching at least one rule is ingested.", "required": [ "conditions" ], "properties": { "conditions": { "type": "object", "description": "The conditions content must match. All conditions of a rule must match.", "additionalProperties": true, "properties": { "text": { "type": "string", "description": "Text the content must contain.", "example": "sneakers" }, "published_at": { "type": "object", "description": "The publication time range of the content.", "properties": { "$gte": { "type": "string", "format": "date-time", "description": "At or after this time.", "example": "2025-01-01T00:00:00Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Before this time.", "example": "2026-01-01T00:00:00Z" } } } } } }, "example": { "conditions": { "text": "sneakers", "published_at": { "$gte": "2025-01-01T00:00:00Z" } } } }, "SocialFeedAttributes": { "type": "object", "description": "The attributes of a social feed. Attributes marked as only returned to authenticated requests are omitted when the social feed is retrieved with an influencer authorization JWT.", "properties": { "name": { "type": [ "string", "null" ], "description": "A label that identifies the social feed. When not set, the account name, hashtag, URL or other identifier of the feed is returned instead.", "example": "#acmesummer" }, "source": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedSource" } ], "description": "The source (network or channel) the social feed ingests posts from.", "example": "instagram_business" }, "type": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedKind" } ], "description": "The kind of social feed. Always `null` for `spark` social feeds." }, "status": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedStatus" } ], "description": "The status of the social feed. Only returned to authenticated requests." }, "moderated": { "type": "boolean", "description": "Whether posts must be moderated before they're displayed. When `false`, new posts are public by default. Only returned to authenticated requests.", "example": true }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the feed at the source (for example an Instagram business account ID, a page ID or an RSS URL), when applicable. Only returned to authenticated requests.", "example": "17841400008460056" }, "options": { "type": [ "object", "null" ], "description": "Source-specific options. For `public_post` social feeds, only the public settings are returned: `email`, `custom_field`, `author_name` and `media_url` (whether each field is shown or required), `multiple_files` and `terms`; or, when the feed is linked to a form, `form_id`, `form_team_id` and (to authenticated requests) the `email_template_id` and field mapping. For other sources, the options are only returned to authenticated requests.", "additionalProperties": true, "example": { "email": true, "custom_field": false, "author_name": true, "media_url": false, "multiple_files": false, "terms": "https://example.com/terms" } }, "pre_processing_rules": { "type": [ "array", "null" ], "description": "The pre-processing rules that determine which content is ingested.", "items": { "$ref": "#/components/schemas/PreProcessingRule" }, "example": [] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the social feed was created. Only returned to authenticated requests.", "example": "2025-01-06T09:20:00.000Z", "readOnly": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the social feed was last updated. Only returned to authenticated requests.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true } } }, "SocialFeedRelationships": { "type": "object", "description": "The social feed's relationships. Unless a relationship is requested with the `include` query parameter, only `meta.included: false` is returned.", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board the social feed adds posts to. Only returned when the access token has the `tints:read` scope.", "properties": { "data": { "description": "Only returned when included.", "allOf": [ { "$ref": "#/components/schemas/TintIdentifier" } ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/teams/1/tints/42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "account": { "type": "object", "description": "The connected account used to ingest posts. Only returned when the access token has the `accounts:read` scope.", "properties": { "data": { "description": "Only returned when included. `null` for sources that don't use an account.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "account" ], "example": "account" }, "id": { "type": "string", "example": "77" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "form": { "type": "object", "description": "The form linked to a `public_post` social feed. Only returned when the access token has the `forms:read` scope.", "properties": { "data": { "description": "Only returned when included. `null` when no form is linked.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "form" ], "example": "form" }, "id": { "type": "string", "example": "19" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "right_request_term": { "type": "object", "description": "The right request terms sent to influencers. Only returned when the access token has the `right_request_terms:read` scope, or with an influencer authorization JWT.", "properties": { "data": { "description": "Only returned when included. `null` unless the social feed's `type` is `influencer`.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "right_request_term" ], "example": "right_request_term" }, "id": { "type": "string", "example": "5" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } }, "SocialFeed": { "type": "object", "description": "A social feed, which ingests posts from a source into a board.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the social feed.", "example": "311", "readOnly": true }, "type": { "$ref": "#/components/schemas/SocialFeedType" }, "attributes": { "$ref": "#/components/schemas/SocialFeedAttributes" }, "relationships": { "$ref": "#/components/schemas/SocialFeedRelationships" } } }, "SocialFeedOptionsForRequest": { "type": "object", "description": "Source-specific options. `public_post`: `email`, `custom_field`, `author_name`, `media_url` (booleans: whether the field is shown or required), `multiple_files` (boolean), `terms` (URL), `email_template_id` (the ID of an email template of type `review_reply`, as a string), and, for feeds linked to a form, the field mapping keys (`author.name`, `author.email`, `author.avatar`, `media`, `text`, `alternative_text`, `rating`, `title`, `tags`, `incentivized`). `review_trackers` (create only): `name`, `address`, `city` and `country` (required), `state` and `zip`. `google_news`: `lang`. `form_submission`: `author_image_url_key`, `author_name_field`, `author_username_key`, `post_body_field`, `post_media_url_key`, `post_tags_key`, `post_title_key`. `mission`: `activity_item_types` (array of strings). `options` is required when creating `public_post`, `review_trackers`, `google_news`, `form_submission` and `mission` social feeds.", "additionalProperties": true, "example": { "email": true, "custom_field": false, "author_name": true, "media_url": false, "multiple_files": false, "terms": "https://example.com/terms" } }, "NewSocialFeed": { "type": "object", "description": "The social feed to create. Which attributes are required depends on the `source` and `type`: accounts-based sources (`facebook`, `instagram_business`, `twitter`, `threads`, `youtube`, `flickr`, `tumblr`, `tiktok`, `tiktok_business`, `hootsuite`, `slack`, `pinterest`, `creator_iq`) require `account_id` (except when `type` is `influencer`), and other sources reject it; `instagram_business`, `hootsuite`, `pinterest`, `creator_iq`, `slack`, `spark`, `form_submission` and `mission` require `external_id` (the ID of the account's business account, board, channel, campaign, form, experience or mission); `rss` requires `external_id` (the feed URL); `instagram_business` with `type` `hashtags` requires `search_term` starting with `#`, and with `social_listening` a business username; `twitter` requires `search_term` (a hashtag starting with `#` when `type` is `hashtag`), except for `influencer` feeds, which require `external_id`; `threads` with `type` `keyword`, `flickr` with `hashtag` or `user`, `google_news`, `slack` and `spark` require `search_term`; `influencer` feeds require `contact` and `right_request_term_id`. A board can only have one social feed per source and identifier.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SocialFeedType" }, "attributes": { "type": "object", "required": [ "source", "tint_id" ], "properties": { "source": { "allOf": [ { "$ref": "#/components/schemas/SocialFeedSource" } ], "description": "The source to ingest posts from. `linkedin` is no longer supported.", "example": "instagram_business" }, "tint_id": { "type": "integer", "description": "The ID of the board the social feed adds posts to. You must have access to the board.", "example": 42 }, "type": { "$ref": "#/components/schemas/SocialFeedKind" }, "name": { "type": [ "string", "null" ], "description": "A label that identifies the social feed. Defaults to a name derived from the source.", "example": "#acmesummer" }, "account_id": { "type": [ "integer", "null" ], "description": "The ID of the connected account used to ingest posts. It must be one of your accounts.", "example": 77 }, "external_id": { "type": [ "string", "null" ], "description": "The ID of the feed at the source, or the feed URL for `rss`.", "example": "17841400008460056" }, "search_term": { "type": [ "string", "null" ], "description": "The hashtag, keyword, username or channel to ingest, depending on the source and type.", "example": "#acmesummer" }, "moderated": { "type": "boolean", "description": "Whether posts must be moderated before they're displayed.", "default": true, "example": true }, "options": { "$ref": "#/components/schemas/SocialFeedOptionsForRequest" }, "pre_processing_rules": { "type": "array", "description": "The pre-processing rules that determine which content is ingested.", "items": { "$ref": "#/components/schemas/PreProcessingRule" }, "example": [] }, "form_id": { "type": [ "integer", "null" ], "description": "The ID of a form to link to a `public_post` social feed. It must be one of your forms.", "example": null }, "right_request_term_id": { "type": [ "integer", "null" ], "description": "The ID of the right request terms sent to the influencer. Required when `type` is `influencer`; must not be sent otherwise.", "example": null }, "contact": { "type": [ "object", "null" ], "description": "The influencer to send the authorization request to. Required when `type` is `influencer`; must not be sent otherwise.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The influencer's email address.", "example": "jane.doe@example.com" } }, "example": null } } } } }, "SocialFeedWritableAttributes": { "type": "object", "description": "Attributes that can be changed on an existing social feed. Only the attributes sent are changed.", "properties": { "name": { "type": [ "string", "null" ], "description": "A label that identifies the social feed.", "example": "#acmesummer" }, "status": { "type": "string", "description": "Activates or deactivates the social feed. The status of a `token_requested` social feed can't be changed.", "enum": [ "active", "inactive" ], "example": "inactive" }, "moderated": { "type": "boolean", "description": "Whether posts must be moderated before they're displayed.", "example": false }, "account_id": { "type": [ "integer", "null" ], "description": "The ID of the connected account used to ingest posts, which must be one of your accounts of the same source. Required (can't be removed) for account-based sources; can't be changed for `influencer` feeds; must be `null` for other sources.", "example": 78 }, "options": { "$ref": "#/components/schemas/SocialFeedOptionsForRequest" }, "pre_processing_rules": { "type": "array", "description": "The pre-processing rules that determine which content is ingested. Replaces all existing rules.", "items": { "$ref": "#/components/schemas/PreProcessingRule" }, "example": [] }, "form_id": { "type": [ "integer", "null" ], "description": "The ID of a form linked to a `public_post` social feed; must be one of your forms. Must not be sent for other sources.", "example": 19 } } }, "SocialFeedBulkUpdate": { "type": "object", "description": "A social feed to update, identified by its `id`. In bulk updates, only `name`, `status`, `moderated`, `account_id` and `options` are saved.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the social feed.", "example": "311" }, "type": { "$ref": "#/components/schemas/SocialFeedType" }, "attributes": { "$ref": "#/components/schemas/SocialFeedWritableAttributes" } } }, "SocialFeedUpdate": { "type": "object", "description": "The social feed changes. The `id` is optional; the social feed is identified by the URL.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the social feed.", "example": "311" }, "type": { "$ref": "#/components/schemas/SocialFeedType" }, "attributes": { "$ref": "#/components/schemas/SocialFeedWritableAttributes" } } }, "SocialFeedMetric": { "type": "object", "description": "The number of posts ingested by the social feed during a period.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The beginning of the period, as a Unix timestamp in milliseconds.", "example": "1741910400000", "readOnly": true }, "type": { "type": "string", "description": "The resource type. Always `social_feed_metric`.", "enum": [ "social_feed_metric" ], "example": "social_feed_metric" }, "attributes": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "The beginning of the period.", "example": "2025-03-14T00:00:00.000Z", "readOnly": true }, "count": { "type": "integer", "description": "The number of posts ingested during the period.", "example": 128, "readOnly": true } } } } }, "ExperienceWritableAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "An internal name used to tell experiences apart. Can't be blank.", "minLength": 1, "example": "Summer Sweepstakes 2025" }, "status": { "$ref": "#/components/schemas/experienceStatuses" }, "title": { "type": [ "string", "null" ], "description": "The page title, shown in the browser tab and search results.", "example": "Win a trip to Hawaii" }, "description": { "type": [ "string", "null" ], "description": "The page description, used in search results and link previews.", "example": "Enter our summer sweepstakes for a chance to win a trip for two." }, "slug": { "type": [ "string", "null" ], "description": "The part of the public URL that identifies the experience. Letters, digits, `_` and `-` only, and it can't start with a digit. Must be unique within the team. Required once the experience is published; when left blank, one is generated from the title (or name) on publication.", "pattern": "^(?!\\d)[a-zA-Z0-9_-]+$", "example": "summer-sweepstakes" }, "domain_id": { "type": [ "integer", "null" ], "description": "The ID of the team's custom domain to serve the experience from, or `null` for the default domain.", "example": 3 }, "analytics_id": { "type": [ "string", "null" ], "description": "The analytics measurement ID. Must start with `G-` for `google_analytics` or `GTM-` for `google_tag_manager`.", "example": "GTM-5XK7Q2P" }, "analytics_type": { "$ref": "#/components/schemas/experienceAnalyticsTypes" }, "captcha_type": { "$ref": "#/components/schemas/experienceCaptchaTypes" }, "captcha_public_key": { "type": [ "string", "null" ], "description": "The captcha provider's public site key. Required when `captcha_type` is set.", "example": null }, "captcha_private_key": { "type": [ "string", "null" ], "description": "The captcha provider's secret key. Required when `captcha_type` is set. Never returned.", "writeOnly": true, "example": null }, "cookie_consent": { "type": "boolean", "description": "Whether a cookie consent banner is displayed.", "default": false, "example": true }, "noindex": { "type": "boolean", "description": "Whether search engines are asked not to index the experience.", "default": false, "example": false }, "favicon_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the favicon.", "example": "https://cdn.example.com/favicons/acme.png" }, "data": { "$ref": "#/components/schemas/ExperienceData" } } }, "NewExperience": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ExperienceWritableAttributes" }, { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/experienceTypes" } ], "description": "The kind of experience. Can't be changed later." }, "status": { "allOf": [ { "$ref": "#/components/schemas/experienceStatuses" } ], "default": "active" } } } ] } } }, "ExperienceIdentifier": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the experience.", "example": "42" }, "type": { "type": "string", "enum": [ "experience" ], "example": "experience" } } }, "ExperienceUpdate": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ExperienceWritableAttributes" } ], "description": "The attributes to change. The experience `type` can't be changed and is ignored." } } }, "ExperienceBulkUpdate": { "allOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The ID of the experience to update.", "example": "42" } } }, { "$ref": "#/components/schemas/ExperienceUpdate" } ] }, "PublicExperience": { "type": "object", "description": "An experience, as returned to unauthenticated requests: no internal attributes, no relationships, and only the published content.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the experience.", "readOnly": true, "example": "42" }, "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/ExperiencePublicAttributes" }, { "type": "object", "properties": { "data": { "type": "object", "description": "Only the published version of each part of the experience's content.", "properties": { "published": { "$ref": "#/components/schemas/ExperienceSections" }, "locales": { "type": "object", "properties": { "published": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "example": [ { "value": "en", "isDefault": true } ] } } }, "translations": { "type": "object", "properties": { "published": { "type": "object", "additionalProperties": true, "example": { "en": {} } } } }, "customFonts": { "type": "object", "properties": { "published": { "type": "object", "additionalProperties": true, "example": {} } } } } } } } ] }, "links": { "$ref": "#/components/schemas/ExperiencePublicLinks" } } }, "FormSubmissionAttributes": { "type": "object", "properties": { "data": { "type": "object", "description": "The submitted fields as key/value pairs, exactly as they were sent. For poll experiences, `post_id` is the ID of the post voted for and `vote` the number of votes.", "additionalProperties": true, "example": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" } }, "user_agent": { "type": [ "string", "null" ], "description": "The `User-Agent` header of the request that created the submission.", "readOnly": true, "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15" }, "referer": { "type": [ "string", "null" ], "description": "The `Referer` header of the request that created the submission.", "readOnly": true, "example": "https://contests.example.com/summer-sweepstakes" }, "locale": { "type": [ "string", "null" ], "description": "The `locale` query parameter sent with the submission, if any.", "readOnly": true, "example": "en" }, "metadata": { "type": [ "object", "null" ], "description": "Extra data sent in the `X-TINT-Metadata` header (as a URL-encoded query string) when the submission was created. `null` when none was sent.", "additionalProperties": true, "readOnly": true, "example": { "utm_source": "newsletter" } }, "remote_ip_city": { "type": [ "string", "null" ], "description": "The city of the submitter, based on their IP address. `null` when unknown.", "readOnly": true, "example": "Vancouver" }, "remote_ip_most_specific_subdivision": { "type": [ "string", "null" ], "description": "The ISO 3166-2 code (without the country prefix) of the most specific subdivision of the submitter, based on their IP address. `null` when unknown.", "readOnly": true, "example": "BC" }, "remote_ip_country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-2 code of the submitter's country, based on their IP address. `null` when unknown.", "readOnly": true, "example": "CA" }, "city": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated; use `remote_ip_city`, `remote_ip_most_specific_subdivision`, and `remote_ip_country` instead. The comma-separated combination of those three attributes, or `null` when all are unknown.", "readOnly": true, "example": "Vancouver, BC, CA" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the form was submitted.", "example": "2025-03-14T16:42:07.000Z" } } }, "FormSubmissionRelationships": { "type": "object", "readOnly": true, "description": "Unless stated otherwise, a relationship's `data` is only present when it's listed in the `include` query parameter; otherwise its `meta.included` is `false`.", "properties": { "person": { "type": "object", "description": "The loyalty member who submitted the form. `data` is always present; its `id` is `null` when the submitter wasn't matched to a loyalty member.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "person" ], "example": "person" }, "id": { "type": [ "string", "null" ], "description": "The ID of the loyalty member, or `null`.", "example": "65f3a1c2e4b0a91d2c7e8f10" } } } } }, "experience": { "type": "object", "description": "The experience the form was submitted to. Only present when the request is authenticated with the `experiences:read` scope.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "id": { "type": "string", "description": "The ID of the experience.", "example": "42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "post": { "type": "object", "description": "The post voted for in a poll experience (from `data.post_id`). Only present when the request is authenticated with the `posts:read` scope. When included, `data` is `null` if the submission has no matching post.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "description": "The ID of the post.", "example": "7731902" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "terms": { "type": "object", "description": "The rights terms the submitter accepted. Only returned for submissions to forms (not experiences), and never included.", "properties": { "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "files": { "type": "object", "description": "The files attached to the submission.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "upload" ], "example": "upload" }, "id": { "type": "string", "description": "The signed ID of the file.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6NDU2NzgsInB1ciI6ImJsb2JfaWQifX0=--1a2b3c4d5e6f70819a2b3c4d5e6f708192a3b4c5" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } }, "FormSubmission": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the form submission.", "readOnly": true, "example": "88213" }, "type": { "type": "string", "enum": [ "form_submission" ], "example": "form_submission" }, "attributes": { "$ref": "#/components/schemas/FormSubmissionAttributes" }, "relationships": { "$ref": "#/components/schemas/FormSubmissionRelationships" } } }, "FormSubmissionFields": { "type": "object", "description": "The experience's form fields as key/value pairs; they are stored as is in the submission's `data`. For poll experiences, send `post_id` (the ID of the post voted for) and `vote` (the number of votes, usually `1`). When the experience uses a captcha, also send the `g-recaptcha-response` (Google reCAPTCHA) or `h-captcha-response` (hCaptcha) token.", "additionalProperties": true, "example": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" } }, "FormSubmissionMetric": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The group's value: the beginning of the `created_at` interval, the `post_id`, the `remote_ip`, or the data key, depending on the `group` query parameter.", "readOnly": true, "example": "2025-03-01T00:00:00.000Z" }, "type": { "type": "string", "enum": [ "form_submission_metric" ], "example": "form_submission_metric" }, "attributes": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "description": "The number of submissions in the group. When grouping by `post_id`, the sum of the `vote` values; when grouping by `data`, the sum of the key's numeric values.", "example": 128 }, "created_at": { "type": "string", "format": "date-time", "description": "The beginning of the interval. Only present when grouping by `created_at`.", "example": "2025-03-01T00:00:00.000Z" }, "key": { "type": "string", "description": "The data key. Only present when grouping by `data` or `data.keys`.", "example": "vote" }, "post_id": { "type": [ "string", "null" ], "description": "The ID of the post voted for. Only present when grouping by `post_id` for a poll experience.", "example": "7731902" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "post": { "type": "object", "description": "The post voted for. Only present when grouping by `post_id` for a poll experience. `data` is only present when `post` is listed in the `include` query parameter; otherwise `meta.included` is `false`.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "description": "The ID of the post.", "example": "7731902" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "NewFormSubmissionExportRequest": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "form_submission_export_request" ], "example": "form_submission_export_request" }, "attributes": { "type": "object", "required": [ "experience_id" ], "properties": { "experience_id": { "type": "integer", "description": "The ID of the experience whose submissions are exported. This, not the `experience_id` in the path, determines which experience is exported; the user must have access to it.", "example": 42 }, "filters": { "type": "object", "description": "Only exports the submissions matching these filters.", "properties": { "created_at": { "type": "object", "description": "Only exports the submissions created in this range. Either bound can be left out.", "properties": { "$gte": { "type": "string", "format": "date-time", "description": "Created on or after this date and time.", "example": "2025-03-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "Created on or before this date and time.", "example": "2025-03-31T23:59:59.000Z" } } } } }, "include_files": { "type": "boolean", "description": "Whether to add the submitted files to the ZIP file.", "default": false, "example": true } } } } }, "FormSubmissionExportRequest": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the export request.", "readOnly": true, "example": "OxZZQtuh5sXIKA" }, "type": { "type": "string", "enum": [ "form_submission_export_request" ], "example": "form_submission_export_request" }, "attributes": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/exportStatus" }, "url": { "allOf": [ { "$ref": "#/components/schemas/ExportUrl" } ], "description": "Once `status` is `success`, a signed URL to a ZIP file containing `form_submissions.csv` (and the submitted files when `include_files` was `true`), valid for 15 minutes. Every request returns a new URL. `null` until then.", "example": null } } }, "relationships": { "type": "object", "readOnly": true, "description": "A relationship's `data` is only present when it's listed in the `include` query parameter; otherwise its `meta.included` is `false`.", "properties": { "experience": { "type": "object", "description": "The experience whose submissions are exported.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "id": { "type": "string", "description": "The ID of the experience.", "example": "42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "form": { "type": "object", "description": "The same resource as `experience`.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "experience" ], "example": "experience" }, "id": { "type": "string", "description": "The ID of the experience.", "example": "42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "user": { "type": "object", "description": "The user who requested the export.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user" ], "example": "user" }, "id": { "type": "string", "description": "The ID of the user.", "example": "7" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL of the export request.", "example": "https://api.tintup.com/v2/teams/1/experiences/42/form_submissions/export/requests/OxZZQtuh5sXIKA" } } } } }, "PostsInNotInFilter": { "title": "Include or exclude", "type": "object", "description": "Include and exclude lists.", "properties": { "$in": { "type": "string", "description": "A comma-separated list of values; matches posts with any of them.", "example": "featured" }, "$notin": { "type": "string", "description": "A comma-separated list of values; excludes posts with any of them.", "example": "follow up" } } }, "PostsTimeRangeFilter": { "title": "Time range", "type": "object", "description": "Time operators. Values are ISO 8601 date-times.", "properties": { "$eq": { "type": "string", "format": "date-time", "description": "Equal to.", "example": "2025-03-14T16:42:07Z" }, "$gt": { "type": "string", "format": "date-time", "description": "After.", "example": "2025-03-01T00:00:00Z" }, "$gte": { "type": "string", "format": "date-time", "description": "At or after.", "example": "2025-03-01T00:00:00Z" }, "$lt": { "type": "string", "format": "date-time", "description": "Before.", "example": "2025-04-01T00:00:00Z" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before.", "example": "2025-03-31T23:59:59Z" } } }, "PostSource": { "type": "string", "description": "The network or channel the content comes from.", "enum": [ "creator_iq", "custom", "email", "externally_sourced_posts_account", "facebook", "flickr", "form_submission", "google_news", "hootsuite", "instagram_business", "linkedin", "mission", "pinterest", "public_post", "review_trackers", "rss", "slack", "sms", "spark", "threads", "tiktok", "tiktok_business", "tumblr", "twitter", "youtube" ], "example": "instagram_business" }, "PostAuthorAttribute": { "type": "object", "description": "The author of the post. The same author is also available through the `author` relationship. `email`, `phone` and `remote_ip` are only returned to authenticated requests.", "readOnly": true, "properties": { "name": { "type": [ "string", "null" ], "description": "The author's display name.", "example": "Jane Doe" }, "username": { "type": [ "string", "null" ], "description": "The author's username at the source.", "example": "janedoe" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the author's profile.", "example": "https://example.com/janedoe" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the author's avatar.", "example": "https://cdn.example.com/avatars/janedoe.jpg" }, "external_id": { "type": [ "string", "null" ], "description": "The author's ID at the source.", "example": "17841400008460056" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The author's email address.", "example": "jane.doe@example.com" }, "phone": { "type": [ "string", "null" ], "description": "The author's phone number.", "example": "+15555550123" }, "remote_ip": { "type": [ "string", "null" ], "description": "The author's anonymized IP address, for posts submitted through a public post form.", "example": "203.0.113.0" } } }, "PostStatus": { "type": "string", "description": "The moderation status of the post. `public` posts are displayed; `private` posts are hidden; the `*_deleted` statuses are hidden and set by moderation, privacy requests, or the author deleting the post at the source; `image_moderation_*` statuses are set by image moderation; `custom_post` is used internally.", "enum": [ "public", "private", "deleted", "author_deleted", "privacy_deleted", "moderation_deleted", "image_moderation_pending", "image_moderation_deleted", "image_moderation_failed", "custom_post" ], "example": "public" }, "PostStatusReason": { "type": "string", "description": "A reason explaining the post's moderation status.", "enum": [ "legal_transgression", "inappropriate", "foreign_language", "contains_private_info", "unrelated", "misleading", "fake", "harmful_content", "wrong_language", "off_topic", "spam", "low_effort", "nonsense", "auto_moderation", "auto_moderation_nsfw", "auto_moderation_author", "auto_moderation_keyword", "auto_moderation_remote_ip" ], "example": "off_topic" }, "PostAttributes": { "type": "object", "description": "The attributes of a post. Attributes marked as only returned to authenticated requests are omitted from public responses.", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/PostSource" } ], "description": "The source (network or channel) of the post." }, "external_id": { "type": "string", "description": "The ID of the post at the source. Generated for custom and public posts.", "example": "17912345678901234" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the post at the source, or `null` if there isn't one.", "example": "https://www.instagram.com/p/C4xYz12AbCd/" }, "title": { "type": [ "string", "null" ], "description": "The title of the post, or `null` if it doesn't have one.", "example": null }, "text": { "type": [ "string", "null" ], "description": "The text of the post, or `null` if it's empty.", "example": "Loving my new Acme sneakers!" }, "alternative_text": { "type": [ "string", "null" ], "description": "The alternative text describing the post's media, for accessibility.", "example": "A pair of white Acme sneakers on a beach." }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the post was published at the source.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "highlighted": { "type": [ "boolean", "null" ], "description": "Whether the post is highlighted.", "example": false }, "pinned": { "type": [ "boolean", "null" ], "description": "Whether the post is pinned to the top of the board.", "example": false }, "tags": { "type": [ "array", "null" ], "description": "The tags assigned to the post.", "items": { "type": "string" }, "example": [ "featured" ] }, "carousel": { "type": "boolean", "description": "Whether the post is one of several media items published together.", "example": false, "readOnly": true }, "media_type": { "type": "string", "enum": [ "text_only", "image", "video", "carousel" ], "description": "The type of media attached to the post: `carousel` when it's one of several media items published together, `video` or `image` for a single attachment, and `text_only` when it has no media.", "example": "image", "readOnly": true }, "image_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the post's image, or `null` if it has none.", "example": "https://cdn.example.com/posts/9001/media.jpg", "readOnly": true }, "video_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the post's video, or `null` if it has none.", "example": null, "readOnly": true }, "attachment_id": { "type": [ "string", "null" ], "description": "An opaque identifier of the post's media attachment.", "example": "aHR0cHM6Ly9jZG4uZXhhbXBsZS5jb20vcG9zdHMvOTAwMS9tZWRpYS5qcGc=", "readOnly": true }, "author": { "$ref": "#/components/schemas/PostAuthorAttribute" }, "metadata": { "type": "object", "description": "Machine learning metadata about the post (also available through the dedicated attributes). Keys without a value are omitted.", "readOnly": true, "properties": { "language": { "type": "string", "description": "The dominant language of the text.", "example": "en" }, "sentiment": { "type": "string", "description": "The sentiment of the text.", "example": "positive" }, "image_nsfw": { "type": "number", "description": "The NSFW score of the image.", "example": 0.02 }, "image_phash": { "type": "string", "description": "The perceptual hash of the image.", "example": "d1c4f0e0b0a09080" }, "image_sentiments": { "type": "array", "description": "The emotions detected in the image.", "items": { "type": "string" }, "example": [ "happy" ] }, "image_objects": { "type": "array", "description": "The objects detected in the image.", "items": { "type": "string" }, "example": [ "shoe", "beach" ] }, "image_objects_rekognition": { "type": "array", "deprecated": true, "description": "Deprecated. Same as `image_objects`.", "items": { "type": "string" }, "example": [ "shoe", "beach" ] } } }, "language": { "type": [ "string", "null" ], "description": "The dominant language of the text (ISO 639-1 code). `null` when not detected.", "example": "en", "readOnly": true }, "rating": { "type": [ "integer", "null" ], "description": "The review rating from 0 to 100.", "minimum": 0, "maximum": 100, "example": 80 }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the review is from a verified buyer. Only set on reviews; `null` for other posts.", "example": null }, "incentivized": { "type": [ "boolean", "null" ], "description": "Whether the reviewer received an incentive. Only set on reviews; `null` for other posts.", "example": null }, "status": { "allOf": [ { "$ref": "#/components/schemas/PostStatus" } ], "description": "The moderation status of the post. Only returned to authenticated requests." }, "status_reasons": { "type": [ "array", "null" ], "description": "The reasons for the post's moderation status. Only returned to authenticated requests.", "items": { "$ref": "#/components/schemas/PostStatusReason" }, "example": null }, "last_moderated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the post was last moderated. Only returned to authenticated requests.", "example": "2025-03-15T09:03:11.000Z", "readOnly": true }, "custom_field": { "type": [ "string", "null" ], "description": "The value of the custom field of a public post form, or `null`. Only returned to authenticated requests.", "example": null }, "sentiment": { "type": [ "string", "null" ], "description": "The sentiment of the text. Only returned to authenticated requests.", "enum": [ "positive", "negative", "neutral", null ], "example": "positive", "readOnly": true }, "image_nsfw": { "type": [ "number", "null" ], "description": "The NSFW score of the image, from 0 to 1. `null` when not analyzed. Only returned to authenticated requests.", "minimum": 0, "maximum": 1, "example": 0.02, "readOnly": true }, "image_phash": { "type": [ "string", "null" ], "description": "The perceptual hash of the image, used to find duplicates. `null` when not computed. Only returned to authenticated requests.", "example": null, "readOnly": true }, "image_sentiments": { "type": [ "array", "null" ], "description": "The emotions detected in the image. `null` when not analyzed. Only returned to authenticated requests.", "items": { "type": "string" }, "example": null, "readOnly": true }, "image_objects": { "type": [ "array", "null" ], "description": "The objects detected in the image. `null` when not analyzed. Only returned to authenticated requests.", "items": { "type": "string" }, "example": [ "shoe", "beach" ], "readOnly": true }, "hue_probability": { "type": "null", "deprecated": true, "description": "Deprecated. Always `null`. Only returned to authenticated requests.", "example": null, "readOnly": true } } }, "PostRelationships": { "type": "object", "description": "The post's relationships. Unless a relationship is requested with the `include` query parameter, only `meta.included: false` is returned (`social_feed` and `tint` always return `data`).", "readOnly": true, "properties": { "social_feed": { "type": "object", "description": "The social feed the post was ingested from. Returned to unauthenticated requests or when the access token has the `social_feeds:read` scope.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "social_feed" ], "example": "social_feed" }, "id": { "type": "string", "example": "311" } } } } }, "tint": { "type": "object", "description": "The board the post belongs to. Only returned when the access token has the `tints:read` scope.", "properties": { "data": { "$ref": "#/components/schemas/TintIdentifier" }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/teams/1/tints/42" } } } } }, "author": { "type": "object", "description": "The author of the post. The author's ID is the post's ID.", "properties": { "data": { "type": "object", "description": "Only returned when included.", "properties": { "type": { "type": "string", "enum": [ "author" ], "example": "author" }, "id": { "type": "string", "example": "9001" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "replies": { "type": "object", "description": "The replies to the post. Inactive replies are only included when the access token has the `replies:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply" ], "example": "reply" }, "id": { "type": "string", "example": "88" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "products": { "type": "object", "description": "The product tags of the post (resource type `product_tag`). Returned to unauthenticated requests or when the access token has the `products:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product_tag" ], "example": "product_tag" }, "id": { "type": "string", "example": "501" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "product_tags": { "type": "object", "description": "The product tags on the post (see also `products`). Only returned to unauthenticated requests or when the access token has the `products:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "product_tag" ], "example": "product_tag" }, "id": { "type": "string", "example": "501" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "cta_associations": { "type": "object", "description": "The calls to action associated with the post, directly or through a saved filter. Returned to unauthenticated requests or when the access token has the `ctas:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cta_association" ], "example": "cta_association" }, "id": { "type": "string", "example": "64" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "asset": { "type": "object", "description": "The asset created from the post. Only returned when the access token has the `assets:read` scope.", "properties": { "data": { "description": "Only returned when included. `null` if no asset was created from the post.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "asset" ], "example": "asset" }, "id": { "type": "string", "example": "7300" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "right_requests": { "type": "object", "description": "The right requests sent for the post. Only returned when the access token has the `right_requests:read` scope.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "right_request" ], "example": "right_request" }, "id": { "type": "string", "example": "210" } } } }, "meta": { "type": "object", "properties": { "included": { "type": "boolean", "description": "`false` when the relationship wasn't requested with the `include` query parameter.", "example": false }, "status": { "type": [ "string", "null" ], "description": "The status of the most recent right request. Only returned when the post has a right request.", "example": "approved" }, "status_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the status of the most recent right request expires, or `null` if it doesn't.", "example": null } } } } }, "siblings": { "type": "object", "description": "The other posts with the same source and external ID in other boards. Only returned when the `collapse` query parameter is `source,external_id`.", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PostType" }, "id": { "type": "string", "example": "9002" } } } } } } } }, "Post": { "type": "object", "description": "A post, as returned to authenticated requests.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the post.", "example": "9001", "readOnly": true }, "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "$ref": "#/components/schemas/PostAttributes" }, "relationships": { "$ref": "#/components/schemas/PostRelationships" } } }, "PostDelete": { "type": "object", "description": "A post to delete, identified by its `id`. Posts you don't have access to are ignored.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the post.", "example": "9001" }, "type": { "$ref": "#/components/schemas/PostType" } } }, "NewPostAuthor": { "type": "object", "description": "The author of the post.", "properties": { "name": { "type": "string", "description": "The author's display name. Required for reviews when the Ratings & Reviews social feed requires the author's name.", "example": "Jane Doe" }, "username": { "type": "string", "description": "The author's username.", "example": "janedoe" }, "email": { "type": "string", "format": "email", "description": "The author's email address. Required for public posts and reviews when the social feed shows the email field.", "example": "jane.doe@example.com" }, "phone": { "type": "string", "description": "The author's phone number.", "example": "+15555550123" }, "external_id": { "type": "string", "description": "The author's ID in your system.", "example": "cust_48213" }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "The URL of the author's profile. Must start with `http://` or `https://`.", "example": "https://example.com/janedoe" }, "image_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "The URL of the author's avatar. Must start with `http://` or `https://`.", "example": "https://cdn.example.com/avatars/janedoe.jpg" }, "image_id": { "type": "string", "description": "The signed ID of a file uploaded with `POST /v2/teams/{team_id}/posts/upload`, used as the author's avatar. Only used for custom posts.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6MTIzNDUsInB1ciI6ImJsb2JfaWQifX0=--0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6" } } }, "PostWritableAttributes": { "type": "object", "description": "Attributes that can be changed on an existing post. Only the attributes sent are changed. `title`, `text`, `url`, `custom_field` and `author` can only be changed on custom posts and are ignored for other posts.", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/PostStatus" } ], "description": "The moderation status of the post. Use `public`, `private`, or `deleted` to moderate posts." }, "status_reasons": { "type": [ "array", "null" ], "description": "The reasons for the post's moderation status.", "items": { "$ref": "#/components/schemas/PostStatusReason" }, "example": [ "off_topic" ] }, "highlighted": { "type": "boolean", "description": "Whether the post is highlighted.", "example": true }, "pinned": { "type": "boolean", "description": "Whether the post is pinned to the top of the board.", "example": false }, "tags": { "type": "array", "description": "The tags assigned to the post. A comma-separated string is also accepted.", "items": { "type": "string" }, "example": [ "featured", "follow up" ] }, "alternative_text": { "type": [ "string", "null" ], "description": "The alternative text describing the post's media, for accessibility.", "example": "A pair of white Acme sneakers on a beach." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the review is from a verified buyer. Must be `null` (or omitted) for posts that aren't reviews.", "example": true }, "incentivized": { "type": [ "boolean", "null" ], "description": "Whether the reviewer received an incentive. Must be `null` (or omitted) for posts that aren't reviews.", "example": false }, "title": { "type": [ "string", "null" ], "description": "The title of the post. Custom posts only.", "example": "Summer collection" }, "text": { "type": [ "string", "null" ], "description": "The text of the post. Custom posts only.", "example": "Our summer collection just dropped!" }, "url": { "type": [ "string", "null" ], "format": "uri", "pattern": "^https?://", "description": "The URL the post links to. Must start with `http://` or `https://`. Custom posts only.", "example": "https://example.com/summer" }, "custom_field": { "type": [ "string", "null" ], "description": "The value of the custom field. Custom posts only.", "example": null }, "author": { "allOf": [ { "$ref": "#/components/schemas/NewPostAuthor" } ], "description": "The author of the post. Custom posts only. Send an empty `image_id` to remove the author's uploaded avatar." } } }, "PostBulkUpdate": { "type": "object", "description": "A post to update, identified by its `id`. Posts you don't have access to are ignored.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the post.", "example": "9001" }, "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "$ref": "#/components/schemas/PostWritableAttributes" } } }, "PostsModeratedMetric": { "type": "object", "description": "The number of posts moderated, for one group of dimensions.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/MetricId" }, "type": { "type": "string", "description": "The resource type. Always `posts_metric`.", "enum": [ "posts_metric" ], "example": "posts_metric" }, "attributes": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/MetricCount" }, "dimensions": { "type": [ "object", "null" ], "description": "The values of the dimensions requested with the `group` query parameter for this group, or `null` when the metrics aren't grouped. Time dimensions are returned as `time` (the start of the period), `day_of_week` (0 is Sunday) and `hour_of_day`.", "additionalProperties": true, "readOnly": true, "example": { "tint_id": "42", "status": "public" } } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board. Only returned when grouping by `tint_id` and the access token has the `tints:read` scope.", "properties": { "data": { "$ref": "#/components/schemas/TintIdentifier" } } }, "user": { "type": "object", "description": "The user who moderated the posts. Only returned when grouping by `user_id` and the access token has the `users:read` scope.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ], "example": "user" }, "id": { "type": "string", "example": "16891" } } } } } } } } }, "PostsMetricsTimeFilter": { "type": "object", "description": "The time range. Defaults to the last 14 days. The UTC offset of the last value is used as the time zone for time-based grouping.", "properties": { "$gt": { "type": "string", "format": "date-time", "description": "After this time.", "example": "2025-03-01T00:00:00-05:00" }, "$gte": { "type": "string", "format": "date-time", "description": "At or after this time.", "example": "2025-03-01T00:00:00-05:00" }, "$lt": { "type": "string", "format": "date-time", "description": "Before this time.", "example": "2025-03-15T00:00:00-05:00" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before this time.", "example": "2025-03-14T23:59:59-05:00" } } }, "PostsIngestedMetric": { "type": "object", "description": "The number of posts ingested, for one group of dimensions.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/MetricId" }, "type": { "type": "string", "description": "The resource type. Always `posts_ingested_metric`.", "enum": [ "posts_ingested_metric" ], "example": "posts_ingested_metric" }, "attributes": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/MetricCount" }, "dimensions": { "type": [ "object", "null" ], "description": "The values of the dimensions requested with the `group` query parameter for this group, or `null` when the metrics aren't grouped. Time dimensions are returned as both `time` and `created_at` (the start of the period), or as `day_of_week` (0 is Sunday) and `hour_of_day`. `social_feed_source` is returned as a source name such as `instagram_business`.", "additionalProperties": true, "readOnly": true, "example": { "social_feed_source": "instagram_business", "time": "2025-03-14T00:00:00.000Z", "created_at": "2025-03-14T00:00:00.000Z" } } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "social_feed": { "type": "object", "description": "The social feed. Only returned when grouping by `social_feed_id` and the access token has the `social_feeds:read` scope.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "social_feed" ], "example": "social_feed" }, "id": { "type": "string", "example": "311" } } } } }, "tint": { "type": "object", "description": "The board. Only returned when grouping by `tint_id` and the access token has the `tints:read` scope.", "properties": { "data": { "$ref": "#/components/schemas/TintIdentifier" } } }, "account": { "type": "object", "description": "The account. Only returned when grouping by `account_id` and the access token has the `accounts:read` scope.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account" ], "example": "account" }, "id": { "type": "string", "example": "77" } } } } } } } } }, "PostUpdate": { "type": "object", "description": "The post changes. The `id` is optional; the post is identified by the URL.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the post.", "example": "9001" }, "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "$ref": "#/components/schemas/PostWritableAttributes" } } }, "NewPost": { "type": "object", "description": "The custom post to create. The post's status, external ID and publication time are set by the server. Each file in `media` creates a separate post; when several are sent, the posts are grouped as a carousel.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "type": "object", "properties": { "text": { "type": "string", "description": "The text of the post.", "example": "Our summer collection just dropped!" }, "title": { "type": "string", "description": "The title of the post.", "example": "Summer collection" }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "The URL the post links to. Must start with `http://` or `https://`.", "example": "https://example.com/summer" }, "alternative_text": { "type": "string", "description": "The alternative text describing the post's media, for accessibility.", "example": "A pair of white Acme sneakers on a beach." }, "highlighted": { "type": "boolean", "description": "Whether the post is highlighted.", "default": false, "example": false }, "pinned": { "type": "boolean", "description": "Whether the post is pinned to the top of the board.", "default": false, "example": true }, "tags": { "type": "array", "description": "The tags to assign to the post. A comma-separated string is also accepted.", "items": { "type": "string" }, "example": [ "featured" ] }, "media": { "type": "array", "description": "The signed IDs of images or videos uploaded with `POST /v2/teams/{team_id}/posts/upload`. Files that aren't images or videos are ignored.", "items": { "type": "string" }, "example": [ "eyJfcmFpbHMiOnsiZGF0YSI6MTIzNDUsInB1ciI6ImJsb2JfaWQifX0=--0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6" ] }, "author": { "$ref": "#/components/schemas/NewPostAuthor" } } } } }, "PostRequest": { "type": "object", "description": "An asynchronous request to create one or more posts.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the request, used to check its status.", "example": "OxZZQtuh5sXIKA", "readOnly": true }, "type": { "type": "string", "description": "The resource type. Always `post_create_request`.", "enum": [ "post_create_request" ], "example": "post_create_request" }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "description": "`pending` while the posts are being created, then `success` or `failure`.", "enum": [ "pending", "success", "failure" ], "example": "pending", "readOnly": true } } } } }, "q": { "type": "string", "description": "A full-text search on the text, title, author name and username, and external ID of posts.", "example": "sneakers" }, "id": { "type": "string", "description": "A comma-separated list of post IDs.", "example": "9001,9002" }, "social_feed_id": { "type": "string", "description": "A comma-separated list of social feed IDs.", "example": "311" }, "saved_filter_id": { "type": "integer", "description": "The ID of a saved filter of the board whose criteria are used as defaults for the filters that aren't sent. Only for the board endpoints.", "example": 15 }, "type": { "type": "string", "description": "A comma-separated list of sources (the posts' `type` attribute), for example `instagram_business`.", "example": "instagram_business,tiktok" }, "media_type": { "type": "string", "description": "A comma-separated list of media types among `text`, `image` and `video`.", "example": "image" }, "highlighted": { "type": "boolean", "description": "Returns only highlighted (`true`) or non-highlighted (`false`) posts.", "example": true }, "pinned": { "type": "boolean", "description": "Returns only pinned (`true`) or non-pinned (`false`) posts.", "example": false }, "verified": { "type": "boolean", "description": "Returns only reviews from verified (`true`) or unverified (`false`) buyers.", "example": true }, "incentivized": { "type": "boolean", "description": "Returns only incentivized (`true`) or non-incentivized (`false`) reviews.", "example": false }, "tag": { "description": "A comma-separated list of tags, `true`/`false` to return posts with or without tags, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "featured,follow up" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "language": { "type": "string", "description": "A comma-separated list of ISO 639-1 language codes.", "example": "en,fr" }, "sentiment": { "description": "A comma-separated list of text sentiments (`positive`, `negative`, `neutral`), or an object with `$in` and/or `$notin` lists. Sentiment is only available for English posts.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "positive" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "image_object": { "description": "A comma-separated list of objects detected in the image, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "shoe" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "image_emotions": { "description": "A comma-separated list of emotions detected in the image, or an object with `$in` and/or `$notin` lists.", "oneOf": [ { "title": "Comma-separated list", "type": "string", "example": "happy" }, { "$ref": "#/components/schemas/PostsInNotInFilter" } ] }, "rating": { "description": "A rating (0 to 100) to match exactly, or an object of operators. `$range` takes a comma-separated list of `from-to` ranges, for example `80-100`.", "oneOf": [ { "title": "Exact rating", "type": "integer", "example": 100 }, { "title": "Operators", "type": "object", "properties": { "$eq": { "type": "integer", "description": "Equal to.", "example": 80 }, "$gt": { "type": "integer", "description": "Greater than.", "example": 60 }, "$gte": { "type": "integer", "description": "Greater than or equal to.", "example": 60 }, "$lt": { "type": "integer", "description": "Less than.", "example": 40 }, "$lte": { "type": "integer", "description": "Less than or equal to.", "example": 40 }, "$range": { "type": "string", "description": "A comma-separated list of inclusive `from-to` ranges.", "example": "0-20,80-100" } } } ] }, "published_at": { "description": "A publication time to match exactly, or an object of operators.", "oneOf": [ { "title": "Exact time", "type": "string", "format": "date-time", "example": "2025-03-14T16:42:07Z" }, { "$ref": "#/components/schemas/PostsTimeRangeFilter" } ] }, "product_id": { "type": "string", "description": "A comma-separated list of tagged product IDs, or `true`/`false` to return posts with or without product tags.", "example": "501" }, "product_sku": { "type": "string", "description": "A comma-separated list of tagged product SKUs, or `true`/`false` to return posts with or without product tags.", "example": "ACME-SNK-001" }, "product_family": { "type": "string", "description": "A comma-separated list of tagged product families.", "example": "sneakers" }, "PublicPost": { "type": "object", "description": "A post, as returned to unauthenticated requests. Only public posts are returned, and attributes marked as only returned to authenticated requests are omitted, as are the `tint`, `asset` and `right_requests` relationships.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the post.", "example": "9001", "readOnly": true }, "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "$ref": "#/components/schemas/PostAttributes" }, "relationships": { "$ref": "#/components/schemas/PostRelationships" } } }, "NewPublicPost": { "type": "object", "description": "The public post or review to create. The validation rules depend on the settings of the board's public post or Ratings & Reviews social feed. Each URL in `media_url` creates a separate post; when several are sent, the posts are grouped as a carousel.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/PostType" }, "attributes": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of submission, which selects the social feed: `post` for the board's public post social feed, `reviews` for its Ratings & Reviews social feed. The board must have a social feed of that kind.", "enum": [ "post", "reviews" ], "default": "post", "example": "reviews" }, "text": { "type": "string", "description": "The text of the post. Required for reviews.", "example": "Super comfortable and true to size. Would buy again!" }, "title": { "type": "string", "description": "The title of the post.", "example": "Great everyday sneakers" }, "rating": { "type": "integer", "description": "The rating from 0 to 100. Required for reviews; ignored otherwise.", "minimum": 0, "maximum": 100, "example": 80 }, "custom_field": { "type": "string", "description": "The value of the social feed's custom field. Required when the social feed shows the custom field.", "example": "Order 10482" }, "media_url": { "type": "array", "description": "The URLs of images or videos to attach, each starting with `http://` or `https://`. A comma-separated string is also accepted. Required for reviews when the social feed requires media. Limited to one URL unless the social feed accepts multiple files.", "items": { "type": "string", "format": "uri", "pattern": "^https?://" }, "example": [ "https://cdn.example.com/uploads/sneakers.jpg" ] }, "tags": { "type": "array", "description": "The tags to assign to the post. A comma-separated string is also accepted. Each tag must already exist in the board. For reviews, a tag can also be a product SKU (optionally prefixed with `sku:`) or a product family prefixed with `family:`.", "items": { "type": "string" }, "example": [ "sku:ACME-SNK-001" ] }, "author": { "$ref": "#/components/schemas/NewPostAuthor" } } } } }, "PostsSummaryParameters": { "type": "object", "description": "The posts to summarize. These parameters can also be sent in the query string. Different parameters produce a different summary.", "properties": { "filter": { "type": "object", "description": "The filters applied to the posts included in the summary. The same filters as \"Retrieve a list of public posts for a board\" are supported.", "additionalProperties": true, "example": { "rating": { "$gte": 60 }, "tag": "sku:ACME-SNK-001" } }, "sort": { "type": "string", "description": "The sort order applied to the posts included in the summary.", "example": "-published_at" } } }, "PostsSummary": { "type": "object", "description": "An AI-generated summary of the posts matching a set of filters.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The ID of the posts summary: a deterministic SHA-256 fingerprint of the team and the filter parameters, so the same filters always return the same summary.", "example": "3b6d5c3e9a09a2b47a2d87b6d4a2c65a3b6d5c3e9a09a2b47a2d87b6d4a2c65a" }, "type": { "type": "string", "description": "The resource type. Always `posts_summary`.", "enum": [ "posts_summary" ], "example": "posts_summary" }, "attributes": { "type": "object", "required": [ "status", "fresh" ], "properties": { "status": { "type": "string", "description": "The processing status of the posts summary: `pending` while it's being generated, `ready` once generated, `failed` if it couldn't be generated, and `daily_limit_reached` when the team has reached its daily limit.", "enum": [ "pending", "ready", "failed", "daily_limit_reached" ], "example": "ready", "readOnly": true }, "fresh": { "type": "boolean", "description": "`true` when the summary is `ready`, has content, and hasn't expired yet (`expires_at` is in the future). When `false`, a new summary is generated in the background and the response status is `202`.", "example": true, "readOnly": true }, "summary": { "type": [ "string", "null" ], "description": "The overall verdict. `null` until the summary has been generated.", "example": "Customers love the comfort and design of the sneakers, but some mention sizing runs small.", "readOnly": true }, "key_insights": { "type": [ "array", "null" ], "description": "Short key insights. `null` until the summary has been generated.", "items": { "type": "string" }, "example": [ "Very comfortable for all-day wear", "Sizing runs half a size small" ], "readOnly": true }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the summary was first requested.", "example": "2025-03-14T16:42:07Z", "readOnly": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the summary was last updated.", "example": "2025-03-14T16:42:31Z", "readOnly": true }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time after which the summary is no longer fresh, typically 24 hours after it was generated.", "example": "2025-03-15T16:42:07Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "team": { "type": "object", "description": "The team that owns the posts summary. Only returned when the access token has the `teams:read` scope.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "team" ], "example": "team" }, "id": { "type": "string", "description": "The ID of the team.", "example": "1" } } } } } } } } }, "PostExportRequestType": { "type": "string", "description": "The resource type. Always `post_export_request`.", "enum": [ "post_export_request" ], "example": "post_export_request" }, "NewPostExportRequest": { "type": "object", "description": "The export to request.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/PostExportRequestType" }, "attributes": { "type": "object", "required": [ "tint_id" ], "properties": { "tint_id": { "type": "integer", "description": "The ID of the board whose posts to export. You must have access to the board.", "example": 42 } } } } }, "PostExportRequest": { "type": "object", "description": "An asynchronous request to export the posts of a board to a CSV file.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the request, used to check its status.", "example": "OxZZQtuh5sXIKA", "readOnly": true }, "type": { "$ref": "#/components/schemas/PostExportRequestType" }, "attributes": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/exportStatus" }, "url": { "$ref": "#/components/schemas/ExportUrl" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board whose posts are exported.", "properties": { "data": { "description": "Only returned when included.", "allOf": [ { "$ref": "#/components/schemas/TintIdentifier" } ] }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "user": { "type": "object", "description": "The user who requested the export.", "properties": { "data": { "type": "object", "description": "Only returned when included.", "properties": { "type": { "type": "string", "enum": [ "user" ], "example": "user" }, "id": { "type": "string", "example": "16891" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } }, "links": { "type": "object", "readOnly": true, "properties": { "self": { "type": "string", "format": "uri", "description": "The URL to check the status of the request.", "example": "https://api.tintup.com/v2/teams/1/posts/export/requests/OxZZQtuh5sXIKA" } } } } }, "CollectionType": { "type": "string", "description": "The resource type. Always `collection`.", "enum": [ "collection" ], "example": "collection" }, "CollectionName": { "type": "string", "description": "The name of the collection.", "minLength": 1, "example": "Summer campaign" }, "CollectionStatus": { "type": "string", "description": "Whether the collection is `active` or `archived`.", "enum": [ "active", "archived" ], "example": "active" }, "CollectionPublic": { "type": "boolean", "description": "Whether the collection can be viewed publicly using its `slug`. Making a collection public generates a new slug; making it private removes the slug.", "example": false }, "Collection": { "type": "object", "description": "A collection of assets.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the collection.", "example": "27", "readOnly": true }, "type": { "$ref": "#/components/schemas/CollectionType" }, "attributes": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/CollectionName" }, "status": { "$ref": "#/components/schemas/CollectionStatus" }, "public": { "$ref": "#/components/schemas/CollectionPublic" }, "slug": { "type": [ "string", "null" ], "description": "The public identifier of the collection. `null` unless the collection is public.", "example": null, "readOnly": true }, "assets_count": { "type": "integer", "deprecated": true, "description": "Deprecated. The number of assets in the collection; use `meta.total` of the `assets` relationship instead.", "example": 48, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "When the collection was created.", "example": "2025-02-03T11:30:00.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the collection was last updated.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "assets": { "type": "object", "description": "The assets in the collection.", "properties": { "data": { "type": "array", "description": "The first 25 assets of the collection. Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asset" ], "example": "asset" }, "id": { "type": "string", "example": "7300" } } } }, "links": { "type": "object", "description": "Links to the collection's assets, only returned when included and the collection has assets.", "properties": { "first": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/teams/1/collections/27/assets" }, "next": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/teams/1/collections/27/assets?page%5Bnumber%5D=2" }, "previous": { "type": "string", "format": "uri", "example": "https://api.tintup.com/v2/teams/1/collections/27/assets?page%5Bnumber%5D=1" } } }, "meta": { "type": "object", "properties": { "included": { "type": "boolean", "description": "`false` when the relationship wasn't requested with the `include` query parameter.", "example": false }, "total": { "type": "integer", "description": "The number of assets in the collection.", "example": 48 } } } } } } } } }, "NewCollection": { "type": "object", "description": "The collection to create. New collections are `active`.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/CollectionType" }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "$ref": "#/components/schemas/CollectionName" }, "public": { "allOf": [ { "$ref": "#/components/schemas/CollectionPublic" } ], "default": false } } } } }, "CollectionBulkDelete": { "type": "object", "description": "A collection to delete, identified by its `id`. Collections you don't have access to are ignored.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the collection.", "example": "27" }, "type": { "$ref": "#/components/schemas/CollectionType" } } }, "CollectionWritableAttributes": { "type": "object", "description": "Attributes that can be changed on an existing collection. Only the attributes sent are changed.", "properties": { "name": { "$ref": "#/components/schemas/CollectionName" }, "status": { "$ref": "#/components/schemas/CollectionStatus" }, "public": { "$ref": "#/components/schemas/CollectionPublic" } } }, "CollectionBulkUpdate": { "type": "object", "description": "A collection to update, identified by its `id`. Collections you don't have access to are ignored. In bulk updates, only `name` and `status` are saved.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "The ID of the collection.", "example": "27" }, "type": { "$ref": "#/components/schemas/CollectionType" }, "attributes": { "$ref": "#/components/schemas/CollectionWritableAttributes" } } }, "CollectionUpdate": { "type": "object", "description": "The collection changes. The `id` is optional; the collection is identified by the URL.", "required": [ "type" ], "properties": { "id": { "type": "string", "description": "The ID of the collection.", "example": "27" }, "type": { "$ref": "#/components/schemas/CollectionType" }, "attributes": { "$ref": "#/components/schemas/CollectionWritableAttributes" } } }, "OAuthApplicationType": { "type": "string", "description": "The resource type.", "enum": [ "oauth_application" ], "example": "oauth_application" }, "oauthApplicationVersions": { "type": "integer", "description": "The API version used for requests made with this application's access tokens that don't send an `API-Version` header.", "enum": [ 20190326 ], "example": 20190326 }, "OAuthApplication": { "type": "object", "description": "An OAuth 2.0 application of the team.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the OAuth application.", "example": "17", "readOnly": true }, "type": { "$ref": "#/components/schemas/OAuthApplicationType" }, "attributes": { "type": "object", "required": [ "name", "redirect_uri", "version", "client_id", "created_at", "updated_at" ], "properties": { "name": { "type": "string", "description": "The name of the application, shown to users when they authorize it.", "example": "Acme Reporting" }, "redirect_uri": { "type": [ "string", "null" ], "description": "The URIs users can be redirected to after authorizing the application, separated by spaces or new lines. `null` for older applications created without one.", "example": "https://reports.example.com/auth/callback" }, "version": { "$ref": "#/components/schemas/oauthApplicationVersions" }, "client_id": { "type": "string", "description": "The public identifier of the application, sent as `client_id` in the OAuth flows.", "example": "3a7c1e0b9d8f4e6a2b5c7d9e1f3a5b7c", "readOnly": true }, "client_secret": { "type": "string", "description": "The secret of the application, sent as `client_secret` when requesting access tokens. Only returned when the request includes a valid `id_token`. Keep it confidential.", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "readOnly": true }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the application was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the application was last updated.", "example": "2025-03-14T16:42:07.000Z" } } } } }, "OAuthApplicationWritableAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the application, shown to users when they authorize it.", "minLength": 1, "example": "Acme Reporting" }, "redirect_uri": { "type": "string", "description": "One or more redirect URIs, separated by spaces or new lines. Each must be an absolute `https://` URI without a fragment.", "pattern": "^https://", "example": "https://reports.example.com/auth/callback" }, "version": { "allOf": [ { "$ref": "#/components/schemas/oauthApplicationVersions" } ], "description": "The API version used for requests made with this application's access tokens that don't send an `API-Version` header. Defaults to the API's default version when omitted on creation." } } }, "NewOAuthApplication": { "type": "object", "description": "The OAuth application to create.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/OAuthApplicationType" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/OAuthApplicationWritableAttributes" }, { "required": [ "name", "redirect_uri" ] } ] } } }, "OAuthApplicationUpdate": { "type": "object", "description": "The attributes to change. Omitted attributes are left unchanged.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the OAuth application. Ignored; the path parameter is used instead.", "example": "17" }, "type": { "$ref": "#/components/schemas/OAuthApplicationType" }, "attributes": { "$ref": "#/components/schemas/OAuthApplicationWritableAttributes" } } }, "webhookEventName": { "type": "string", "description": "The name of a webhook event. `offer_*` and `mission_*` are accepted when you create or update a webhook but are never delivered: nothing emits them yet. `event_*` are loyalty events. Their body is the loyalty JSON document with `request_id`, `total_count`, `events` and `created_date`, sent as `application/json` and signed with `X-TINT-Signature` like every other webhook. Events that happen together (e.g. a bulk action on members) are sent up to `batch_size` per request. A `filter` matches the fields of each event's `data` (e.g. `member_info.tier_info.loyalty_tier_name`) and `event_type`, keeping only the matching events, and nothing is sent when none match; the payload transformation template renders that document. `payload_include` and `payload_fields` don't apply to them.", "enum": [ "account_created", "account_updated", "account_destroyed", "asset_created", "asset_updated", "asset_destroyed", "asset_exported", "form_submission_created", "form_submission_exported", "post_created", "post_updated", "post_destroyed", "post_exported", "product_feed_created", "product_feed_updated", "product_feed_destroyed", "teams_user_exported", "transaction_exported", "offer_created", "offer_updated", "offer_destroyed", "mission_created", "mission_updated", "mission_destroyed", "event_member_enrol", "event_member_update", "event_member_delete", "event_member_otp_generation", "event_member_tierupgrade", "event_member_tierdowngrade", "event_points_earned", "event_points_redeemed", "event_points_deducted", "event_points_expired", "event_points_rejected", "event_friend_incentive_request", "event_referral_success", "event_referral_link_share", "event_winback_offer", "event_points_expiration_reminder", "event_rewards_within_reach_reminder", "event_available_rewards_reminder", "event_campaign_entered", "event_campaign_exited", "event_transaction_import_success", "event_transaction_import_failure", "event_member_import_success", "event_member_import_failure", "event_bulk_job_success", "event_bulk_job_failure", "event_workflow_run_failure" ], "example": "asset_created" }, "webhookStatus": { "type": "string", "description": "`active` webhooks receive events. `inactive` webhooks receive nothing; we also set a webhook to `inactive` after more than 50 failed delivery attempts within a week without a successful one in between.", "enum": [ "active", "inactive" ], "default": "active", "example": "active" }, "webhookVersion": { "type": "integer", "description": "The API version the webhook was created with. Defaults to the API's default version. It is not returned in responses.", "enum": [ 20190326 ], "example": 20190326, "writeOnly": true }, "WebhookAttributes": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "The endpoint we send events to. It must use `https` and resolve to a public IP address (private, loopback and link-local addresses are rejected), both when you save the webhook and before every delivery.", "example": "https://hooks.example.com/trueloyal" }, "description": { "type": [ "string", "null" ], "description": "A note to help you identify the webhook. `null` when not set.", "example": "Sync new UGC assets to our DAM." }, "events": { "type": "array", "description": "The event this webhook subscribes to. Exactly one event per webhook: create a separate webhook for each event you want to receive, so that the filter and payload options can differ per event. A comma-separated string is also accepted when creating or updating a webhook.", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/webhookEventName" }, "example": [ "asset_created" ] }, "status": { "$ref": "#/components/schemas/webhookStatus" }, "version": { "$ref": "#/components/schemas/webhookVersion" }, "signing_secret": { "type": [ "string", "null" ], "description": "The secret used to sign each delivery in the `X-TINT-Signature` header (see [Webhook Event Signatures](advocacy/guides/webhook-signatures.html)). When it is not set, deliveries are not signed. Stored encrypted, and only returned when the request includes an `id_token` (see [Changes to Sensitive Data](advocacy/guides/sensitive-data.html)); `null` otherwise.", "example": "whsec_8f14e45fceea167a5a36dedd4bea2543" }, "filter": { "type": "object", "description": "Conditions the event's object must meet for the event to be delivered, in the same syntax as our list filters: a bare value tests equality (a comma-separated value matches any of them), and a nested object maps operators (`$eq`, `$neq`, `$in`, `$notin`, `$gt`, `$gte`, `$lt`, `$lte`, `$contains`, `$notcontains`, `$exists`) to values. Conditions are combined with AND and a blank value is ignored. Keys are the object's attribute names, plus `_id` (to-one) or `_ids` (to-many) for its relationships. The filter is evaluated against the full, untrimmed object before `payload_fields` applies. Events whose payload does not contain the object, and events for which evaluating the filter fails, are delivered anyway. Defaults to `{}` (every event is delivered).", "additionalProperties": true, "default": {}, "example": { "form_id": "2012", "created_at": { "$gte": "2025-01-01T00:00:00Z" } } }, "http_method": { "type": "string", "description": "The HTTP method used to deliver events. The body is sent with every method, including `get` and `delete`.", "enum": [ "post", "get", "put", "patch", "delete" ], "default": "post", "example": "post" }, "headers": { "type": [ "object", "null" ], "description": "Extra request headers sent with every delivery. They override `User-Agent`, `API-Version` and `Content-Type` if you set them. `Host`, `Content-Length`, `Transfer-Encoding` and `X-TINT-Signature` are rejected (case insensitive), as is any name or value containing a line break. Stored encrypted, but returned as is to anyone who can read the webhook. `null` when not set.", "additionalProperties": { "type": "string" }, "example": { "Authorization": "Bearer 3f2a9c71d04b" } }, "payload_include": { "type": "array", "description": "JSON:API include paths that replace the resources the event sideloads by default. Every path must start with `object` (for example `object` or `object.person`); any other root is rejected. Below that root, a relationship the object does not have is ignored. Defaults to `[]`, which keeps the event's default includes. Ignored for events that don't sideload their object.", "items": { "type": "string" }, "default": [], "example": [ "object.person" ] }, "payload_fields": { "type": "object", "description": "JSON:API sparse fieldsets for the payload, keyed by resource type, each listing the fields to keep. A type that is not listed keeps all of its fields. A JSON:API field is an attribute *or* a relationship, so listing only attributes removes that resource's relationships. Applied before `payload_transformation_template`. Defaults to `{}`.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "default": {}, "example": { "form_submission": [ "data", "created_at", "person" ] } }, "payload_transformation_template": { "type": [ "string", "null" ], "description": "A [Liquid](https://shopify.github.io/liquid/) template rendered against the JSON:API document (after `payload_fields` has trimmed it); its output replaces the body. The syntax is checked when you save the webhook, and an undefined path renders as an empty string. We still send `Content-Type: application/vnd.api+json`, so set your own `Content-Type` in `headers` if your template produces something else. `null` when not set.", "example": "{\"text\": \"New submission {{ data.relationships.object.data.id }}\"}" }, "batch_size": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100, "description": "Loyalty events only: the most events a request holds when they happen together, such as a bulk action on members. `1` sends every event in its own request. `null` uses the default of 100.", "example": 10 } } }, "WebhookBase": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/WebhookAttributes" }, { "type": "object", "required": [ "url", "description", "events", "status", "filter", "http_method", "headers", "payload_include", "payload_fields", "payload_transformation_template", "created_at", "updated_at" ], "properties": { "created_at": { "$ref": "#/components/schemas/ReadOnlyDate" }, "updated_at": { "$ref": "#/components/schemas/ReadOnlyDate" } } } ] } } }, "Webhook": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "$ref": "#/components/schemas/WebhookBase" } ] }, "NewWebhook": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/WebhookAttributes" }, { "type": "object", "required": [ "url", "events" ] } ] } } }, "IdAsString": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the resource.", "example": "1" } } }, "WebhookUpdate": { "allOf": [ { "$ref": "#/components/schemas/IdAsString" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "attributes": { "$ref": "#/components/schemas/WebhookAttributes" } } } ] }, "webhookEventStatus": { "type": "string", "description": "`pending` until the event is delivered or given up on, then `success` (your endpoint returned a status below 400) or `failure` (your endpoint returned 404 or 410, the retries ran out, the webhook was inactive, or its URL no longer resolved to a public address).", "enum": [ "pending", "success", "failure" ], "example": "success" }, "WebhookEvent": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "event" ] }, "attributes": { "type": "object", "required": [ "created_at", "payload", "status", "version" ], "properties": { "payload": { "type": [ "string", "null" ], "description": "The body we send (or sent) to your endpoint, as a string.", "example": "{\"data\":{\"id\":\"1377451\",\"type\":\"event\",\"attributes\":{\"created_at\":\"2025-03-14T16:42:07.000Z\",\"name\":\"asset_created\"},\"relationships\":{\"object\":{\"data\":{\"type\":\"asset\",\"id\":\"5501\"}},\"team\":{\"data\":{\"type\":\"team\",\"id\":\"1\"}}}},\"included\":[]}" }, "status": { "$ref": "#/components/schemas/webhookEventStatus" }, "version": { "type": "integer", "description": "The API version used to serialize the payload.", "example": 20190326 }, "created_at": { "$ref": "#/components/schemas/ReadOnlyDate" } } }, "relationships": { "type": "object", "required": [ "attempts" ], "properties": { "attempts": { "type": "object", "description": "The delivery attempts, newest first. The linkage is only returned when you request `include=attempts`.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "attempt" ] }, "id": { "type": "string", "example": "2210987" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } } ] }, "WebhookAttempt": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "attempt" ] }, "attributes": { "type": "object", "required": [ "webhook_url", "response_status", "response_body", "response_headers", "created_at" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "The URL the attempt was sent to.", "example": "https://hooks.example.com/trueloyal" }, "response_status": { "type": [ "string", "null" ], "description": "The HTTP status your endpoint returned, as a string. `null` when no response was received.", "example": "200" }, "response_body": { "type": [ "string", "null" ], "description": "The body your endpoint returned. `null` when no response was received.", "example": "{\"received\":true}" }, "response_headers": { "type": [ "object", "null" ], "description": "The headers your endpoint returned. `null` when no response was received.", "additionalProperties": true, "example": { "content-type": "application/json" } }, "created_at": { "$ref": "#/components/schemas/ReadOnlyDate" } } } } } ] }, "SavedFilterType": { "type": "string", "description": "The resource type. Always `saved_filter`.", "enum": [ "saved_filter" ], "example": "saved_filter" }, "SavedFilterName": { "type": "string", "description": "The name of the saved filter. It must be unique within the board.", "minLength": 1, "example": "Summer favorites" }, "SavedFilterCriteria": { "type": "object", "description": "The post filter criteria, using the same names as the `filter` query parameter of \"Retrieve a list of posts\". Lists are arrays (a comma-separated string is also accepted in requests). At least one criterion is required. Criteria that aren't sent are removed.", "minProperties": 1, "properties": { "q": { "type": "string", "description": "A full-text search on the posts.", "example": "sneakers" }, "status": { "type": "array", "description": "The moderation statuses to include. Only these combinations are supported (in any order), and any other value is ignored: all visible posts (`public`, `recurring`, `private`, `image_moderation_failed`), public posts (`public`, `recurring`), private posts (`private`, `image_moderation_failed`, `recurring`), and hidden posts (`recurring`, `moderation_deleted`, `image_moderation_deleted`, `deleted`, `privacy_deleted`).", "items": { "type": "string", "enum": [ "public", "recurring", "private", "image_moderation_failed", "moderation_deleted", "image_moderation_deleted", "deleted", "privacy_deleted" ] }, "example": [ "public", "recurring" ] }, "published_at": { "type": "object", "description": "The publication time range. Times are stored with a precision of one second.", "properties": { "$gte": { "type": "string", "format": "date-time", "description": "At or after this time. Must not be after `$lte`.", "example": "2025-06-01T00:00:00.000Z" }, "$lte": { "type": "string", "format": "date-time", "description": "At or before this time.", "example": "2025-08-31T23:59:59.000Z" } } }, "type": { "type": "array", "description": "The sources of the posts.", "items": { "$ref": "#/components/schemas/SocialFeedSource" }, "example": [ "instagram_business", "tiktok" ] }, "social_feed_id": { "type": "array", "description": "The IDs of the social feeds the posts come from.", "items": { "type": "string" }, "example": [ "311", "312" ] }, "media_type": { "type": "array", "description": "The media types of the posts.", "items": { "type": "string", "enum": [ "text", "image", "video", "carousel" ] }, "example": [ "image", "video" ] }, "language": { "type": "array", "description": "The ISO 639-1 codes of the posts' languages.", "items": { "type": "string" }, "example": [ "en", "es" ] }, "sentiment": { "type": "array", "description": "The sentiments of the posts' text.", "items": { "type": "string", "enum": [ "neutral", "positive", "negative" ] }, "example": [ "positive" ] }, "image_object": { "type": "array", "description": "Objects detected in the posts' images.", "items": { "type": "string" }, "example": [ "shoe", "beach" ] }, "tag": { "type": "array", "description": "The tags of the posts.", "items": { "type": "string" }, "example": [ "featured" ] }, "product_id": { "type": "array", "description": "The IDs of the products tagged in the posts.", "items": { "type": "string" }, "example": [ "501" ] }, "right_request_status": { "type": "array", "description": "The statuses of the posts' most recent right request.", "items": { "type": "string", "enum": [ "approved", "declined", "deleted", "error", "expired", "missing", "pending", "requested", "soft_approved", "token_error" ] }, "example": [ "approved" ] }, "right_request_status_expires_at": { "type": "string", "pattern": "^[+-]?\\d+$", "description": "When the status of the most recent right request expires, as a Unix timestamp in seconds, or relative to now in seconds when prefixed with `+` or `-`.", "example": "+2592000" }, "rating": { "type": "object", "description": "The review rating range (0 to 100).", "properties": { "$gte": { "type": "integer", "description": "At least this rating.", "example": 60 }, "$lte": { "type": "integer", "description": "At most this rating.", "example": 100 }, "$range": { "type": "string", "description": "A comma-separated list of inclusive `from-to` ranges.", "example": "80-100" } } }, "highlighted": { "type": "boolean", "description": "Whether the posts are highlighted.", "example": true }, "pinned": { "type": "boolean", "description": "Whether the posts are pinned.", "example": false }, "incentivized": { "type": "boolean", "description": "Whether the reviews are incentivized.", "example": false } } }, "SavedFilter": { "type": "object", "description": "A saved set of post filter criteria for a board.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the saved filter.", "example": "15", "readOnly": true }, "type": { "$ref": "#/components/schemas/SavedFilterType" }, "attributes": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/SavedFilterName" }, "filter": { "$ref": "#/components/schemas/SavedFilterCriteria" }, "created_at": { "type": "string", "format": "date-time", "description": "When the saved filter was created.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "When the saved filter was last updated.", "example": "2025-03-14T16:42:07.000Z", "readOnly": true } } }, "relationships": { "type": "object", "readOnly": true, "description": "The saved filter's relationships. Unless a relationship is requested with the `include` query parameter, only `meta.included: false` is returned.", "properties": { "tint": { "type": "object", "description": "The board the saved filter belongs to.", "properties": { "data": { "description": "Only returned when included.", "allOf": [ { "$ref": "#/components/schemas/TintIdentifier" } ] }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "cta_associations": { "type": "object", "description": "The calls to action associated with the posts matching the saved filter.", "properties": { "data": { "type": "array", "description": "Only returned when included.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cta_association" ], "example": "cta_association" }, "id": { "type": "string", "example": "64" } } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "NewSavedFilter": { "type": "object", "description": "The saved filter to create.", "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SavedFilterType" }, "attributes": { "type": "object", "required": [ "name", "filter" ], "properties": { "name": { "$ref": "#/components/schemas/SavedFilterName" }, "filter": { "$ref": "#/components/schemas/SavedFilterCriteria" } } } } }, "SavedFilterUpdate": { "type": "object", "description": "The saved filter changes. The `id` is optional; the saved filter is identified by the URL. The `filter` is always replaced: send the complete criteria, as the update fails if `filter` is missing or empty.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the saved filter.", "example": "15" }, "type": { "$ref": "#/components/schemas/SavedFilterType" }, "attributes": { "type": "object", "required": [ "filter" ], "properties": { "name": { "$ref": "#/components/schemas/SavedFilterName" }, "filter": { "$ref": "#/components/schemas/SavedFilterCriteria" } } } } }, "Cta": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the CTA.", "readOnly": true, "example": "731" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "cta" ], "example": "cta" }, "attributes": { "type": "object", "required": [ "name", "text", "url" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Internal name used to identify the CTA in the app. Not displayed to visitors.", "example": "Spring sale booking" }, "text": { "type": [ "string", "null" ], "description": "The label displayed on the CTA button.", "example": "Book now" }, "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL visitors are sent to.", "example": "https://example.com/spring-sale?utm_source=board" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "tint": { "type": "object", "description": "The board the CTA belongs to. Only returned when the token has the `tints:read` scope. `data` is only returned when `tint` is included; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tint" ], "example": "tint" }, "id": { "type": "string", "example": "96" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "CtaWritableAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal name used to identify the CTA in the app. Not displayed to visitors.", "minLength": 1, "example": "Spring sale booking" }, "text": { "type": "string", "description": "The label displayed on the CTA button.", "minLength": 1, "example": "Book now" }, "url": { "type": "string", "format": "uri", "description": "The URL visitors are sent to. Must start with `http://` or `https://`.", "pattern": "^https?://", "example": "https://example.com/spring-sale?utm_source=board" } } }, "NewCta": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "cta" ], "example": "cta" }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/CtaWritableAttributes" }, { "type": "object", "required": [ "name", "text", "url" ] } ] } } }, "CtaUpdate": { "type": "object", "description": "Only the attributes that are sent are changed. Sent attributes can't be blank.", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the CTA.", "example": "731" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "cta" ], "example": "cta" }, "attributes": { "$ref": "#/components/schemas/CtaWritableAttributes" } } }, "NewCtaAssociation": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "description": "The resource type.", "enum": [ "cta_association" ], "example": "cta_association" }, "attributes": { "type": "object", "description": "Specify `cta_id` and either `post_id` or `saved_filter_id`. A CTA can only be applied once to the same post or saved filter.", "required": [ "cta_id" ], "properties": { "cta_id": { "type": "integer", "description": "The ID of the CTA to apply.", "example": 731 }, "post_id": { "type": "integer", "description": "The ID of the post to apply the CTA to. Don't combine with `saved_filter_id`.", "example": 902314 }, "saved_filter_id": { "type": "integer", "description": "The ID of the saved filter to apply the CTA to, so that every post matching the filter shows it. Don't combine with `post_id`.", "example": 3317 } } } } }, "CtaAssociation": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the CTA association.", "readOnly": true, "example": "5120" }, "type": { "type": "string", "description": "The resource type.", "enum": [ "cta_association" ], "example": "cta_association" }, "attributes": { "type": "object", "readOnly": true, "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The type of resource the CTA is applied to.", "enum": [ "post", "saved_filter" ], "example": "post" } } }, "relationships": { "readOnly": true, "type": "object", "description": "`data` is only returned for relationships that are included; otherwise `meta.included` is `false`.", "properties": { "cta": { "type": "object", "description": "The applied CTA.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cta" ], "example": "cta" }, "id": { "type": "string", "example": "731" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "post": { "type": "object", "description": "The post the CTA is applied to.", "properties": { "data": { "description": "`null` unless the CTA is applied to a post.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "post" ], "example": "post" }, "id": { "type": "string", "example": "902314" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } }, "saved_filter": { "type": "object", "description": "The saved filter the CTA is applied to.", "properties": { "data": { "description": "`null` unless the CTA is applied to a saved filter.", "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "saved_filter" ], "example": "saved_filter" }, "id": { "type": "string", "example": "3317" } }, "example": null }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "RoleAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the role.", "minLength": 1, "example": "Content Moderator" }, "description": { "type": [ "string", "null" ], "description": "A description of what the role is for. `null` when not set.", "example": "Moderates posts and manages rights requests for the brand boards." }, "permissions": { "type": "array", "description": "The permissions granted to team members who are assigned this role. In requests, a comma-separated string is also accepted. In responses, a role with the `all` permission lists every permission except those that grant access to future resources (`new_*` and `accounts_new`), unless they were granted explicitly.", "uniqueItems": true, "items": { "$ref": "#/components/schemas/RolePermission" }, "example": [ "moderate_tint", "modify_tint", "assets_read", "replies_r", "replies_cu" ] } } }, "RoleRelationships": { "type": "object", "readOnly": true, "description": "Resources related to the role. Every relationship always contains the identifiers of all its resources in `data`. When a relationship is requested with `include`, `data` only lists the resources you have access to and pagination links for the first page are added.", "properties": { "users": { "type": "object", "description": "The team members who are assigned the role.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "description": "The ID of the user.", "example": "42" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of team members who are assigned the role.", "example": 3 } } } } }, "tints": { "type": "object", "description": "The boards the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "tint" ] }, "id": { "type": "string", "example": "12" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the boards the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/tints" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/tints" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/tints?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of boards the role grants access to.", "example": 2 } } } } }, "accounts": { "type": "object", "description": "The social accounts the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "example": "3" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the social accounts the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/accounts" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/accounts" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/accounts?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of social accounts the role grants access to.", "example": 1 } } } } }, "collections": { "type": "object", "description": "The collections the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "collection" ] }, "id": { "type": "string", "example": "8" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the collections the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/collections" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/collections" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/collections?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of collections the role grants access to.", "example": 1 } } } } }, "domains": { "type": "object", "description": "The custom domains the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "domain" ] }, "id": { "type": "string", "example": "2" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the custom domains the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/domains" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/domains" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/domains?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of custom domains the role grants access to.", "example": 1 } } } } }, "fonts": { "type": "object", "description": "The custom fonts the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "font" ] }, "id": { "type": "string", "example": "5" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the custom fonts the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/fonts" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/fonts" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/fonts?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of custom fonts the role grants access to.", "example": 1 } } } } }, "experiences": { "type": "object", "description": "The experiences the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "experience" ] }, "id": { "type": "string", "example": "21" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the experiences the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/experiences" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/experiences" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/experiences?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of experiences the role grants access to.", "example": 2 } } } } }, "product_accounts": { "type": "object", "description": "The product accounts the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product_account" ] }, "id": { "type": "string", "example": "4" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the product accounts the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_accounts" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_accounts" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_accounts?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of product accounts the role grants access to.", "example": 1 } } } } }, "product_feeds": { "type": "object", "description": "The product feeds the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "product_feed" ] }, "id": { "type": "string", "example": "6" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the product feeds the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_feeds" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_feeds" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/product_feeds?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of product feeds the role grants access to.", "example": 1 } } } } }, "personalizations": { "type": "object", "description": "The personalizations the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "personalization" ] }, "id": { "type": "string", "example": "9" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the personalizations the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/personalizations" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/personalizations" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/personalizations?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of personalizations the role grants access to.", "example": 1 } } } } }, "oauth_applications": { "type": "object", "description": "The OAuth applications the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "oauth_application" ] }, "id": { "type": "string", "example": "7" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the OAuth applications the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/oauth_applications" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/oauth_applications" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/oauth_applications?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of OAuth applications the role grants access to.", "example": 1 } } } } }, "webhooks": { "type": "object", "description": "The webhooks the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "id": { "type": "string", "example": "11" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the webhooks the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/webhooks" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/webhooks" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/webhooks?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of webhooks the role grants access to.", "example": 1 } } } } }, "forms": { "type": "object", "description": "The forms the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "form" ] }, "id": { "type": "string", "example": "14" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the forms the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/forms" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/forms" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/forms?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of forms the role grants access to.", "example": 1 } } } } }, "mixes": { "type": "object", "description": "The mixes the role grants access to.", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "mix" ] }, "id": { "type": "string", "example": "10" } } } }, "links": { "type": "object", "properties": { "related": { "type": "string", "format": "uri", "description": "The URL listing the mixes the role grants access to.", "example": "https://api.tintup.com/v2/teams/1/roles/3/mixes" }, "first": { "type": "string", "format": "uri", "description": "The URL of the first page. Only present when the relationship is included and not empty.", "example": "https://api.tintup.com/v2/teams/1/roles/3/mixes" }, "next": { "type": "string", "format": "uri", "description": "The URL of the next page. Only present when the relationship is included and has more pages.", "example": "https://api.tintup.com/v2/teams/1/roles/3/mixes?page%5Bnumber%5D=2" } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of mixes the role grants access to.", "example": 1 } } } } } } }, "Role": { "allOf": [ { "$ref": "#/components/schemas/IdAsStringReadOnly" }, { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "example": "3" }, "type": { "type": "string", "enum": [ "role" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/RoleAttributes" }, { "type": "object", "required": [ "name", "description", "permissions", "created_at", "updated_at" ], "properties": { "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the role was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "When the role was last updated.", "example": "2025-03-20T09:15:31.000Z" } } } ] }, "relationships": { "$ref": "#/components/schemas/RoleRelationships" } } } ] }, "RoleResourceIds": { "description": "The IDs of the resources the role grants access to. You can only grant or revoke access to resources you have access to yourself; any other ID makes the request fail with a `422 Unprocessable Entity` error. Accepted forms: an array of IDs, or a comma-separated string of IDs, replaces the resources you have access to (access to resources you can't see is kept); `all` grants access to every resource of that kind you have access to; an object with `+` and/or `-` arrays adds or removes access without touching the other resources.", "oneOf": [ { "title": "List of IDs", "type": "array", "description": "The IDs of the resources to grant access to.", "items": { "type": "integer" }, "uniqueItems": true }, { "title": "Comma-separated or all", "type": "string", "description": "A comma-separated list of IDs, or `all`.", "pattern": "^(all|\\d+(,\\d+)*)?$" }, { "title": "Add or remove", "type": "object", "description": "Incremental changes to the resources the role grants access to.", "properties": { "+": { "type": "array", "description": "The IDs of the resources to add.", "items": { "type": "integer" } }, "-": { "type": "array", "description": "The IDs of the resources to remove.", "items": { "type": "integer" } } }, "additionalProperties": false } ] }, "RoleResourceAccessAttributes": { "type": "object", "description": "Write-only attributes that set which resources the role grants access to.", "properties": { "tint_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The boards the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 12, 15 ], "writeOnly": true }, "account_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The social accounts the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 3 ], "writeOnly": true }, "collection_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The collections the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 8 ], "writeOnly": true }, "domain_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The custom domains the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 2 ], "writeOnly": true }, "font_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The custom fonts the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 5 ], "writeOnly": true }, "experience_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The experiences the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 21, 22 ], "writeOnly": true }, "product_account_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The product accounts the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 4 ], "writeOnly": true }, "product_feed_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The product feeds the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 6 ], "writeOnly": true }, "personalization_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The personalizations the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 9 ], "writeOnly": true }, "oauth_application_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The OAuth applications the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 7 ], "writeOnly": true }, "webhook_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The webhooks the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 11 ], "writeOnly": true }, "form_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The forms the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 14 ], "writeOnly": true }, "mix_ids": { "allOf": [ { "$ref": "#/components/schemas/RoleResourceIds" } ], "description": "The mixes the role grants access to. Accepts IDs, `all`, or `+`/`-` changes.", "example": [ 10 ], "writeOnly": true } } }, "NewRole": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "role" ] }, "attributes": { "allOf": [ { "$ref": "#/components/schemas/RoleAttributes" }, { "$ref": "#/components/schemas/RoleResourceAccessAttributes" }, { "type": "object", "required": [ "name" ] } ] } } }, "RoleUpdate": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the role. Optional; the role is identified by the URL.", "example": "3" }, "type": { "type": "string", "enum": [ "role" ] }, "attributes": { "description": "The attributes to change. Attributes that are omitted are left unchanged.", "allOf": [ { "$ref": "#/components/schemas/RoleAttributes" }, { "$ref": "#/components/schemas/RoleResourceAccessAttributes" } ] } } }, "privacyRequestTypes": { "type": "string", "description": "The type of privacy request. Currently, only `erasure` is supported.", "enum": [ "erasure" ], "example": "erasure" }, "privacyRequestStatuses": { "type": "string", "description": "`pending` while the request is being processed, then `success` or `failure`.", "readOnly": true, "enum": [ "pending", "success", "failure" ], "example": "pending" }, "privacyRequestIdentifierTypes": { "type": "string", "description": "The type of identifier provided. Currently, only a loyalty member `id` is supported.", "enum": [ "id" ], "example": "id" }, "PrivacyRequest": { "type": "object", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the privacy request.", "readOnly": true, "example": "37" }, "type": { "type": "string", "enum": [ "privacy_request" ], "example": "privacy_request" }, "attributes": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/privacyRequestTypes" }, "status": { "$ref": "#/components/schemas/privacyRequestStatuses" }, "identifier_type": { "$ref": "#/components/schemas/privacyRequestIdentifierTypes" }, "identifier_hash": { "type": "string", "description": "A salted SHA-256 hash (hex-encoded) of the identifier that was provided, after trimming and lowercasing it. It records which identifier the request was for without storing the identifier itself.", "readOnly": true, "example": "3c1bd5494bbc5e832580d202fa3adbee31b038baebe334ab2436a3933ce468d0" }, "created_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the request was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "allOf": [ { "$ref": "#/components/schemas/ReadOnlyDate" } ], "description": "The date and time the request was last updated. Once `status` is `success` or `failure`, this is when the request was completed.", "example": "2025-03-14T16:43:12.000Z" } } }, "relationships": { "type": "object", "readOnly": true, "properties": { "team": { "type": "object", "description": "The team the request was made for. `data` is only present when `team` is listed in the `include` query parameter; otherwise `meta.included` is `false`.", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "team" ], "example": "team" }, "id": { "type": "string", "description": "The ID of the team.", "example": "1" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "NewPrivacyRequest": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "privacy_request" ], "example": "privacy_request" }, "attributes": { "type": "object", "required": [ "type", "identifier_type", "identifier" ], "properties": { "type": { "$ref": "#/components/schemas/privacyRequestTypes" }, "identifier_type": { "$ref": "#/components/schemas/privacyRequestIdentifierTypes" }, "identifier": { "type": "string", "description": "The value for the chosen identifier type. Currently, this is always the ID of a loyalty member. It isn't stored; only its hash is (see `identifier_hash`).", "minLength": 1, "writeOnly": true, "example": "65f3a1c2e4b0a91d2c7e8f10" } } } } }, "WebhookEventId": { "type": "string", "description": "The event ID. It stays the same on every retry of this event, so use it to detect duplicate deliveries. It is also the ID to use with [Retrieve a webhook event](#operation-v2-teams-team-id-webhooks-webhook-id-events-webhook-event-id-get).", "example": "1377451" }, "WebhookEventType": { "type": "string", "description": "Always `event`.", "enum": [ "event" ] }, "WebhookEventCreatedAt": { "type": "string", "format": "date-time", "description": "When the event happened (the event was recorded), not when this delivery was sent. Retries keep the original value.", "example": "2025-03-14T16:42:07.000Z" }, "WebhookEventTeamRelationship": { "type": "object", "description": "The team the webhook belongs to.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "example": "1" } } } } }, "Variant": { "type": "object", "description": "Deprecated. A variant of an asset. Each asset has a single variant, the asset itself, with the same `id`; it's sideloaded when `variants` is included (always in webhook payloads).", "deprecated": true, "readOnly": true, "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the variant, the same as the asset's ID.", "example": "190245" }, "type": { "type": "string", "enum": [ "variant" ], "example": "variant" }, "attributes": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of the stored file.", "example": "https://media.example.com/assets/190245/beach-picnic.jpg" }, "expanded_url": { "type": [ "string", "null" ], "format": "uri", "description": "Same value as `source_url`.", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "mime_type": { "type": "string", "description": "The file's media type.", "example": "image/jpeg" }, "size": { "type": "integer", "description": "The file size in bytes.", "example": 2483910 }, "dimensions": { "type": "array", "description": "The width and height of the image or video, in pixels.", "minItems": 2, "maxItems": 2, "items": { "type": [ "integer", "null" ] }, "example": [ 1080, 1350 ] }, "duration": { "type": [ "number", "null" ], "description": "The video duration in seconds. `null` for images.", "example": null }, "thumbnail_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of a thumbnail of the image or video. `null` when no thumbnail is available.", "example": "https://media.example.com/assets/190245/thumbnail.jpg" }, "source_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL the asset was imported from. `null` for direct uploads. Only returned to authenticated requests and in webhook payloads.", "example": "https://cdn.example.com/uploads/beach-picnic.jpg" }, "title": { "type": [ "string", "null" ], "description": "The asset's title. Only returned to authenticated requests and in webhook payloads.", "example": "Beach picnic" }, "description": { "type": [ "string", "null" ], "description": "A longer description of the asset. Only returned to authenticated requests and in webhook payloads.", "example": "Customer photo submitted during the summer campaign." }, "transformations": { "type": "null", "description": "Always `null`. Only returned to authenticated requests and in webhook payloads.", "example": null }, "enhance": { "type": "null", "description": "Always `null`. Only returned to authenticated requests and in webhook payloads.", "example": null }, "insights": { "type": [ "object", "null" ], "description": "Attention insights for images, with `metrics` (scores keyed by metric name) and `heatmap` (the attention heat map). `null` when not analyzed. Only returned to authenticated requests and in webhook payloads.", "additionalProperties": true, "example": null } } } } }, "AssetExportRequest": { "type": "object", "description": "An export of assets, generated asynchronously as a ZIP file.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "description": "The ID of the export request.", "example": "OxZZQtuh5sXIKA", "readOnly": true }, "type": { "type": "string", "enum": [ "asset_export_request" ] }, "attributes": { "type": "object", "required": [ "status", "url" ], "properties": { "status": { "$ref": "#/components/schemas/exportStatus" }, "url": { "$ref": "#/components/schemas/ExportUrl" } } }, "relationships": { "type": "object", "readOnly": true, "required": [ "user" ], "properties": { "user": { "type": "object", "description": "The user who requested the export. The linkage is only returned when the user is included.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "example": "42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } }, "LoyaltyMember": { "type": "object", "description": "A member of the team's loyalty program.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The ID of the loyalty member.", "example": "65f3a1c2e4b0a91d2c7e8f10", "readOnly": true }, "type": { "type": "string", "enum": [ "person" ], "example": "person", "readOnly": true }, "attributes": { "type": "object", "readOnly": true, "properties": { "first_name": { "type": [ "string", "null" ], "description": "The member's first name.", "example": "Jane" }, "last_name": { "type": [ "string", "null" ], "description": "The member's last name.", "example": "Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The member's email address.", "example": "jane.doe@example.com" }, "external_id": { "type": [ "string", "null" ], "description": "The member's ID in your own system, if one was provided when they enrolled.", "example": "CUS-004211" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the member was created.", "example": "2025-03-14T16:42:07.000Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the member was last updated.", "example": "2025-03-14T16:42:07.000Z" }, "enrolled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the member enrolled in the loyalty program.", "example": "2025-03-14T16:42:07.000Z" }, "last_interaction_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the member last interacted with the loyalty program.", "example": "2025-03-14T16:42:07.000Z" } } } } }, "Attachment": { "type": "object", "description": "A file attached to a form submission, sideloaded when `files` is included (always in webhook payloads).", "readOnly": true, "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "description": "The signed ID of the file.", "example": "eyJfcmFpbHMiOnsiZGF0YSI6OTg3NjU0LCJwdXIiOiJibG9iX2lkIn19--3b5f0c1d2e" }, "type": { "type": "string", "enum": [ "upload" ], "example": "upload" }, "attributes": { "type": "object", "properties": { "content_type": { "type": "string", "description": "The file's media type.", "example": "image/jpeg" }, "url": { "type": "string", "format": "uri", "description": "The URL of the file. The URL is signed and expires after a short time.", "example": "https://cdn.example.com/uploads/entry-photo.jpg" }, "thumbnail_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL of a thumbnail of the file, or `null` for files that can't be previewed (such as PDFs).", "example": "https://cdn.example.com/uploads/entry-photo-thumbnail.jpg" } } }, "relationships": { "type": "object", "properties": { "asset": { "type": "object", "description": "The asset created from the file, if any. Only returned in webhook payloads or when the access token has the `assets:read` scope.", "properties": { "data": { "type": [ "object", "null" ], "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "asset" ], "example": "asset" }, "id": { "type": "string", "example": "190245" } } } } } } } } }, "TransactionExportRequest": { "type": "object", "description": "An export of loyalty transactions, generated asynchronously as a ZIP file.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "description": "The ID of the export request.", "example": "OxZZQtuh5sXIKA", "readOnly": true }, "type": { "type": "string", "enum": [ "transaction_export_request" ] }, "attributes": { "type": "object", "required": [ "status", "url" ], "properties": { "status": { "$ref": "#/components/schemas/exportStatus" }, "url": { "$ref": "#/components/schemas/ExportUrl" } } }, "relationships": { "type": "object", "readOnly": true, "required": [ "user" ], "properties": { "user": { "type": "object", "description": "The user who requested the export. The linkage is only returned when the user is included.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user" ] }, "id": { "type": "string", "example": "42" } } }, "meta": { "$ref": "#/components/schemas/RelationshipMetaExcluded" } } } } } } } }, "responses": { "204": { "description": "No Content. The request succeeded and there is no response body." }, "401": { "description": "Unauthorized. The access token is missing, invalid, expired or revoked.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "401", "title": "Unauthorized", "status": "401" } ] } } } }, "403": { "description": "Forbidden. The access token doesn't have the required scope, the user isn't allowed to perform this action, or the `id_token` is missing or invalid.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4030000", "title": "Forbidden", "status": "403" } ] } } } }, "404": { "description": "Not Found.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "404", "title": "Not found", "status": "404" } ] } } } }, "422": { "description": "Unprocessable Entity. The request is missing required parameters or the resource is invalid.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "title": "Invalid name", "detail": "Name can't be blank", "source": { "pointer": "/data/attributes/name" } } ] } } } }, "429": { "description": "Too Many Requests. Retry after the time given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "The date and time after which you may retry the request.", "schema": { "type": "string" }, "example": "Wed, 01 Jan 2020 00:00:00 GMT" } }, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "429", "title": "Too many requests", "status": "429" } ] } } } }, "accountsWhenAuthorized": { "description": "A list of accounts.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "accountWhenAuthorized": { "description": "The account.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "accountAuthorizationUrl": { "description": "The URL of the third-party authorization page. Open it (usually in a popup window) so the user can grant access.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Redirect" } } } } } }, "subaccountsWhenAuthorized": { "description": "A list of subaccounts.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subaccount" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "productFeedRefreshRequestWhenAuthorized": { "description": "The product feed refresh request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductFeedRefreshRequest" } } } } } }, "productsWhenAuthorized": { "description": "A list of products.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "properties": { "aggregations": { "type": "object", "description": "Counts of products per value, across all the products of the product feeds you have access to (the other filters don't apply). Useful to build filter menus.", "properties": { "brand": { "type": "object", "description": "The number of products per brand.", "additionalProperties": { "type": "integer" }, "example": { "Acme": 124, "Globex": 37 } }, "categories": { "type": "object", "description": "The number of products per category.", "additionalProperties": { "type": "integer" }, "example": { "Footwear": 98, "Running": 42 } }, "family": { "type": "object", "description": "The number of products per family.", "additionalProperties": { "type": "integer" }, "example": { "Acme Runner 2": 6, "Acme Trail": 4 } } } } } } } } }, "text/csv": { "schema": { "type": "string", "description": "Returned when the request asks for CSV (`Accept: text/csv` or a `.csv` extension). Contains every product of the product feeds you have access to (filters, sorting and pagination are ignored) with the columns `sku`, `name`, `description`, `image_url`, `url`, `currency`, `categories`, `availability`, `price`, `sale_price`, `status`, `sale_price_starts_at`, `sale_price_ends_at`, `brand` and `family`. Sent as an attachment named `products.csv`.", "example": "sku,name,description,image_url,url,currency,categories,availability,price,sale_price,status,sale_price_starts_at,sale_price_ends_at,brand,family\nACME-RUN2-BLK-42,Acme Runner 2 sneakers,Lightweight running sneakers.,https://cdn.example.com/products/acme-runner-2-black.jpg,https://shop.example.com/products/acme-runner-2,USD,\"Footwear,Running\",in_stock,89.00,69.00,active,2025-03-14 00:00:00 UTC,2025-03-31 23:59:59 UTC,Acme,Acme Runner 2" } } } }, "productWhenAuthorized": { "description": "The product.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Product" } } } } } }, "scheduledContentsWhenAuthorized": { "description": "A list of scheduled contents.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledContent" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "scheduledContentWhenAuthorized": { "description": "The scheduled content.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ScheduledContent" } } } } } }, "scheduledContentsAggregationsWhenAuthorized": { "description": "The number of scheduled contents of the team per tag, account and subaccount.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledContentAggregation" } } } } } } }, "campaignsWhenAuthorized": { "description": "A list of campaigns.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "campaignWhenAuthorized": { "description": "The campaign.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } } } } }, "productFeedsWhenAuthorized": { "description": "A list of product feeds.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFeed" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "productFeedWhenAuthorized": { "description": "The product feed.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductFeed" } } } } } }, "productAccountsWhenAuthorized": { "description": "A list of product accounts.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductAccount" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "productAccountWhenAuthorized": { "description": "The product account.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductAccount" } } } } } }, "productAccountAuthorizationRedirect": { "description": "The URL of the third-party authorization page.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductAccountAuthorizationRedirect" } } } } } }, "productTagWhenAuthorized": { "description": "The product tag.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductTag" } } } } } }, "marketingIntegrationsWhenAuthorized": { "description": "A list of marketing integrations.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketingIntegration" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "marketingIntegrationWhenAuthorized": { "description": "The marketing integration.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/MarketingIntegration" } } } } } }, "marketingIntegrationAuthorizationUrl": { "description": "The URL of the third-party authorization page. Open it (usually in a popup window) so the user can grant access.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Redirect" } } } } } }, "foldersWhenAuthorized": { "description": "A list of folders in the marketing integration. This list is not paginated.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" } } } } } } }, "marketingIntegrationRequestsWhenAuthorized": { "description": "The marketing integration requests that were created, one per published asset. The uploads happen asynchronously; each request starts as `pending`.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketingIntegrationRequest" } } } } } } }, "mixWhenUnauthorized": { "description": "The mix. Without an access token, the public representation is returned; with one, the full representation is returned.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PublicMix" } } } } } }, "mixesWhenAuthorized": { "description": "A list of mixes.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mix" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "mixWhenAuthorized": { "description": "The mix.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Mix" } } } } } }, "mixPlanLimitExceeded": { "description": "Payment Required. The team already has as many mixes as its plan allows.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4020001", "title": "Payment Required", "detail": "You have exceeded your plan's limit of 5", "status": "402" } ] } } } }, "personalizationsWithAggregationsWhenAuthorized": { "description": "A list of personalizations.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalizationBase" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "properties": { "aggregations": { "type": "object", "properties": { "tags": { "type": "object", "description": "The number of personalizations (that the user can access, regardless of filters) using each tag, keyed by tag.", "additionalProperties": { "type": "integer" }, "example": { "spring": 3, "website": 5 } } } } } } } } } } }, "personalizationWhenAuthorized": { "description": "The personalization.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PersonalizationBase" } } } } } }, "personalizationLimitReached": { "description": "Payment Required. The team reached its plan's limit of personalizations.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4020001", "title": "Payment Required", "status": "402", "detail": "You have exceeded your plan's limit of 10" } ] } } } }, "personalizationsWhenAuthorized": { "description": "A list of personalizations.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalizationBase" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "replyWhenAuthorized": { "description": "The reply.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Reply" } } } } } }, "rightRequestsWhenAuthorized": { "description": "A list of right requests.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RightRequest" } }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "rightRequestWhenAuthorized": { "description": "The right request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RightRequest" }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } } } } } } }, "rightRequestsMetricsWhenAuthorized": { "description": "A list of right request metrics, one row per combination of the grouping dimensions, or a single row when the `group` query parameter isn't used. The list is not paginated.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RightRequestsMetric" } } } }, "example": { "data": [ { "id": "f42c2ba98b72afee69976d52875fe313", "type": "right_requests_metric", "attributes": { "count": 41, "dimensions": { "source": "instagram_business", "time": "2025-03-14 00:00:00.000000000" } } }, { "id": "0b9e4c7d2a8f41e3b5c6d7e8f9a0b1c2", "type": "right_requests_metric", "attributes": { "count": 17, "dimensions": { "source": "tiktok_business", "time": "2025-03-14 00:00:00.000000000" } } } ] } } } }, "rightRequestTermsWhenAuthorized": { "description": "A list of published right request terms.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RightRequestTerm" } }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "rightRequestTermWhenAuthorized": { "description": "The right request term.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RightRequestTerm" }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } } } } } } }, "rightRequestTemplatesWhenAuthorized": { "description": "A list of right request templates.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RightRequestTemplate" } }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "rightRequestTemplateWhenAuthorized": { "description": "The right request template.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RightRequestTemplate" }, "included": { "type": "array", "description": "The related resources requested with the `include` query parameter.", "items": { "type": "object" } } } } } } }, "teamsWhenAuthorized": { "description": "A list of the teams the authenticated user is a member of.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "teamWhenAuthorized": { "description": "The team.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Team" }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } } } } } } }, "domainsWhenAuthorized": { "description": "The domains the user has access to. The list isn't paginated.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "included": { "type": "array", "description": "The default experiences, when requested with `include=default_experience`.", "items": { "$ref": "#/components/schemas/ExperienceBase" } } } } } } }, "domainWhenAuthorized": { "description": "The domain.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Domain" }, "included": { "type": "array", "description": "The default experience, when requested with `include=default_experience`.", "items": { "$ref": "#/components/schemas/ExperienceBase" } } } } } } }, "domainForbidden": { "description": "Forbidden. The access token doesn't have the required scope or the user doesn't have access to the domain.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "403", "title": "Forbidden", "status": "403" } ] } } } }, "emailTemplatesWhenAuthorized": { "description": "A page of the team's email templates.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "included": { "type": "array", "description": "The team, when requested with `include=team`.", "items": { "$ref": "#/components/schemas/Team" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "emailTemplateWhenAuthorized": { "description": "The email template.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmailTemplate" }, "included": { "type": "array", "description": "The team, when requested with `include=team`.", "items": { "$ref": "#/components/schemas/Team" } } } } } } }, "fontsWhenAuthorized": { "description": "A page of the fonts the user has access to.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Font" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "fontWhenAuthorized": { "description": "The font.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Font" } } } } } }, "fontUpload": { "description": "The upload. Send the file to its `url`, then create the font with its `id` as `upload_id`.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Upload" } } } } } }, "fontsStylesheet": { "description": "A stylesheet with one `@font-face` rule per requested font that was found. Requested IDs that don't match one of the team's fonts are skipped.", "content": { "text/css": { "schema": { "type": "string" }, "example": "@font-face { font-family: \"Quicksand\"; font-style: normal; font-weight: 400; src: local(\"Quicksand\"), url(\"https://storage.example.com/fonts/quicksand-regular.woff2?X-Amz-Expires=604800&X-Amz-Signature=3f9a1c0b7d\"); font-display: block; }\n@font-face { font-family: \"Merriweather\"; font-style: normal; font-weight: 400; src: local(\"Merriweather\"), url(\"https://storage.example.com/fonts/merriweather-regular.ttf?X-Amz-Expires=604800&X-Amz-Signature=a41e9d27c5\"); font-display: block; }\n" } } }, "tintsWhenAuthorized": { "description": "A list of boards.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tint" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "tintWhenAuthorized": { "description": "The board.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Tint" } } } } } }, "tintPlanLimitExceeded": { "description": "Payment Required. The team already has as many active boards as its plan allows.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "402", "title": "Plan limit exceeded", "status": "402" } ] } } } }, "tintsUpdated": { "description": "The updated boards.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tint" } } } } } } }, "tintEngagementMetricsWhenAuthorized": { "description": "A list of board engagement metrics.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostsEngagementMetric" } } } } } } }, "tintWhenUnauthorized": { "description": "The board. Without an access token, the public representation is returned; with one, the full representation (see \"Retrieve a board\") is returned.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PublicTint" } } } } } }, "meWhenAuthorized": { "description": "The authenticated user.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } } } } } } }, "teamUsersWhenAuthorized": { "description": "A list of team users.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUser" } }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total number of users in the team, regardless of filters.", "example": 12 } } } } } } } }, "teamUsersCreated": { "description": "The invited user, or an array of the invited users when the request contained an array of resource objects.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/TeamUser" }, { "title": "List of team users", "type": "array", "items": { "$ref": "#/components/schemas/TeamUser" } } ] } } } } } }, "teamUsersLimitExceeded": { "description": "Payment Required. Inviting the users would exceed the number of users allowed by the team's plan.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4020001", "title": "Payment Required", "status": "402", "detail": "You have exceeded your plan's limit of 10" } ] } } } }, "teamUsersUpdated": { "description": "The updated team users.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUser" } } } } } } }, "teamUserWhenAuthorized": { "description": "The team user.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamUser" }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } } } } } } }, "teamsUserExportRequestWhenAuthorized": { "description": "The team user export request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TeamsUserExportRequest" } } } } } }, "authenticationFactorsWhenAuthorized": { "description": "All the authentication factors of the current user. This list isn't paginated.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuthenticationFactor" } } } } } } }, "authenticationFactorWhenAuthorized": { "description": "The authentication factor.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthenticationFactor" } } } } } }, "authenticationFactorChallengeWhenAuthorized": { "description": "The authentication factor challenge. A new code was sent.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AuthenticationFactorChallenge" } } } } } }, "assetsWhenAuthorized": { "description": "A list of assets.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/AssetsListMeta" } } } } } }, "assetBulkCreateRequestWhenAuthorized": { "description": "Accepted. The assets are being created.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AssetBulkCreateRequest" } } } } } }, "assetsUpdatedWhenAuthorized": { "description": "The updated assets.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } } }, "assetWhenAuthorized": { "description": "The asset.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Asset" } } } } } }, "assetsAggregationsWhenAuthorized": { "description": "The number of the team's assets per source, detected object, emotion, media type and tag.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssetAggregation" } } } } } } }, "socialFeedsWhenAuthorized": { "description": "A list of social feeds.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialFeed" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "socialFeedWhenAuthorized": { "description": "The social feed.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SocialFeed" } } } } } }, "socialFeedPlanLimitExceeded": { "description": "Payment Required. The team already has as many active social feeds as its plan allows.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4020001", "title": "Payment Required", "detail": "You have exceeded your plan's limit of 10", "status": "402" } ] } } } }, "socialFeedsUpdated": { "description": "The updated social feeds.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialFeed" } } } } } } }, "socialFeedMetricsWhenAuthorized": { "description": "A list of social feed metrics.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SocialFeedMetric" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "experiencesWithTotalWhenAuthorized": { "description": "A list of experiences.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceBase" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "properties": { "total": { "type": "integer", "description": "The total number of experiences of the team, regardless of filters.", "example": 18 } } } } } } } }, "experienceWhenAuthorized": { "description": "The experience.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ExperienceBase" } } } } } }, "experiencesWhenAuthorized": { "description": "A list of experiences.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExperienceBase" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "formSubmissionsWhenAuthorized": { "description": "A list of form submissions.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmission" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "properties": { "impressions": { "type": "integer", "description": "The number of times the experience was viewed.", "example": 15230 }, "total": { "type": "integer", "description": "The total number of submissions to the experience, regardless of filters.", "example": 1289 } } } } } } } }, "formSubmissionWhenCreated": { "description": "The form submission was created.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FormSubmission" } } } } } }, "formSubmissionLimitReached": { "description": "Payment Required. The team reached its plan's form submission limit.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "4020002", "title": "Payment Required", "status": "402", "detail": "Form submission limit reached" } ] } } } }, "formSubmissionMetricsWhenAuthorized": { "description": "A list of form submission metrics, sorted by group value in descending order.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmissionMetric" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "formSubmissionMetricsBadRequest": { "description": "Bad Request. The `group` query parameter is invalid.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/x-errors" }, "example": { "errors": [ { "code": "400", "title": "Bad request", "status": "400" } ] } } } }, "formSubmissionExportRequestWhenAuthorized": { "description": "The form submission export request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/FormSubmissionExportRequest" } } } } } }, "postsWhenAuthorized": { "description": "A list of posts.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "postsUpdated": { "description": "The updated posts.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } } }, "postsModeratedMetricsWhenAuthorized": { "description": "A list of moderated post metrics.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostsModeratedMetric" } } } } } } }, "postsEngagementMetricsWhenAuthorized": { "description": "A list of post engagement metrics.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostsEngagementMetric" } } } } } } }, "postsIngestedMetricsWhenAuthorized": { "description": "A list of ingested post metrics.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PostsIngestedMetric" } } } } } } }, "postWhenAuthorized": { "description": "The post.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Post" } } } } } }, "postRequestWhenUnauthorized": { "description": "The post create request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PostRequest" } } } } } }, "postsWhenUnauthorized": { "description": "A list of public posts. Without an access token, the public representation of posts is returned; with one, the authenticated representation is returned.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicPost" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "postsSummaryWhenAuthorized": { "description": "The posts summary for the given filters.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PostsSummary" } } } } } }, "postsSummaryAcceptedWhenAuthorized": { "description": "The posts summary generation has been queued. Repeat the same request later to fetch the completed summary.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PostsSummary" } } } } } }, "postExportRequestWhenAuthorized": { "description": "The post export request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PostExportRequest" } } } } } }, "collectionsWhenAuthorized": { "description": "A list of collections.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "collectionWhenAuthorized": { "description": "The collection.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } } } }, "collectionsUpdated": { "description": "The updated collections.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } } } }, "oauthApplicationsWhenAuthorized": { "description": "A list of OAuth applications.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthApplication" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "oauthApplicationWhenAuthorized": { "description": "The OAuth application.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OAuthApplication" } } } } } }, "webhooksWhenAuthorized": { "description": "A list of webhooks.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "webhookCreated": { "description": "The webhook was created.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "webhookWhenAuthorized": { "description": "The webhook.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Webhook" } } } } } }, "webhookEventsWhenAuthorized": { "description": "A list of webhook events.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "included": { "type": "array", "description": "The delivery attempts, when requested with `include=attempts`.", "items": { "$ref": "#/components/schemas/WebhookAttempt" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "webhookEventWhenAuthorized": { "description": "The webhook event.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEvent" }, "included": { "type": "array", "description": "The delivery attempts, when requested with `include=attempts`.", "items": { "$ref": "#/components/schemas/WebhookAttempt" } } } } } } }, "savedFiltersWhenAuthorized": { "description": "A list of the board's saved filters. The list isn't paginated.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedFilter" } } } } } } }, "savedFilterWhenAuthorized": { "description": "The saved filter.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SavedFilter" } } } } } }, "ctasWhenAuthorized": { "description": "A list of CTAs.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cta" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "ctaWhenAuthorized": { "description": "The CTA.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Cta" } } } } } }, "ctaAssociationWhenAuthorized": { "description": "The CTA association.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CtaAssociation" } } } } } }, "rolesWhenAuthorized": { "description": "A list of roles.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "roleWhenAuthorized": { "description": "The role.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Role" }, "included": { "type": "array", "description": "The related resources requested with the `include` parameter.", "items": { "type": "object" } } } } } } }, "privacyRequestsWhenAuthorized": { "description": "A list of privacy requests.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrivacyRequest" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } } } } }, "privacyRequestWhenAuthorized": { "description": "The privacy request.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PrivacyRequest" } } } } } }, "webhookDeliveryRetried": { "description": "Any other 4XX or 5XX status, a timeout or a connection error fails the attempt, and we retry up to 7 more times with an increasing delay (roughly 1 minute, 1 minute, 2 minutes, 13 minutes, 1 hour, 4 hours, then 13 hours later), after which the event is marked `failure`. More than 50 failed attempts for the same webhook within a week, without a successful delivery in between, set the webhook to `inactive`." }, "webhookDeliveryGone": { "description": "404 Not Found or 410 Gone stops delivery of this event immediately: it is marked `failure` and not retried. The attempt still counts toward the webhook's failure limit." }, "webhookDeliveryAcknowledged": { "description": "Any status below 400 (typically 2XX) acknowledges the event: we mark it `success` and don't send it again. The response body is ignored (we store it with the attempt, for your reference). Redirects are not followed, and a 3XX response also counts as acknowledged, so point the webhook at the final URL." } } } }