Satalia Logo
API docs by Redocly

Brand Brain Creative API (0.31.0)

Download OpenAPI specification:

Brand Brain: info@satalia.com URL: https://www.satalia.com License: Proprietary

Introduction

The Brand Brain Creative API for Content Generation and chatbot responses.

The API is used for offloading chatbot prompts where the chatbot needs to generate responses where is using these functions:

The API also includes a set of functions for managing the resources required for the above functions.

Submit a search job

Submit a search job to the Knowledgebase.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
external_tracking_id
string non-empty

An optional external job ID to be used for internal tracking purposes.

prompt
required
string non-empty

The prompt for the chatbot.

context_ids
Array of strings [ 1 .. 10 ] items

Optional context IDs for the request.

access
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

labels
Array of strings (Labels) [ 1 .. 100 ] items [ items [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]{1,64}$ ]

These can be used to assist in determining more accurate search results by filtering on documents that have any one of the specified labels.

Only alphanumeric characters, hyphens, and underscores are allowed for each label.

Note: the search is case-insensitive.

mode
string
Default: "SEARCH_AND_ANSWER"
Enum: "SEARCH_AND_ANSWER" "SEARCH_ONLY" "SEARCH_WITH_CONTENT"

Determines the behaviour of the search job.

  • SEARCH_AND_ANSWER (default) retrieves relevant documents and generates a response.
  • SEARCH_ONLY retrieves relevant documents but does not generate a response.
  • SEARCH_WITH_CONTENT retrieves relevant documents and content but does not generate a response.
    • Warning: this mode may make the final result significantly larger and bypasses the additional security option included where the raw content is not stored directly in the system.
callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
Example

A basic request with minimum required arguments.

{
  • "prompt": "What is the process for submitting a travel expense claim?"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get search job

Retrieves the current status and result (if any) of a search via prompt job.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
Example

The job is still processing and the result is not yet available.

{
  • "status": "processing"
}

Context

Knowledgebase API for creating a context based on a document, chat history, competitor analysis, or use case.

Create Context

Create a new context.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
data
string non-empty

The data of the context.

context_type
string

The type of the context.

Responses

Request samples

Content type
application/json
Example

A document uploaded to create a context.

{
  • "data": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  • "context_type": "document"
}

Response samples

Content type
application/json
{
  • "context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686"
}

Administration

Knowledgebase API for managing the Knowledgebase documents.

Submit a Import Document job

Triggers the import of a document into the Knowledgebase database. Once the document is fetched and processed, the chunks are stored in the database and the document is indexed.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
external_tracking_id
string non-empty

An optional external job ID to be used for internal tracking purposes.

uri
required
string non-empty

URI of the document to import.

See the User Guide for supported file types, size limits, and other restrictions.

access
string
Default: "PUBLIC"
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Access level for the imported document.

labels
Array of strings (Labels) [ 1 .. 100 ] items [ items [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]{1,64}$ ]

List of labels to be associated with the document.
These can be used to assist in determining more accurate search results.

Only alphanumeric characters, hyphens, and underscores are allowed for each label.

Note: labels will be stored in a case-insensitive manner.

weight
integer (Weight) [ 1 .. 100 ]
Default: 1

Weight of the document for search ranking.
A higher weight means the document will be ranked higher in search results.

A value of one (1) means the document is not weighted.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
Example

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get Import Job

Retrieves the current status and result (if any) of a Knowledgebase Import job. The result may include the document ID, chunk IDs, and any relevant failures.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid> non-empty
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "result": {
    },
  • "failures": []
}

Get a chunk

Get a chunk by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
chunk_id
required
string <uuid> non-empty

The ID of the chunk.

Responses

Response samples

Content type
application/json
{
  • "chunk_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  • "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n",
  • "access": "PRIVATE",
  • "document_ref": "https://example.com/documents/123",
  • "status": "ACTIVE",
  • "labels": [
    ]
}

List documents

Finds documents in the Knowledgebase database. The search can be performed based on the URI of the document, or it can return all documents. The search can be limited to an exact match of the URI.

This endpoint supports pagination and returns up to 100 documents per page. If there are more documents to be fetched, use the next_page_token from the response to fetch the subsequent page.

Authorizations:
ApiGatewayApiKey
query Parameters
uri
string non-empty
Example: uri=rainbow

