Portal

Getting Started (1.0.0)

Cincopa REST API V2 to get/set and manipulate assets and galleries

Cincopa REST API V2 is a simple set of REST based methods that allow you to access almost every aspect of your galleries and assets. Authentication is done with a simple api_token that can be created and deleted per app, set the permission level according to the needed level and exposure level.

V2 API was designed to be used:

  • in server-to-server scenario where the api_token and information is not exposed to the public, in such scenario the permissions level can allow write and delete.
  • in client-to-server scenario like javascript request from a public web page, in this scenario permission level will be set to read only which ensures the safety of your web app. This unique architecture eliminates the need of creating a "proxy" service that usually needed when working with a 3rd party API thus saving you time in integration.
Download OpenAPI description
index.json
index.yaml
Overview
Cincopa API Support support@cincopa.com
License MIT
Languages
Servers
Cincopa API
https://api.cincopa.com/v2/

General

This section offers foundational API endpoints essential for establishing and validating connections with the Cincopa platform. These endpoints are designed to ensure smooth integration and secure interactions between your application and Cincopa's services.

Key FunctionalitiesEndpointPurpose
Validate API Connection/ping.jsonThis endpoint allows you to confirm the validity and responsiveness of your API connection. By sending a request to /ping.json with your api_token, you can verify that your application is properly authenticated and can communicate effectively with Cincopa's servers.
Obtain a Temporary Token/token.get_temp.jsonIn scenarios where frontend applications require direct interaction with Cincopa's API, this endpoint provides a secure method to generate temporary tokens. These tokens facilitate client-to-server communications, enabling operations like updating galleries or assets directly from client-side code without exposing permanent credentials.
Operations

Gallery

This section provides a comprehensive suite of methods for managing your media galleries. The Gallery API empowers developers to programmatically create, manage, and customize multimedia galleries for seamless integration into applications, websites, or digital platforms.

Whether you're building a media-rich portal, a dynamic content hub, or a branded video experience, this API provides granular control over gallery configurations, media assets, permissions, and display logic.

Key FunctionalitiesEndpointPurpose
Creating Galleries/gallery.create.jsonEstablish new media galleries to organize your content effectively.
Setting Gallery Metadata/gallery.set_meta.json Update gallery information such as title, description, and custom properties to keep your content organized and accessible.
Deleting Galleries/gallery.delete.jsonRemove galleries that are no longer needed, ensuring your media library stays current.
Adding Items to Galleries/gallery.add_item.jsonIncorporate new media assets into existing galleries to enhance your content offerings.
Removing Items from Galleries/gallery.remove_item.jsonManage your galleries by removing outdated or unwanted media assets.
Listing Galleries/gallery.list.jsonRetrieve a list of all galleries in your account for easy management and overview.
Retrieving Gallery Items/gallery.get_items.jsonAccess detailed information about the media assets contained within a specific gallery.
Setting Master Media/gallery.set_master.jsonDesignate a primary media asset within a gallery to highlight featured content.
Operations

Assets

This section provides a comprehensive suite of methods for managing assets within your account. The Assets API enables developers to efficiently upload, organize, modify, and retrieve digital assets, ensuring seamless integration into applications, websites, or media platforms.

Whether you're handling large media libraries, automating asset management, or implementing structured metadata, this API offers precise control over asset creation, metadata customization, categorization, and retrieval, enhancing workflow efficiency and content organization.

