Typeface Digital Assets API

openapi: 3.2.0
info:
  title: Typeface 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.
components:
  schemas:
    JsonNode:
      type: object
    SearchAssetsResponseBody:
      type: object
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/SearchedAsset'
        nextCursor:
          type: string
    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
    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

            '
    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.

                  '
    QueryAssetsV2InAccountResponseBody:
      type: object
      properties:
        assets:
          type: array
          items:
            $ref: '#/components/schemas/EntityModelAssetV2'
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    AssetMetadataResponeBody:
      type: object
      properties:
        assetId:
          type: integer
          format: int64
        metadata:
          $ref: '#/components/schemas/Metadata'
    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'
    AssetV2ContentType:
      type: string
      enum:
      - IMAGE
      - FILE
      - PRODUCT
      - URL
      - VIDEO
      - LAYOUT
      - AUDIENCE_SEGMENT
    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
    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
    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)
    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
    Metadata:
      properties:
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-readme:
  explorer-enabled: true
  proxy-enabled: true