A portion of the URI to search for.

exact
boolean
Default: false
Example: exact=true

Whether to match the URI exactly.

page_token
string non-empty
Example: page_token=eyJkb2NfaWQiOiAiZDI5MGYxZWUtNmM1NC00YjAxLTkwZTYtZDcwMTc0OGYwODUxIiwgInVyaSI6ICJodHRwczovL2V4YW1wbGUuY29tL2RvY3MvcmFpbmJvd30ifQ==

A token to retrieve the next page of results. This token is obtained from the next_page_token field in the response of a previous request.

Responses

Response samples

Content type
application/json
Example

A list of documents with a token for the next page.

{
  • "documents": [],
  • "next_page_token": "eyJkb2NfaWQiOiAiZDI5MGYxZWUtNmM1NC00YjAxLTkwZTYtZDcwMTc0OGYwODUxIiwgInVyaSI6ICJodHRwczovL2V4YW1wbGUuY29tL2RvY3MvcmFpbmJvd30ifQ=="
}

Get a document

Get a document by its ID.

Note: Only the first 1000 chunk IDs are returned.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid> non-empty

The ID of the document.

Responses

Response samples

Content type
application/json
{
  • "doc_id": "0480b34a-1be4-43fe-82d6-567c7d9f0fc8",
  • "uri": "https://uri.com/document",
  • "status": "ACTIVE",
  • "access": "PUBLIC",
  • "labels": [
    ],
  • "weight": 10,
  • "chunks": [
    ]
}

Delete a document

Deletes all the chunks for a document by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid>

The ID of the document.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_PATH_PARAMETERS",
  • "message": "Invalid path parameters",
  • "details": {
    }
}

Patch a document metadata

Patch a document metadata by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid> non-empty

The ID of the document.

Request Body schema: application/json
required

The metadata to update for the document. Only the the fields provided will be updated.

non-empty
external_tracking_id
string non-empty

An optional external job ID to be used for internal tracking purposes.

status
string (Status)
Enum: "ACTIVE" "SUSPENDED"

Details the possible status for a resource.

access
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

labels
Array of strings (Labels) <= 100 items [ items [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]{1,64}$ ]

List of labels associated with the record.

weight
integer (Weight) [ 1 .. 100 ]

Weight of the document for search ranking.
A higher weight means the document will be ranked higher in search results.

A value of one (1) means the document is not weighted.

update_reason
string [ 1 .. 128 ] characters

The reason for updating the document metadata.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "external_tracking_id": "8a6953e1-cc2b-4be6-8d8b-f0a87daf7334",
  • "status": "ACTIVE",
  • "access": "PUBLIC",
  • "labels": [
    ],
  • "weight": 1,
  • "update_reason": "string",
  • "callback_url": "https://example.com/webhook-url"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get patch document job

Retrieves the current status and result (if any) of a Knowledgebase Patch Document job.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid> non-empty

The ID of the document.

job_id
required
string <uuid> non-empty
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to retrieve.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "result": {
    },
  • "failures": [
    ]
}

Set the status of a document

Set the status of a document by its ID.

⚠️ This endpoint is deprecated and will be removed in a future release. Please use the 'Patch a document metadata' endpoint.
Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid>

The ID of the document to set the status of

Request Body schema: application/json
required
status
required
string (Status)
Enum: "ACTIVE" "SUSPENDED"

Details the possible status for a resource.

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Response samples

Content type
application/json
{
  • "code": "BAD_PATH_PARAMETERS",
  • "message": "Invalid path parameters",
  • "details": {
    }
}

Set the access of a document

Set the access of a document by its ID.

⚠️ This endpoint is deprecated and will be removed in a future release. Please use the 'Patch a document metadata' endpoint.
Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid>

The ID of the document.

Request Body schema: application/json
required
access
required
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

Responses

Request samples

Content type
application/json
{
  • "access": "PUBLIC"
}

Response samples

Content type
application/json
{
  • "code": "BAD_PATH_PARAMETERS",
  • "message": "Invalid path parameters",
  • "details": {
    }
}

Submit a recommend labels job

Recommend labels for a document based on its content and provided candidate labels.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid>

The ID of the document to analyse.

Request Body schema: application/json

List of candidate labels (including descriptions) to evaluate against the document.