Key FunctionalitiesEndpointPurpose
List Assets/asset.list.jsonGet a list of assets in the account; those assets can be added to any gallery. Use search to locate specific assets or use reference_id to locate by reference_id of the asset.
List Tags/asset.get_tags.json Fetches all tags associated with assets for categorization and filtering. Returns a structured list for efficient metadata management.
Set meta data of an asset/asset.set_meta.jsonUpdates or adds metadata (title, description, custom fields) for a specific asset. Requires the asset ID and enhances searchability and organization.
Resync an asset/asset.resync.jsonResync an asset will start a process of checking for missing versions and generating them. This method is only needed in cases of a failure to sync a gallery.
Delete an asset/asset.delete.jsonDelete an asset for good, it will be removed also from any gallery that exists.
Get upload URL to POST an asset./asset.get_upload_url.jsonGet upload URL to your assets library, use this URL with an HTTP POST method. Asset can be added directly to a gallery or be attached to another asset to set the video poster, for example. When attaching to another asset, it must provide a type name.
Start uploading an asset from an input URL./asset.upload_from_url.jsonUpload an asset from an input URL. Asset can be added directly to a gallery or be attached to another asset to set the video poster, for example. When attaching to another asset, must provide a type name. This method will return a status ID that can be used by asset.upload_from_url_get_status to get information about the upload process and the ID of the uploaded asset when done.
Get status during and after the uploading process./asset.upload_from_url_get_status.jsonUse this method to get the Id of the uploaded asset when done.
Abort uploading process./asset.upload_from_url_abort.jsonUse this method to abort an upload.
Operations

Upload

This section provides you with a detailed overview of Cincopa's Upload API, which allows users to upload media files to their Cincopa galleries efficiently. The API offers two primary methods for uploading content: an embeddable iFrame for direct user uploads and a secure token-based system for controlled access. These options ensure flexibility, security, and ease of use, making it simple to integrate media uploads into your applications or websites.

With the embeddable iFrame, users can upload media directly through an interactive interface that supports drag-and-drop functionality, media selection, and content management features like metadata editing and file reordering. On the other hand, the token-based system ensures that only authorized users can upload media by generating a secure upload token.

Key FunctionalitiesEndpointPurpose
HTML iframe to manage gallery/upload.iframeProvides an embeddable iFrame URL for users to upload media directly to a Cincopa gallery. The interface supports drag-and-drop uploads, media selection, metadata editing, reordering, and deletion. It is fully responsive across devices.
Invite upload token/upload.get_upload_token.jsonGenerates a unique token that restricts access to the invite upload page, ensuring that only authorized users can upload media to a specified gallery.
Operations

Portal

This section provides a comprehensive suite of methods for managing and customizing portals. The Portal API allows developers to programmatically create, manage, and configure landing pages, video hubs, and share pages for seamless integration into applications, websites, or digital platforms.

Whether you're building a dynamic content hub, a multimedia-rich portal, or a branded video experience, this API offers full control over portal settings, status management, and retrieval of existing portals. The following table provides a breakdown of the available API endpoints and their functions:

Key FunctionalitiesEndpointPurpose
Verify subdomain/portal.check.jsonChecks if a portal exists and retrieves its status. This is useful for validating whether a portal is active before performing further operations.
Create subdomain if available/portal.cease.json Deactivates or ceases an existing portal. This operation is useful when a portal is no longer needed but should not be permanently deleted.
Rename subdomain/portal.rename.jsonRenames a specified portal by providing the existing portal ID and the new desired name. This helps in organizing portals efficiently.
Remove subdomain/portal.remove.jsonDeletes a portal from the system. This operation is irreversible and permanently removes all associated data.
Save subdomain/portal.set.jsonCreates a new portal or updates the settings of an existing one. This allows customization of portal properties such as name, visibility, and other configurations.
List of portals/portal.list.jsonRetrieves a list of all configured portals along with their details. This endpoint helps in managing multiple portals and tracking their statuses.
Operations

Verify subdomain

Request

The API allows developers to check whether a specific subdomain is available for use. This is particularly useful when creating new portals, custom domains, or other web-based services that require a unique subdomain. By making a simple API request, users can determine if their desired subdomain is already taken or available for registration.

Endpoint: GET /portal.check.json

URL: https://api.cincopa.com/v2/portal.check.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
subdomainstringrequired

The name of the subdomain to be checked for availability. The API will return a response indicating whether the subdomain is free or already in use.

Choose a unique subdomain name to increase the chances of availability and avoid conflicts with existing domains.

Example: subdomain=test4
curl -i -X GET \
  'https://api.cincopa.com/v2/portal.check.json?api_token=AAAAtAURG&subdomain=test4'

