canonical: https://jentic.com/apis/cincopa.com/cincopa # Cincopa REST API V2 Jentic publishes the only available OpenAPI specification for Cincopa REST API V2, keeping it validated and agent-ready. Cincopa is a media hosting and gallery platform that lets developers manage image, video, and audio assets along with the galleries that present them. The REST API V2 exposes 19 endpoints for asset upload, tagging, gallery composition, and metadata management, with separate read/write modes for server-to-server flows and read-only client tokens. Authentication uses an api_token passed as a query parameter. ## For AI agents Upload, tag, and organise media assets in Cincopa galleries, and manage gallery membership and metadata for embed-ready video and image experiences. ## Scope Does not handle live streaming, DRM packaging, or video editing - use for media hosting and gallery composition only. ## Capabilities - Upload images, video, and audio to Cincopa via /asset.upload_from_url.json or signed upload URLs from /asset.get_upload_url.json - Resync remote assets to refresh transcoded variants via /asset.resync.json - Tag and retag assets and read tag taxonomies via /asset.set_meta.json and /asset.get_tags.json - Compose galleries by adding and removing assets via /gallery.add_item.json and /gallery.remove_item.json - Designate a master asset for a gallery via /gallery.set_master.json to control the primary thumbnail or hero - List, create, and delete galleries via /gallery.list.json, /gallery.create.json, and /gallery.delete.json - Issue temporary read-only tokens for client-side embeds via /token.get_temp.json ## Use cases ### Server-Side Media Upload Pipeline Push images and video into Cincopa from a backend job by requesting an upload URL or supplying a remote URL, then tagging the new asset and adding it to the right gallery in a single workflow. The /asset.get_upload_url.json and /asset.upload_from_url.json endpoints support both direct binary upload and remote ingestion, while /asset.set_meta.json applies tags and metadata as the asset is created. Example prompt: Call /asset.upload_from_url.json with the source URL and gallery ID, then call /asset.set_meta.json to attach campaign tags and a description. ### Gallery Composition for Marketing Pages Build and rearrange Cincopa galleries that drive product, blog, and landing page experiences by adding or removing items, designating a master asset for hero positioning, and updating gallery metadata. The /gallery.add_item.json, /gallery.remove_item.json, /gallery.set_master.json, and /gallery.set_meta.json endpoints together cover the curation workflow without writing custom CMS code. Example prompt: Add asset abc123 to gallery xyz789 via /gallery.add_item.json then mark it as the gallery master via /gallery.set_master.json. ### Browser-Safe Read-Only Embeds Embed Cincopa galleries on public sites without leaking the master api_token by minting a short-lived read-only token via /token.get_temp.json and passing it to the browser. This keeps the privileged token on the server while the client can still load gallery metadata and assets for rendering. Example prompt: Mint a temporary read token via /token.get_temp.json scoped to a single gallery and return it to the browser embed code. ### AI Agent Media Curation via Jentic An AI agent receives a request to add a new product video to a marketing gallery, searches Jentic for the upload-and-attach operations, and calls Cincopa via Jentic without ever holding the api_token. Jentic securely stores the credential and the agent only sees the schema for the relevant /asset and /gallery operations. Example prompt: Use the Jentic search query 'upload a video to a gallery' to find the Cincopa upload and add-item operations and execute them with the new product video URL. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/asset.get_upload_url.json` | Request a signed upload URL for direct binary upload | | POST | `/asset.upload_from_url.json` | Ingest a remote asset by URL | | POST | `/asset.set_meta.json` | Set metadata and tags on an asset | | POST | `/gallery.create.json` | Create a new gallery | | POST | `/gallery.add_item.json` | Add an asset to a gallery | | POST | `/gallery.set_master.json` | Designate the master asset for a gallery | | POST | `/token.get_temp.json` | Mint a temporary read-only API token | ## Key resources - **Asset** — Upload, tag, list, resync, and delete media assets - **Gallery** — Create galleries, add and remove items, set the master asset, and manage metadata - **Token** — Issue temporary read-only tokens for client-side embeds ## Why Jentic - **Setup:** Wiring Cincopa by hand means managing its API key, calling its JSON-RPC style asset and gallery operations, and juggling temporary upload tokens yourself. Through Jentic you install once, import the Cincopa REST API V2 from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** Cincopa's write operations take the target asset or gallery id in the request body rather than the URL path, so scope the agent to the operations it needs, such as uploading assets and building galleries. You choose the operations it may call, so a rule can allow gallery composition while leaving out anything you do not want it to run. - **Credential handling:** Your Cincopa API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'upload a video asset' or 'create a media gallery', and Jentic returns the matching Cincopa operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Cloudinary Upload API** — Image and video upload, transformation, and delivery API - **Vimeo** — Video hosting platform with player, privacy controls, and analytics - **Mux** — Video streaming, encoding, and analytics API ## FAQ ### Why is there no official OpenAPI spec for Cincopa REST API V2? Cincopa does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Cincopa REST API V2 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Cincopa REST API V2 use? The API uses an apiKey called api_token passed as a query parameter on every request. Through Jentic the api_token is stored in the encrypted vault and the agent never receives the raw value, only a scoped execution context. ### Can I upload a video to Cincopa from a remote URL? Yes. Call /asset.upload_from_url.json with the source URL and the target gallery, and Cincopa will fetch and transcode the asset. Upload status can be polled via /asset.upload_from_url_get_status.json. ### How do I add an asset to a Cincopa gallery through Jentic? Search Jentic for 'add a video to a gallery', load the schema for /gallery.add_item.json, and execute with the gallery and asset IDs. The Python SDK uses await client.search, await client.load, await client.execute. ### How do I generate a browser-safe read-only token? Call /token.get_temp.json on the server with the master api_token to mint a temporary read-only token, then pass that scoped token to the browser embed. The master token never leaves the server. ### How do I tag a Cincopa asset and read tags back? Use /asset.set_meta.json to attach tags as metadata and /asset.get_tags.json to read the tag taxonomy for an asset. Tags drive search and gallery filtering downstream. ### Can I limit what my agent is allowed to do with the Cincopa REST API V2? Yes. Because you run Jentic One yourself, your own rules decide which Cincopa operations and credentials the agent may use, so you can grant only the calls the task needs. For example, you can allow gallery composition through /gallery.add_item.json and /gallery.set_master.json while withholding destructive operations like /gallery.delete.json, or permit uploads via /asset.upload_from_url.json without exposing token minting through /token.get_temp.json. Since Cincopa's write operations take the target asset or gallery id in the request body rather than the URL path, you scope access at the operation level to match exactly what you want the agent to run.