external_tracking_id
string non-empty

An optional external tracking ID to be used for internal tracking purposes.

required
Array of objects (Candidate Labels) [ 1 .. 100 ] items

List of candidate labels to evaluate against the document.
These will be used to accurately recommend the most relevant labels for the document based on its content.

Only alphanumeric characters, hyphens, and underscores are allowed for each label.

Note: labels will be recommended in a case-insensitive manner and returned in uppercase to align with the system's standard label format.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
Example

An example request to recommend labels for a document.

{
  • "labels": [
    ]
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get recommend labels job

Retrieves the current status and result (if any) of a recommend labels job.

Authorizations:
ApiGatewayApiKey
path Parameters
doc_id
required
string <uuid> non-empty

The ID of the document.

job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
Example

The job is still processing and the result is not yet available.

{
  • "status": "processing"
}

Retrieve assets based on a prompt

Retrieve a list of assets based on a given prompt.

⚠️ This endpoint is scheduled to be deprecated, and will be replaced by an asynchronous process.
Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
prompt
required
string non-empty

The prompt for the chatbot.

access
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

Responses

Request samples

Content type
application/json

A basic prompt request.

{
  • "prompt": "What does Paris look like?"
}

Response samples

Content type
application/json
Example

Search for similar assets using image URI

Retrieve a list of assets similar to the one located at the provided URI.

⚠️ This endpoint is scheduled to be deprecated, and will be replaced by an asynchronous process.
Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
image_uri
required
string <uri> non-empty

The URI of the image to search for similar assets.

access
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

Responses

Request samples

Content type
application/json

A basic search via image URI request.

{}

Response samples

Content type
application/json
Example

Administration

Smart Asset Search API for managing the Smart Asset Search assets.

Submit an Import Asset job

Triggers the import of an asset into the Smart Asset Search database.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
external_tracking_id
string non-empty

An optional external job ID to be used for internal tracking purposes.

uri
required
string

URI of the asset to import.

access
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
Example

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get Import Asset job status

Retrieve the status of an Import Asset job.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "message": "The job has finished with failures.",
  • "failures": [
    ]
}

Get Import Asset job result

Retrieve the result of am Import Asset job.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "asset_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
}

List assets

Finds assets in the Smart Asset Search database. The search is performed based on the URI of the asset. The search can be limited to an exact match of the URI.

The search is limited to 100 assets. If more than 100 assets are found, the response will contain the first 100 assets found.

Authorizations:
ApiGatewayApiKey
query Parameters
uri
string
Example: uri=rainbow

A portion of the URI to search for.

exact
boolean
Example: exact=true

Whether to match the URI exactly.

Responses

Response samples

Content type
application/json
Example
[]

Get an asset

Get an asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset to get.

Responses

Response samples

Content type
application/json
{}

Delete an asset

Deletes an asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset to delete.

Responses

Get asset status

Get the status of a asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset.

Responses

Response samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Set the status of an asset

Set the status of a asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset.

Request Body schema: application/json
required
status
required
string (Status)
Enum: "ACTIVE" "SUSPENDED"

Details the possible status for a resource.

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE"
}

Response samples

Content type
application/json
{
  • "message": "Invalid request body"
}

Get the access of an asset

Get the access of an asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset.

Responses

Response samples

Content type
application/json
{
  • "access": "PUBLIC"
}

Set the access of an asset

Set the access of an asset by its ID.

Authorizations:
ApiGatewayApiKey
path Parameters
asset_id
required
string <uuid>

The ID of the asset.

Request Body schema: application/json
required
access
required
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

Responses

Request samples

Content type
application/json
{
  • "access": "PUBLIC"
}

Response samples

Content type
application/json
{
  • "message": "Invalid request body"
}

Dataset Management

Dataset management API for managing the Text-to-Image datasets.

⚠️ This service is a work in progress and may change in future releases.

List datasets

Returns a list of datasets.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create dataset

Creates a new dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
name
required
string non-empty

The name of the dataset.

description
required
string non-empty

A description of the dataset.

required
URLs (object) non-empty

The source of the dataset.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json

Providing URLs as a source.

{}

Response samples

Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "name": "string",
  • "description": "string",
  • "status": "CREATING",
  • "failures": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Callback payload samples

Callback
Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "status": "CREATING",
  • "job_type": "create_dataset"
}