Responses

When the request is successful, the API returns a JSON response containing relevant details about the requested resource. This response provides key information regarding the availability and status, enabling developers to assess whether further actions are needed. Below are the response parameters with their descriptions and examples.

Bodyapplication/json
successboolean

Indicates whether the request was successful. true for success, false for failure. Always true for a 200 response.

Example: true
runtimeinteger

Specifies the total time taken to process the request, measured in milliseconds.

Example: 77
subdomainstring

Specifies whether the requested subdomain is available or not. Possible values may include available, unavailable, or other relevant status messages.

Example: "available"
Response
application/json
{
  "success": true,
  "runtime": 77,
  "subdomain": "available"
}

Create subdomain if available

Request

This API endpoint allows users to create a new subdomain if it is available. By making a request with the required parameters, users can initiate the subdomain creation process. The API validates the provided credentials and checks the availability of the requested subdomain before processing the request.

Endpoint: POST /portal.cease.json

URL: https://api.cincopa.com/v2/portal.cease.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
subdomainstringrequired

The name of the subdomain to be created. The API will check if the subdomain is available before proceeding with the creation.

Example: subdomain=test4
curl -i -X POST \
  'https://api.cincopa.com/v2/portal.cease.json?api_token=AAAAtAURG&subdomain=test4'

Responses

When a request is successfully processed, the API returns a structured JSON response containing key details about the request status. This response helps confirm whether the request was successful and provides additional information about the server's processing time. Below are the response parameters with their descriptions and examples.

Bodyapplication/json
successboolean

A flag indicating the success of the request. True means the request was processed successfully, while false indicates failure

Example: true
runtimeinteger

The total time (milliseconds) taken by the server to process the request and return a response.

Example: 44
Response
application/json
{
  "success": true,
  "runtime": 44
}

Rename subdomain

Request

This API endpoint allows users to rename an existing subdomain. By providing the current subdomain name and the desired new name, the request will update the subdomain accordingly. Authentication is required through an API token to ensure that only authorized users can perform this action.

Endpoint: POST /portal.rename.json

URL: https://api.cincopa.com/v2/portal.rename.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
fromstringrequired

Specifies the existing subdomain name that needs to be changed. The subdomain must already exist within the system, and the user making the request must have the necessary permissions to modify it.

Careful
If the new subdomain name is already taken or does not follow naming rules, the API may return an error. Verify subdomain availability before renaming to avoid conflicts.

Example: from=test87
tostringrequired

Defines the new name for the subdomain after renaming. The new name must follow the system's naming conventions (e.g., length limits, allowed characters) and must not be already in use by another subdomain. If the requested subdomain name is unavailable, the API may return an error indicating that the name is already taken.

Example: to=test88
curl -i -X POST \
  'https://api.cincopa.com/v2/portal.rename.json?api_token=AAAAtAURG&from=test87&to=test88'

Responses

When the request to rename a subdomain is successful, the API returns a JSON response containing key details about the operation's outcome. This response provides information on whether the subdomain was successfully renamed and how long the server took to process the request. Below are the response parameters with their descriptions and examples.

Bodyapplication/json
successboolean

A flag indicating the success of the request. True means the request was processed successfully, while false indicates failure

Example: true
runtimeinteger

The total time (milliseconds) taken by the server to process the request and return a response.

Example: 44
Response
application/json
{
  "success": true,
  "runtime": 44
}

Remove subdomain

Request

This API endpoint allows users to delete an existing subdomain from the system. This action is irreversible, meaning that once a subdomain is removed, it cannot be recovered, and any associated services or configurations will be lost. Proper authentication is required to perform this operation.

Endpoint: POST /portal.remove.json

URL: https://api.cincopa.com/v2/portal.remove.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
subdomainstringrequired

The name of the subdomain to be removed. The subdomain must exist within the system and be accessible by the user making the request.

Example: subdomain=test987
curl -i -X POST \
  'https://api.cincopa.com/v2/portal.remove.json?api_token=AAAAtAURG&subdomain=test987'

