This article explains how to use the Create content endpoint of the SMARTFENSE API to create your organization's own content automatically. It covers the requirements, the request structure, image handling and the response codes.
What does this endpoint do?
The Create content endpoint creates organization content from the same JSON used to load predefined content.
It currently accepts the following content types:
- Newsletters
- Teachable moments
- Phishing
- Ransomware
- Interactive modules
- Exams
- Surveys
- Courses
The content type is defined in the request path. The content is saved as your organization's own content and becomes available for use in campaigns.
Important: the content is created only in the languages included in the JSON. Those languages must be active in the organization. The API does not translate the texts.
Prerequisites
- Have a registered application in Configuración > Integraciones > Aplicaciones registradas, with its Client ID and Client Secret.
- Assign the
write_contents_createscope (Create content) to the application. - Use one of the supported OAuth 2.0 flows: Authorization code or Client credentials.
- Know the ID of the application catalog where the content will be saved.
For more information on registering an application and obtaining the access token, see the article Integración de APIs en SMARTFENSE.
Endpoint
POST https://tenant.takesecurity.com/api/v1/contents/{content_type}Replace tenant with the subdomain of your SMARTFENSE instance.
Required headers:
Authorization: Bearer <access_token>Content-Type: application/json
Path parameter
| Parameter | Type | Required | Description |
|---|---|---|---|
content_type | string | Yes | Type of content to create. It determines the request body schema. |
Check the exact
content_typevalues in the Contenidos > Create content section of the official API documentation, available athttps://tenant.takesecurity.com/api/schema/redoc/.
Request body structure
The request body varies depending on the content type. The documentation presents it as One of with the following schemas:
- NewsletterContentRequest
- TeachableContentRequest
- PhishingContentRequest
- RansomwareContentRequest
- TrainingContentRequest
- ExamContentRequest
- SurveyContentRequest
- CourseContentRequest
The common fields are:
| Field | Type | Required | Description |
|---|---|---|---|
active | boolean | No | Defines whether the content is created active (available for campaigns) or inactive (to review and activate it from the platform). Default value: true. |
difficulty | string | Yes | Content difficulty: low, medium or high. |
compliance_mappings | array of objects | No | Clauses of the predefined regulations activated by the organization. Each object includes normative_id and normative_clause_id. |
categories | array of integers | No | IDs of predefined categories. |
themes | array of integers | No | IDs of predefined themes. |
tags | array of integers | No | IDs of predefined tags. |
catalog_id | integer | Yes | Catalog where the content is saved. |
estimated_minutes | integer (>= 0) | Yes | Estimated reading time in minutes. |
presentation_image_url | string | No | Presentation image. It can be a platform file (predefined or from the organization) or an https address. |
content | object | Yes | Texts for each language, identified by their code (for example, es-ar). |
Categories, themes, tags and regulations must be predefined and available to the organization. The content can only be saved in an application catalog.
Request example (newsletter)
{
"active": false,
"difficulty": "medium",
"compliance_mappings": [
{ "normative_id": 0, "normative_clause_id": 0 }
],
"categories": [0],
"themes": [0],
"tags": [0],
"catalog_id": 0,
"estimated_minutes": 5,
"presentation_image_url": "https://www.example.com/image.png",
"content": {
"es-ar": { }
}
}Replace the
0values with your organization's actual IDs. The internal structure of each language withincontentdepends on the content type. For newsletters and teachable moments, it follows the EmailTextsRequest schema. See the details of each schema in the official API documentation.
Image handling
Images can be specified in two ways:
- Platform file: a predefined file or one belonging to the organization.
- https address: a URL on port 443 of a public server.
When you use an https address, the platform downloads the image during the same request, before creating the content. The image is saved as an organization image, just as if it had been uploaded from the screen. This way, the content does not depend on the source site.
If the same address appears in several fields or languages, it is downloaded only once.
Image limits
| Limit | Value |
|---|---|
| Accepted formats | PNG, JPEG and GIF |
| Maximum size per image | 4 MB |
| Maximum pixels | 25 million |
| Maximum frames (GIF) | 100 |
| Addresses per content | Up to 10 |
| Redirects per address | Up to 3 |
| Maximum download time | 12 seconds (all downloads) |
Important: if an image cannot be downloaded, the response indicates the affected field and the content is not created.
Successful response
If the request is correct, the API responds with code 201 and the following body:
{
"content_code": "string",
"content_type": "string",
"name": "string"
}| Field | Description |
|---|---|
content_code | Content code. This is the value that the campaign write API receives to assign the content to a campaign. |
content_type | Content type, same as in the path. |
name | Content name. |
Save the content_code. You will need it to assign the content to a campaign through the API.
Error codes
| Code | Meaning |
|---|---|
| 400 | The JSON is not valid or references something the organization cannot use. The response indicates which field and why. |
| 405 | The API does not create content of that type yet. |
| 429 | The application exceeded the number of requests allowed per minute, or there are too many image downloads in progress. The Retry-After header indicates how many seconds to wait before retrying. |
💡 Best practices
- Create content with
"active": falseto review it on the platform before using it in campaigns. - Assign only the write_contents_create scope to the application if its sole purpose is creating content.
- Check that the JSON languages are active in the organization before sending the request.
- Host images on stable public servers with fast response times so you do not exceed the 12-second limit.
- Optimize image size before sending them to avoid size-related rejections.
- If you receive a 429 error, wait the time indicated in Retry-After before retrying.
- Keep a record of the content_code of each created content so you can later automate campaign creation.