Get dataset

Returns a dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset to get.

Responses

Response samples

Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "name": "string",
  • "description": "string",
  • "status": "CREATING",
  • "failures": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update dataset

Updates a dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset to update.

Request Body schema: application/json
required
name
required
string non-empty

The name of the dataset.

description
required
string non-empty

A description of the dataset.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "name": "string",
  • "description": "string",
  • "status": "CREATING",
  • "failures": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete dataset

Deletes a dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset to delete.

Request Body schema: application/json
optional
callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "not_found",
  • "message": "Dataset not found."
}

Callback payload samples

Callback
Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "status": "CREATING",
  • "job_type": "create_dataset"
}

Annotate dataset

Triggers the annotation of a dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset to annotate.

Request Body schema: application/json
optional
callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "not_found",
  • "message": "Dataset not found."
}

Callback payload samples

Callback
Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "status": "CREATING",
  • "job_type": "create_dataset"
}

List dataset items

Returns a list of items in a dataset.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset the items belong to.

query Parameters
page_token
string non-empty

Optional starting point (page token returned in previous request) for listing dataset items.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "items": [
    ]
}

Create dataset item

Creates a new dataset item.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset the item belongs to.

Request Body schema: application/json
required
source
required
string <uri> non-empty

The source of the dataset item.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "source": "http://example.com",
  • "status": "CREATING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Callback payload samples

Callback
Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "status": "CREATING",
  • "job_type": "create_dataset"
}

Get dataset item

Returns a dataset item.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset the item belongs to.

item_id
required
string <uuid> non-empty

The ID of the dataset item to get.

Responses

Response samples

Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "source": "http://example.com",
  • "status": "CREATING",
  • "failures": [
    ],
  • "annotations": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete dataset item

Deletes a dataset item.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
dataset_id
required
string <uuid> non-empty

The ID of the dataset the item belongs to.

item_id
required
string <uuid> non-empty

The ID of the dataset item to delete.

Request Body schema: application/json
optional
callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "not_found",
  • "message": "Dataset item not found."
}

Callback payload samples

Callback
POST: Dataset Item Status Updates
Content type
application/json
{
  • "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  • "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
  • "status": "CREATING",
  • "job_type": "create_dataset"
}

Model Management

Model management API for managing the Text-to-Image models.

⚠️ This service is a work in progress and may change in future releases.

List models

Returns a list of models.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
query Parameters
page_token
string non-empty

Optional starting point (page token returned in previous request) for listing models.

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "string",
  • "items": [
    ]
}

Create model

Creates a new model.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required

Model creation request.

name
required
string non-empty

The name of the model.

description
required
string non-empty

A description of the model.

model_type
required
string (Model Type) non-empty
Enum: "STABLE_DIFFUSION" "BRIA" "LORA" "VAE" "CONTROLNET"

The type of the model.

required
Hugging Face (object) or URI (object) non-empty

The source of the model. This is where the model is 'cloned' from.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json

Providing a hugging_face payload as a source.

{
  • "name": "My new model",
  • "description": "A new great model, it's capable of great things.",
  • "model_type": "LORA",
  • "source": {
    },
  • "callback_url": "https://example.com/callbacks"
}

Response samples