Responses

When a request to remove a subdomain is processed, the API returns a JSON response indicating the success or failure of the operation. Below are the response parameters with their descriptions and examples.

Bodyapplication/json
successboolean

A flag indicating the success of the request. True means the request was processed successfully, while false indicates failure

Example: true
runtimeinteger

The total time (milliseconds) taken by the server to process the request and return a response.

Example: 44
Response
application/json
{
  "success": true,
  "runtime": 44
}

Save subdomain

Request

The Save subdomain API endpoint allows you to create or update a subdomain configuration for a Cincopa-hosted portal. This endpoint is critical for configuring custom access rules, authentication methods (e.g., SSO, user/password), and domain mappings for your portal. Use it to:

  • Set up a branded subdomain (e.g., portal.yourcompany.cincopa.com).
  • Control public/private access to the portal.
  • Integrate Single Sign-On (SSO) via Google or Cincopa’s native authentication.
  • Map custom domains (CNAME) to the portal.

Endpoint: POST/ portal.set.json

URL: https://api.cincopa.com/v2/portal.set.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
subdomainstringrequired

Specifies the name of the subdomain to be created. This must be unique within the Cincopa platform.

Careful
subdomain must be unique within Cincopa; duplicate entries will fail.

Example: subdomain=test456
templatestring

The path to a predefined template that can be used to structure the portal’s appearance.

Example: template=/templates/corporate
argsstring

A JSON string containing additional settings for the template.

Careful
argsmust be a properly formatted JSON string; invalid JSON will cause errors.

Example: args=JSON.stringify ({primary_color:"#2A5F9E", logo_url:"https://acme.com/logo.png"})
allow_publicstring

Determines if the portal is publicly accessible. Possible values:yes (anyone can access) or no (restricted access).

Careful
allow_publicaccepts only yes or no; any other value will be rejected.

Default "yes"
Example: allow_public=no
cincopa_loginstring

Enables or disables Cincopa login authentication. yes requires users to log in with Cincopa credentials. Controls user registration when Cincopa login is enabled. anyone allows open registration, restricted limits it, and off disables it.

Default "no"
Example: cincopa_login=yes
cincopa_login_registrationstring

Controls user registration when Cincopa login is enabled. anyone allows open registration, restricted limits it, and off disables it.

Default "restricted"
Example: cincopa_login_registration=restricted
cincopa_login_user_addstring

Comma-separated list of emails authorized to access the portal using Cincopa login.

Example: cincopa_login_user_add=john@acme.com,emma@acme.com
cincopa_login_user_removestring

Comma-separated list of emails to be removed from the Cincopa authorization list.

Example: cincopa_login_user_remove=old@acme.com
cincopa_login_domain_addstring

Allows login access for users from specified domains. Accepts a comma-separated list of domains.

Example: cincopa_login_domain_add=acme.com
cincopa_login_domain_removestring

Removes specified domains from the authorization list, revoking access for associated users.

google_openid_user_addstring

Grants login access via Google OpenID for specific email addresses. Emails should be comma-separated.

Example: google_openid_user_add=sso-user@acme.com
google_openid_user_removestring

Removes specified Google email addresses from the portal’s authorization list.

Example: google_openid_user_remove=former@acme.com
google_openid_domain_addstring

Authorizes all users from specified Google domains to log in via OpenID.

Example: google_openid_domain_add=acme.com
google_openid_domain_removestring

Revokes OpenID login access for users from specified Google domains.

simple_user_addstring

Adds users using a CSV user:password format or a JSON array for access control.

Example: simple_user_add=old_client
simple_user_removestring

Removes specified users from the authorization list using a comma-separated format.

cname_domainstring

Your domain name to map (CNAME) to this portal. Make sure to map your domain before you make this API call. For example to map your subdomain https://videos.acme.com to your Cincopa portal name https://acme.cincopa.com first go to your DNS provider and create a CNAME record host - video.acme.com points to - acme.cincopa.com. For more information read our help article.

