Typeface Digital Assets API
The Digital Assets API from Typeface — 7 operation(s) for digital assets.
The Digital Assets API from Typeface — 7 operation(s) for digital assets.
openapi: 3.0.1
info:
title: Typeface Audiences Digital Assets API
version: v0
servers:
- url: https://api-us.typeface.ai
description: Generated server url
security:
- BearerAuth: []
tags:
- name: Digital Assets
paths:
/profile-service/accounts/{accountId}/projects/{projectId}/assets:
get:
tags:
- Digital Assets
operationId: queryAssetsInProject
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: contentType
in: query
required: false
description: Allowed values are 'IMAGE' and 'FILE'
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryAssetsV2InAccountResponseBody'
summary: Project - List Assets
post:
tags:
- Digital Assets
operationId: createAssetInProject
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateAssetV2RequestBody'
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Project - Create Asset
/profile-service/accounts/{accountId}/projects/{projectId}/assets/{assetId}:
description: '`ref` Field Usage in API Responses:
The `ref` field plays a crucial role in the identification and processing of assets across our content generation APIs. It acts as a unique asset identifier that can be leveraged in subsequent API requests. Whenever an API requires asset information within its payload, the ref value from the response should be provided to reference the specific asset.
This field ensures seamless asset integration across various operations, enabling efficient consumption and interaction with assets in our system. Make sure to include the ref field in all relevant requests to facilitate proper asset handling and processing in connected APIs
'
get:
tags:
- Digital Assets
operationId: getAssetInProject
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Project - Get Asset
put:
tags:
- Digital Assets
operationId: updateAssetInProject
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UpdateAssetV2RequestBody'
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Project - Update Asset
delete:
tags:
- Digital Assets
operationId: deleteAssetInProject
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'200':
description: OK
summary: Project - Delete Asset
/profile-service/accounts/{accountId}/projects/{projectId}/assets/{assetId}/metadata:
get:
tags:
- Digital Assets
operationId: getMetadataOfProjectAssets
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/AssetMetadataResponeBody'
summary: Project - Get Metadata
description: This API provides metadata details for a specific asset, with a primary focus on its associated tags.
patch:
tags:
- Digital Assets
operationId: patchMetadataOfProjectAssets
summary: Project - Patch Metadata
description: 'This API allows partial updates to asset metadata, supporting add, replace, and remove operations for the `tags` key.
'
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: projectId
in: path
required: true
description: Unique identifier for the specific project
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataPatchRequest'
responses:
'204':
description: Metadata updated successfully. No content returned.
'400':
description: Bad Request – Validation failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid tag format.
details:
type: string
example: Tag value must be a JSON object for entity 12345
examples:
missingValueField:
summary: Missing or invalid 'value' field
value:
error: Invalid tag format.
details: '''value'' must be a string for entity 12345'
missingTagSourceField:
summary: Missing or invalid 'tagSource' field
value:
error: Invalid tag format.
details: '''tagSource'' must be a string for entity 12345'
invalidTagSource:
summary: tagSource not allowed
value:
error: Invalid tagSource.
details: tagSource must be 'auto', 'user' for entity 12345
notAJsonObject:
summary: value node not a JSON object
value:
error: Invalid tag format.
details: Tag value must be a JSON object for entity 12345
/profile-service/accounts/{accountId}/asset-catalogs/{assetCatalogId}/assets:
get:
tags:
- Digital Assets
operationId: queryAssetsInAssetCatalog
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
schema:
type: integer
format: int64
- name: contentType
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryAssetsV2InAccountResponseBody'
summary: List Assets
post:
tags:
- Digital Assets
operationId: createAssetInAssetCatalog
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
schema:
type: integer
format: int64
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateAssetV2RequestBody'
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Create Asset
/profile-service/accounts/{accountId}/asset-catalogs/{assetCatalogId}/assets/{assetId}:
delete:
tags:
- Digital Assets
operationId: deleteAssetInAssetCatalog
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'204':
description: No Content
summary: Delete Asset
get:
tags:
- Digital Assets
operationId: getAssetInAssetCatalog
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Get Asset
put:
tags:
- Digital Assets
operationId: updateAssetInAssetCatalog
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UpdateAssetV2RequestBody'
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/EntityModelAssetV2'
summary: Update Asset
/profile-service/accounts/{accountId}/asset-catalogs/{assetCatalogId}/assets/{assetId}/metadata:
get:
tags:
- Digital Assets
operationId: getMetadata
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
description: Unique identifier for the specific workspace
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/AssetMetadataResponeBody'
summary: Get Metadata
description: This API provides metadata details for a specific asset, with a primary focus on its associated tags.
patch:
tags:
- Digital Assets
operationId: patchMetadata
summary: Patch Metadata
description: 'This API allows partial updates to asset metadata, supporting add, replace, and remove operations for the `tags` key.
'
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
- name: assetCatalogId
in: path
required: true
description: Unique identifier for the specific workspace
schema:
type: integer
format: int64
- name: assetId
in: path
required: true
description: Unique identifier for the specific asset
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataPatchRequest'
responses:
'204':
description: Metadata updated successfully. No content returned.
'400':
description: Bad Request – Validation failed
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid tag format.
details:
type: string
example: Tag value must be a JSON object for entity 12345
examples:
missingValueField:
summary: Missing or invalid 'value' field
value:
error: Invalid tag format.
details: '''value'' must be a string for entity 12345'
missingTagSourceField:
summary: Missing or invalid 'tagSource' field
value:
error: Invalid tag format.
details: '''tagSource'' must be a string for entity 12345'
invalidTagSource:
summary: tagSource not allowed
value:
error: Invalid tagSource.
details: tagSource must be 'auto', 'user' for entity 12345
notAJsonObject:
summary: value node not a JSON object
value:
error: Invalid tag format.
details: Tag value must be a JSON object for entity 12345
/search-service/accounts/{accountId}/all-assets:
post:
tags:
- Digital Assets
operationId: searchAssets
parameters:
- name: accountId
in: path
required: true
description: Unique identifier for the specific team
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAssetsRequestBody'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAssetsResponseBody'
summary: Search Assets
description: "A unified API to search for assets within a team (and Organization) using various filters.\n\nThis API serves as both listing and search endpoint, listing behavior will return results immediately while search behaviour\nreturns results in a eventual consistent manner, waits for the results to be indexed. Simillarly the updates and deletes are \nalso eventually consistent.\n\n\nAsset sub types for mapped are as follows\n| General Usage | Asset Sub Type |\n|---|---|\n| Uploaded Image | IMAGE |\n| Generated Image | GENERATED_IMAGE |\n| Uploaded File | FILE |\n| Generated Document | GENERATED_DOCUMENT |\n\n**Notes:**\n- To retrive SVG images along with other images pass mediaType in the payload with \n value of `[\"DEFAULT\", \"GRAPHIC_SVG\"]`\n\n#### Sample Image search request payload with both query and tags filtering\n```json\n{\n \"query\": \"A red car on the beachside\",\n \"assetType\": \"IMAGE\",\n \"assetSubTypes\": [\"IMAGE\", \"GENERATED_IMAGE\"],\n \"tags\": [\"vacation\", \"beach\"],\n \"limit\": 20,\n \"cursor\": \".....\",\n \"mediaTypes\": [\"DEFAULT\", \"GRAPHIC_SVG\"]\n}\n```\n\n\n\n#### Sample image search response\n```json\n{\n \"assets\": [\n {\n \"id\": 9192636,\n \"name\": \"Red Car Beachside.png\",\n \"assetType\": \"IMAGE\",\n \"subType\": \"IMAGE\",\n \"workspaceId\": 315726,\n \"workspaceType\": \"ASSET_CATALOG\",\n \"accountId\": \"1f04d7c6-05b2-4623-9fc4-26edb1d076d4\",\n \"createdAt\": \"2025-06-18T02:11:45Z\",\n \"modifiedAt\": \"2025-06-18T02:11:45Z\",\n \"createdBy\": \"f90cffca-819e-49ae-8616-550bb7b46392\",\n \"modifiedBy\": \"f90cffca-819e-49ae-8616-550bb7b46392\",\n \"links\": [\n {\n \"rel\": \"download\",\n \"href\": \"https://deveu2su1sawebapi1000.blob.core.windows.net/blob-persistent-zone/eba343c2-5097-46ff-be0d-bb8147abfbde?sv=2021-08-06&spr=https&se=2025-12-17T13%3A43%3A27Z&sr=b&sp=r&sig=vto8SffoTFib3Le4sRKetscF0I9atCWTjXyAzbHBRJg%3D&rscc=max-age%3D603000%2C%20private\"\n },\n {\n \"rel\": \"thumbnail\",\n \"href\": \"https://deveu2su1renditionsa1000.blob.core.windows.net/rendition-blob-storage/eba343c2-5097-46ff-be0d-bb8147abfbde_230_230?sv=2021-08-06&spr=https&se=2025-12-17T13%3A43%3A28Z&sr=b&sp=r&sig=i5GEY8o%2FtLX25HynTyvusC1ngXrgGl2ESvJO7rnZRUE%3D&rscc=max-age%3D603000%2C%20private\"\n },\n {\n \"rel\": \"self\",\n \"href\": \"https://api-dev-us.typeface.ai/profile-service/accounts/1f04d7c6-05b2-4623-9fc4-26edb1d076d4/asset-catalogs/315726/assets/9192636\"\n },\n {\n \"rel\": \"metadata\",\n \"href\": \"https://api-dev-us.typeface.ai/profile-service/accounts/1f04d7c6-05b2-4623-9fc4-26edb1d076d4/asset-catalogs/315726/assets/9192636/metadata\"\n }\n ],\n \"ref\": \"eyJhY2NvdW50SWQiOiIxZjA0ZDdjNi0wNWIyLTQ2MjMtOWZjNC0yNmVkYjFkMDc2ZDQiLCJlbnRpdHlJZCI6OTE5MjYzNiwid29ya3NwYWNlSWQiOjMxNTcyNiwid29ya3NwYWNlVHlwZSI6IkFTU0VUX0NBVEFMT0ciLCJlbnRpdHlUeXBlIjoiQVNTRVQiLCJ2ZXJzaW9uIjoiMi4wIiwicHJvcGVydGllcyI6eyJpbWFnZUlkIjo5MTkyNjM1fX0=\",\n \"isOrgAsset\": false\n } \n ],\n \"nextCursor\": \".....\"\n}\n```\n\n#### Sample image search payload with search query\n```json\n{\n \"query\": \"A scenic view of mountains during sunrise\",\n \"assetType\": \"IMAGE\",\n \"assetSubTypes\": [\"IMAGE\", \"GENERATED_IMAGE\"],\n \"limit\": 20,\n \"cursor\": \".....\",\n \"collectionIds\": [1234567, 2345678],\n \"mediaTypes\": [\"DEFAULT\", \"GRAPHIC_SVG\"]\n}\n```\n\n#### Filter by tags\nUse the `tags` array to filter assets by one or more tag names. Tag filtering is hierarchical.\nWhen you filter by a parent tag, assets tagged with any of its descendants are automatically included.\n\nFor example, given the tag hierarchy `marketing` → `social_media` → `instagram`, filtering by\n`marketing` returns assets tagged with `marketing`, `social_media`, or `instagram`.\n```json\n{\n \"assetType\": \"IMAGE\",\n \"assetSubTypes\": [\"IMAGE\", \"GENERATED_IMAGE\"],\n \"tags\": [\"marketing\"],\n \"limit\": 20,\n \"cursor\": \".....\",\n \"mediaTypes\": [\"DEFAULT\", \"GRAPHIC_SVG\"]\n}\n```\n\nYou can also filter by a tag at any level in the hierarchy. For example, filtering by `social_media`\nreturns assets tagged with `social_media` or `instagram`, but not those only tagged with `marketing`.\n```json\n{\n \"assetType\": \"IMAGE\",\n \"assetSubTypes\": [\"IMAGE\", \"GENERATED_IMAGE\"],\n \"tags\": [\"social_media\"],\n \"limit\": 20,\n \"cursor\": \".....\",\n \"mediaTypes\": [\"DEFAULT\", \"GRAPHIC_SVG\"]\n}\n```"
components:
schemas:
Metadata:
properties:
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
CreateAssetV2RequestBody:
type: object
properties:
name:
type: string
type:
type: string
deprecated: true
enum:
- IMAGE
contentUrl:
type: string
description: URL from where the content can be downloaded. This should be a pre-signed url
content:
type: string
description: File to be uploaded. Either the contentUrl or content field should be passed in a single request
format: binary
contentType:
type: string
enum:
- IMAGE
- FILE
MetadataPatchRequest:
type: object
required:
- operations
properties:
operations:
type: array
items:
type: object
required:
- operation
- key
properties:
operation:
type: string
enum:
- add
- replace
- remove
key:
type: string
enum:
- tags
value:
type: object
properties:
value:
type: string
tagSource:
type: string
enum:
- user
- auto
- tagRef
description: 'Source of the tag (e.g., user or auto-generated or ref of the tag).
'
index:
type: integer
description: 'Required for ''replace'' and ''remove'' operations. Optional for ''add''. If not provided in ''add'', the tag is appended at the end.
'
Tag:
type: object
properties:
id:
type: integer
format: int64
description: Unique identifier of the tag
name:
type: string
description: Identifier of the tag (e.g., social_media)
displayName:
type: string
description: Human-readable display name of the tag (e.g., Social Media)
tagSource:
type: string
enum:
- user
- auto
- tagRef
description: How the tag was associated with the asset (manually by a user, auto-generated, or via tag reference)
AssetV2ContentType:
type: string
enum:
- IMAGE
- FILE
- PRODUCT
- URL
- VIDEO
- LAYOUT
- AUDIENCE_SEGMENT
Link:
type: object
properties:
rel:
type: string
href:
type: string
hreflang:
type: string
media:
type: string
title:
type: string
type:
type: string
deprecation:
type: string
profile:
type: string
name:
type: string
JsonNode:
type: object
EntityModelAssetV2:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
thumbnailUrl:
type: string
type:
type: string
deprecated: true
enum:
- IMAGE
content:
$ref: '#/components/schemas/JsonNode'
contentType:
type: string
description: Allowed values are 'IMAGE' and 'FILE' only
enum:
- IMAGE
- FILE
ref:
type: string
createdAt:
type: string
format: date-time
modifiedAt:
type: string
format: date-time
createdBy:
type: string
modifiedBy:
type: string
links:
type: array
items:
$ref: '#/components/schemas/Link'
UpdateAssetV2RequestBody:
type: object
properties:
name:
type: string
contentUrl:
description: URL from where the content can be downloaded. This should be a pre-signed url
type: string
content:
type: string
description: File to be uploaded. Either the contentUrl or content field should be passed in a single request
format: binary
contentType:
type: string
enum:
- IMAGE
- FILE
SearchedAsset:
type: object
properties:
id:
type: integer
name:
type: string
assetType:
$ref: '#/components/schemas/AssetV2ContentType'
subType:
type: string
enum:
- GENERATED_IMAGE
- DOCUMENT
- IMAGE
- URL
- FILE
- PRODUCT
- VIDEO
- VIDEO_SHOT
- VIDEO_SCRIPT
- VIDEO_EXPORT
- LAYOUT
- COLLECTION
- AUDIENCE_SEGMENT
workspaceId:
type: integer
workspaceType:
type: string
enum:
- PROJECT
- ASSET_LIBRARY
- LIBRARY
- INSIGHTS_CATALOG
accountId:
type: string
isOrgAsset:
type: boolean
createdAt:
type: string
format: date-time
modifiedAt:
type: string
format: date-time
createdBy:
type: string
modifiedBy:
type: string
ref:
type: string
QueryAssetsV2InAccountResponseBody:
type: object
properties:
assets:
type: array
items:
$ref: '#/components/schemas/EntityModelAssetV2'
links:
type: array
items:
$ref: '#/components/schemas/Link'
SearchAssetsRequestBody:
type: object
properties:
query:
type: string
description: 'Natural language search query. When provided the search honors the query, if not provided anything; all assets match.
'
collections:
type: array
items:
type: string
description: 'List of collection IDs to filter the search results.
'
assetType:
$ref: '#/components/schemas/AssetV2ContentType'
assetSubTypes:
type: array
items:
type: string
enum:
- IMAGE
- GENERATED_IMAGE
- DOCUMENT
- URL
- FILE
- VIDEO
- VIDEO_SCRIPT
- VIDEO_EXPORT
description: 'List of asset sub-types to filter the search results.
'
searchScope:
type: string
enum:
- ACCOUNT
- ORG
description: 'Scope of the search. Defaults to ORG if not provided.
'
cursor:
type: string
description: 'Cursor for pagination.
'
limit:
type: integer
tags:
type: array
items:
type: string
description: 'List of tags to filter the search results.
'
referencedBy:
type: array
items:
type: string
enum:
- PRODUCT
description: 'List of entity types that reference the assets. Currently PRODUCT is only supported.
'
relevance:
type: number
workspaceId:
type: string
description: 'Project Id or Asset librarary Id
'
thumbnailProperties:
type: object
properties:
width:
type: integer
height:
type: integer
description: 'Properties for generating thumbnails in the search results.
'
mediaTypes:
type: array
items:
type: string
enum:
- GRAPHIC_SVG
- DEFAULT
description: 'Media types to filter the search results. Defaults to [DEFAULT] is not specified any
'
SearchAssetsResponseBody:
type: object
properties:
assets:
type: array
items:
$ref: '#/components/schemas/SearchedAsset'
nextCursor:
type: string
AssetMetadataResponeBody:
type: object
properties:
assetId:
type: integer
format: int64
metadata:
$ref: '#/components/schemas/Metadata'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
x-readme:
explorer-enabled: true
proxy-enabled: true