Content type
application/json
{
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "name": "string",
  • "description": "string",
  • "model_type": "STABLE_DIFFUSION",
  • "source": {
    },
  • "status": "CREATING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Callback payload samples

Callback
POST: Model Status Updates
Content type
application/json
{
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "status": "CREATING",
  • "job_type": "create_model"
}

Get model

Retrieves a model.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
model_id
required
string <uuid> non-empty

The ID of the model to get.

Responses

Response samples

Content type
application/json
{
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "name": "string",
  • "description": "string",
  • "model_type": "STABLE_DIFFUSION",
  • "source": {
    },
  • "status": "CREATING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update model

Updates a model.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
model_id
required
string <uuid> non-empty

The ID of the model to update.

Request Body schema: application/json
required
name
required
string non-empty

The name of the model.

description
required
string non-empty

A description of the model.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "name": "string",
  • "description": "string",
  • "model_type": "STABLE_DIFFUSION",
  • "source": {
    },
  • "status": "CREATING",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete model

Deletes a model.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
model_id
required
string <uuid> non-empty

The ID of the model to delete.

Request Body schema: application/json
optional
callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "not_found",
  • "message": "Model not found."
}

Callback payload samples

Callback
POST: Model Status Updates
Content type
application/json
{
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "status": "CREATING",
  • "job_type": "create_model"
}

Generation

Generate images based on a prompt and pre-trained model(s).

⚠️ This service is a work in progress and may change in future releases.

Submit Image Generation job

Generate images based on a prompt.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
prompt
required
string [ 1 .. 256 ] characters

The criteria for the images to be generated.

negative_prompt
string [ 1 .. 256 ] characters

The criteria for the images to be avoided.

number_of_images
integer [ 1 .. 10 ]
Default: 1

The number of images to generate.

base_model_id
required
string <uuid> non-empty

The base model to use to generate the images.

lora_model_id
string <uuid> non-empty

The LoRA model to use to generate the images.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

external_tracking_id
string non-empty

An optional external job ID to be used for internal tracking purposes.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "prompt": "What does Paris look like?",
  • "negative_prompt": "What does Paris not look like?",
  • "number_of_images": 1,
  • "base_model_id": "0498b419-32fe-43f4-b07d-a62cf1cf96e6",
  • "lora_model_id": "de55252a-4f82-4dac-afbd-844e8ecedfed",
  • "callback_url": "https://example.com/webhook-url",
  • "external_tracking_id": "8a6953e1-cc2b-4be6-8d8b-f0a87daf7334"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "completed"
}

Get Image Generation job status

Retrieve the status of a Text-to-Image generation job.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid> non-empty
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "message": "The job has completed successfully."
}

Get Image Generation job result

Retrieve the result of a Text-to-Image generation job.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid> non-empty
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "images": [
    ]
}

Get generated image data

Get the raw image data of a generated image.

Note: Image size is limited to 10MB (megabytes).

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
image_id
required
string <uri> non-empty

The ID of the generated image.

query Parameters
format
string non-empty
Default: "PNG"
Enum: "JPG" "PNG" "WEBP"

The format of the image.

quality
integer [ 0 .. 100 ]
Default: 100

The quality of the image.

Note: This parameter is only applicable to JPG and WEBP formats.

header Parameters
Accept
string non-empty
Default: image/png
Enum: "image/jpeg" "image/png" "image/webp"

The accepted response content type.

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid request body"
}

Get generated image URL

Get a pre-signed URL for a generated image.

⚠️ This endpoint is a work in progress and may change in future releases.
Authorizations:
ApiGatewayApiKey
path Parameters
image_id
required
string <uri> non-empty

The ID of the generated image.

Responses

Response samples

Content type
application/json
{}

Generation

Generate creative text based on a prompt.

Submit a Creative Text Generation job

Triggers the generation of creative text based on the provided parameters. The generated text will be tailored to the specified engagement type and objective.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
external_tracking_id
string non-empty

Optional external job ID to be used for internal tracking purposes.

required
object non-empty

The engagement type for the generated text.

objective
required
string non-empty

The objective that the generated text is expected to achieve.

required
Array of objects non-empty unique

The section(s) that the generated text should include.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "external_tracking_id": "string",
  • "engagement": {
    },
  • "objective": "string",
  • "sections": [
    ],
  • "callback_url": "https://example.com/webhook-url"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get Generation Job

Retrieves the current status and result (if any) of a text generation job. The result may include sections of generated text, warnings, and any relevant failures.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "result": {
    },
  • "failures": [
    ]
}

Adaptation

Adapt previously generated text content based on specified properties.

Submit a Creative Text Adaptation job

Submits a request to adapt previously generated text content based on specified properties such as content length, brand tone, engagement type, and section structure.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
external_tracking_id
string non-empty

Optional external job ID for internal tracking.

required
Plain Text (string) or Array of Result Sections (objects)

The content to be adapted.

Engagement Type Adaptation (object) or Engagement Type with Platform Adaptation (object) non-empty

The type of engagement for the adapted content.

required
Array of objects (Section Adaptation) non-empty unique

The section(s) that the generated text should include.

callback_url
string <uri> (Callback URL) non-empty

Webhook callback endpoint.

Responses

Callbacks

Request samples

Content type
application/json
Example

Adapting plain text content to a specific content length, target audience, and platform.