Careful
cname_domain must have a valid CNAME record set up before making the API call.

curl -i -X POST \
  'https://api.cincopa.com/v2/portal.set.json?allow_public=no&api_token=AAAAtAURG&args=JSON.stringify%20({primary_color%3A%22%232A5F9E%22%2C%20logo_url%3A%22https%3A%2F%2Facme.com%2Flogo.png%22})&cincopa_login=yes&cincopa_login_domain_add=acme.com&cincopa_login_domain_remove=string&cincopa_login_registration=restricted&cincopa_login_user_add=john%40acme.com%2Cemma%40acme.com&cincopa_login_user_remove=old%40acme.com&cname_domain=string&google_openid_domain_add=acme.com&google_openid_domain_remove=string&google_openid_user_add=sso-user%40acme.com&google_openid_user_remove=former%40acme.com&simple_user_add=old_client&simple_user_remove=string&subdomain=test456&template=%2Ftemplates%2Fcorporate'

Responses

When a subdomain is successfully saved, the API returns a JSON response containing key details about the request’s execution. Below are the response parameters with corresponding descriptions and examples.

Bodyapplication/json
successboolean

A flag indicating the success of the request. True means the request was processed successfully, while false indicates failure

Example: true
runtimeinteger

The total time (milliseconds) taken by the server to process the request and return a response.

Example: 44
Response
application/json
{
  "success": true,
  "runtime": 44
}

List of portals

Request

This API endpoint retrieves a list of available portals based on the provided query parameters. It allows users to fetch either all portals or filter the results using a specific subdomain. This API requires authentication via an api_token to ensure secure access.

Endpoint: GET/ portal.list.json

URL: https://api.cincopa.com/v2/portal.list.json

Query
api_tokenstringrequired

A unique key used for authentication. Must be a valid API key provided by the system. Without the valid api_token, the request will be rejected with a 403 Unauthorized error.

Example: api_token=AAAAtAURG
subdomainstring

Specifies the subdomain name to filter the portal list. If left blank, the API will return all available portals.

Example: subdomain=test6789
curl -i -X GET \
  'https://api.cincopa.com/v2/portal.list.json?api_token=AAAAtAURG&subdomain=test6789'

Responses

When the request to retrieve the list of portals is successfully processed, the API returns a JSON response containing key details about the available portals. Below are the response parameters with their descriptions and examples.

Bodyapplication/json
successboolean

Indicates whether the request was successful. true for success, false for failure. Always true for a 200 response.

Example: true
runtimeinteger

Specifies the total time taken to process the request, measured in milliseconds.

Example: 77
portalsArray of arrays

Contains the list of portals retrieved based on the provided subdomain or all portals if no subdomain is specified.

Example: [{"id":101,"name":"TechDocs Portal","subdomain":"techdocs","created_at":"2024-03-10T12:45:00Z","status":"active"}]
Response
application/json
{
  "success": true,
  "runtime": 77,
  "portals": [
    { … }
  ]
}

Webhook

This section provides a streamlined way to receive real-time notifications about account activities via HTTP POST callbacks. Instead of continuously polling for updates, webhooks allow external applications to listen for specific events and respond accordingly.

This API enables developers to automate workflows, synchronize data, and receive alerts whenever significant actions occur in the system. Additionally, the API supports Slack integration, allowing event notifications to be delivered directly to a Slack channel for easy monitoring and collaboration.

Key FunctionalitiesEndpointPurpose
List of webhooks/webhook.list.jsonRetrieves a list of all active webhooks associated with the account, including their configurations and callback URLs.
Create/update webhook/webhook.set.jsonRegisters a new webhook by specifying a callback URL and event types to trigger notifications.
Create/update webhook to slack/webhook.set_slack.jsonSets up a webhook that sends real-time event notifications directly to a Slack channel for instant updates.
Delete a webhook/webhhook.delete.jsonDeletes an existing webhook, stopping further event notifications and removing it from the system.
Operations

Live

Professional Live Video Streaming Service.

Operations