{
  • "external_tracking_id": "a3f5d1c2-4f3b-11ec-81d3-0242ac130003",
  • "content": "Introducing the revolutionary Generic Product that will change your daily life!",
  • "engagement": {
    },
  • "sections": [
    ],
  • "callback_url": "https://example.com/callback"
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Callback payload samples

Callback
POST: Job Updates
Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "status": "submitted"
}

Get Adaptation Job

Retrieves the current status and result (if any) of an adaptation job. The result may include sections of adapted text, warnings, and any relevant failures.

Authorizations:
ApiGatewayApiKey
path Parameters
job_id
required
string <uuid>
Example: 13d87fb8-a940-447c-9755-dbe6c631ef57

The ID of the job to query.

Responses

Response samples

Content type
application/json
{
  • "status": "completed",
  • "result": {
    },
  • "failures": [
    ]
}

Config Management

Creative Text Config API for managing the creative text configurations.

List configs

Lists the available creative configs.

Authorizations:
ApiGatewayApiKey
query Parameters
engagement
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: engagement=email

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
string (Platform) non-empty ^[a-z0-9_]+$
Example: platform=facebook

The specific platform for the content.

section
string (Section) non-empty ^[a-z0-9_]+$
Example: section=title

The name identifying a specific part or component within the content.

updated_at_from
string\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[1-2]\d|3[0...
Example: updated_at_from=2024-01-01T00:00:00Z

The updated at date from.
The date must be in the format YYYY-MM-DDTHH:MM:SSZ, and in UTC time.
Also see updated_at_to.

updated_at_to
string\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[1-2]\d|3[0...
Example: updated_at_to=2024-01-01T00:00:00Z

The updated at date to.
The date must be in the format YYYY-MM-DDTHH:MM:SSZ, and in UTC time.
Also see updated_at_from.

sort_by
string non-empty
Default: "updated_at"
Value: "updated_at"
Example: sort_by=updated_at

The field to sort by.

sort_order
string non-empty
Default: "desc"
Enum: "asc" "desc"
Example: sort_order=desc

The sort order.

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=100

The maximum number of items to return.

page_token
string non-empty
Example: page_token=eyJwYWdlX3Rva2VuIjoiY2F0IiwgInNlY3JldCI6IjEifQ==

The page token (returned in the previous request) for getting the next page.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_page_token": "eyJwYWdlX3Rva2VuIjoiY2F0IiwgInNlY3JldCI6IjEifQ=="
}

Create section config

Creates a new creative config for a specific section.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
non-empty
section
required
string (Section) non-empty ^[a-z0-9_]+$

The name identifying a specific part or component within the content.

required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Get section config

Get the configuration for a specific section.

Authorizations:
ApiGatewayApiKey
path Parameters
section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Update section config

Update the configuration for a specific section.

Authorizations:
ApiGatewayApiKey
path Parameters
section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Request Body schema: application/json
required

The new configuration for the section.

non-empty
required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Delete section config

Delete the configuration for a specific section.

Authorizations:
ApiGatewayApiKey
path Parameters
section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "details": { }
}

Create engagement config

Creates a new creative config for an engagement.

Authorizations:
ApiGatewayApiKey
Request Body schema: application/json
required
non-empty
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"

The possible engagement types.

required
object (Engagement Config) non-empty

A configuration that applies to the entire engagement.

Responses

Request samples

Content type
application/json
{
  • "engagement": "social_post",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Get engagement config

Get the configuration for a specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

Responses

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Update engagement config

Update the configuration for a specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

Request Body schema: application/json
required

The new configuration for the engagement.

non-empty
required
object (Engagement Config) non-empty

A configuration that applies to the entire engagement.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Delete engagement config

Delete the configuration for a specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "details": { }
}

Create a platform-specific engagement config

Creates a new creative config for an engagement that applies to a specific platform.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

Request Body schema: application/json
required
non-empty
platform
required
string (Platform) non-empty ^[a-z0-9_]+$

The name identifying a specific platform.

This can be considered as a sub-category of an Engagement. For example, if the Engagement is social_post then the platform could be facebook.

Note: The platform should be relevant to a specified 'engagement'.

required
object (Engagement Config) non-empty

A configuration that applies to the entire engagement.

Responses

Request samples

Content type
application/json
{
  • "platform": "facebook",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Get a platform-specific engagement config

Get the configuration for a platform-specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

Responses

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Update a platform-specific engagement config

Update the configuration for a platform-specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

Request Body schema: application/json
required

The new configuration for the platform-specific engagement.

non-empty
required
object (Engagement Config) non-empty

A configuration that applies to the entire engagement.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "config": {
    },
  • "created_at": "2024-01-01T12:00:00Z",
  • "updated_at": "2024-01-01T12:00:00Z"
}

Delete a platform-specific engagement config

Delete the configuration for a platform-specific engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "details": { }
}

Create an engagement-specific section config

Creates a new creative config for specific section in an engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

Request Body schema: application/json
required
non-empty
section
required
string (Section) non-empty ^[a-z0-9_]+$

The name identifying a specific part or component within the content.

required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Get an engagement-specific section config

Get the configuration for a specific section in an engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Update an engagement-specific section config

Update the configuration for a specific section in an engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Request Body schema: application/json
required

The new configuration for the specific section in an engagement.

non-empty
required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Delete an engagement-specific section config

Delete the configuration for a specific section in an engagement.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "details": { }
}

Create an engagement-platform-specific section config

Creates a new creative config for specific section in an engagement on a specific platform.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

Request Body schema: application/json
required
non-empty
section
required
string (Section) non-empty ^[a-z0-9_]+$

The name identifying a specific part or component within the content.

required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "section": "title",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Get an engagement-platform-specific section config

Get the configuration for a specific section in an engagement that applies to a specific platform.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Update an engagement-platform-specific section config

Update the configuration for a specific section in an engagement that applies to a specific platform.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Request Body schema: application/json
required

The new configuration for the specific section in an engagement that applies to a specific platform.

non-empty
required
object (Section Config) non-empty

A configuration that applies to a specific section.

Responses

Request samples

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "engagement": "social_post",
  • "platform": "facebook",
  • "section": "title",
  • "config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

Delete an engagement-platform-specific section config

Delete the configuration for a specific section in an engagement that applies to a specific platform.

Authorizations:
ApiGatewayApiKey
path Parameters
engagement
required
string (Engagement)
Enum: "generic" "email" "social_post" "blog_post" "creative_brief"
Example: social_post

The form of interaction or communication aimed at capturing attention, promoting content, or encouraging participation.

platform
required
string (Platform) non-empty ^[a-z0-9_]+$
Example: facebook

The specific platform for the content.

section
required
string (Section) non-empty ^[a-z0-9_]+$
Example: title

The name identifying a specific part or component within the content.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST_BODY",
  • "message": "Invalid request body",
  • "details": { }
}

Asset

asset_id
required
string <uuid>

The ID of the asset stored in the Smart Asset Search system.

uri
required
string

The URI of the asset. This is the location of the asset, such as a URL or a unique identifier for an asset in an asset store.

labels
required
string non-empty

The labels associated with the asset.

{
  • "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
  • "uri": "string",
  • "labels": "string"
}

Document

doc_id
required
string <uuid> non-empty

The ID of the document stored in the Knowledgebase.

uri
required
string <uri> non-empty

The URI of the document. This is the location of the document, such as a URL or a unique identifier for a document in a document store.

status
required
string (Status)
Enum: "ACTIVE" "SUSPENDED"

Details the possible status for a resource.

access
required
string (Access)
Enum: "PUBLIC" "PRIVATE" "RESTRICTED"

Details the possible access levels for a resource.

labels
required
Array of strings (Labels) <= 100 items [ items [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]{1,64}$ ]

List of labels associated with the record.

weight
required
integer (Weight) [ 1 .. 100 ]
Default: 1

Weight of the document for search ranking.
A higher weight means the document will be ranked higher in search results.

A value of one (1) means the document is not weighted.

chunks
required
Array of strings <uuid> non-empty [ items <uuid > ]

A list of chunk IDs for the document stored in the Knowledgebase.

Note: Only the first 1000 chunk IDs are returned.

{
  • "doc_id": "c8561737-9a40-4d91-8958-e405c0ad8596",
  • "uri": "http://example.com",
  • "status": "ACTIVE",
  • "access": "PUBLIC",
  • "labels": [
    ],
  • "weight": 1,
  • "chunks": [
    ]
}