canonical: https://jentic.com/apis/coconut.co/coconut

# Coconut Video Encoding API

Jentic publishes the only available OpenAPI specification for Coconut Video Encoding API, keeping it validated and agent-ready. The API runs cloud video transcoding jobs that accept a source URL and a job specification, then output to formats including MP4, HLS, and DASH for adaptive streaming. After submission a job can be polled for status and inspected for output-level metadata such as duration, resolution, and codec. Coconut runs in three regions - North Virginia, Oregon, and Ireland - and authenticates with HTTP Basic where the API key is sent as the username.

## For AI agents

Submit cloud video transcoding jobs that output MP4, HLS, and DASH, then read back job status and per-output metadata.

## Scope

Does not host or stream video, manage CDN delivery, or run live (real-time) transcoding - use for batch on-demand video transcoding only.

## Capabilities

- Submit transcoding jobs that fan out to MP4, HLS, and DASH outputs via POST /jobs
- Poll the status of a transcoding job via GET `/jobs/{jobId}`
- Retrieve full job metadata - duration, resolution, codecs, output URLs - via GET `/metadata/jobs/{jobId}`
- Read metadata for a single output (for example one HLS rendition) via GET `/metadata/jobs/{jobId}/{outputKey}`
- Run jobs in North Virginia, Oregon, or Ireland by switching server URL

## Use cases

### On-Demand Video Library Encoding

Convert a creator-uploaded master video into web-ready MP4s plus an HLS ladder for adaptive playback on mobile and desktop. POST /jobs accepts the source URL and a job specification listing each output, GET `/jobs/{jobId}` reports progress, and GET `/metadata/jobs/{jobId}` returns the URLs and technical detail for every rendition once the job finishes. End-to-end integration takes well under a day.

Example prompt: Submit POST /jobs with an MP4 source and an HLS 1080p/720p/480p output spec, then poll GET `/jobs/{jobId}` until status is completed.

### DASH Streaming Output for Live VOD

Generate DASH segments and a manifest for a video-on-demand archive backed by a player that prefers DASH. The Coconut job spec accepts DASH outputs alongside MP4 and HLS, and GET `/metadata/jobs/{jobId}/{outputKey}` returns the per-output technical detail so the front-end can render quality switches and bitrate badges accurately.

Example prompt: Submit a DASH output spec via POST /jobs and then call GET `/metadata/jobs/{jobId}/dash_main` to read the resulting manifest details.

### Multi-Region Encoding for Latency-Sensitive Workloads

Route encoding jobs to the closest Coconut region - North Virginia, Oregon, or Ireland - to reduce upload time and stay within data residency boundaries. The base URL for each region is published in the spec, so a workflow that pulls source video from EU storage can submit the job to the Ireland endpoint and write outputs back into the same region.

Example prompt: Submit POST https://api-eu-west-1.coconut.co/v2/jobs with an EU-hosted source and EU-hosted output URL.

### AI Agent Video Workflows via Jentic

An AI assistant in a media operations workflow uses Jentic to submit encoding jobs without holding the Basic auth API key. The agent searches for 'transcode a video to HLS', loads the schema, and executes - Jentic injects the API key as the username component of the Basic header at execution time so the agent never sees the secret.

Example prompt: Use Jentic to search for 'transcode a video to HLS', load the POST /jobs schema, and submit a job for source URL https://example.com/master.mp4.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/jobs` | Submit a transcoding job |
| GET | `/jobs/{jobId}` | Get job status |
| GET | `/metadata/jobs/{jobId}` | Read full metadata for a job |
| GET | `/metadata/jobs/{jobId}/{outputKey}` | Read metadata for a single output |

## Key resources

- **Jobs** — Submit transcoding jobs and check their status
- **Metadata** — Read full job metadata or per-output metadata after a job completes

## Why Jentic

- **Setup:** Wiring Coconut by hand means encoding its Basic auth (the API key as the username with an empty password), choosing the right host among its default, us-west-2, and eu-west-1 endpoints, and handling retries while jobs run yourself. Through Jentic you install once, import the Coconut Video Encoding API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Coconut identifies each job by an id it returns rather than a resource you own, so scope the agent to the operations it needs, such as checking a job status or reading its metadata. You choose that set, so the job-creation operation is not included unless you add it.
- **Credential handling:** Your Coconut key is stored once, encrypted, by your own Jentic One instance and assembled into the Basic auth header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'transcode a video to HLS' or 'check an encoding job status', and Jentic returns the matching Coconut operation with its parameter schema so the agent builds a valid job spec without reading the docs.

## Related APIs

- **Mux Video** — Mux provides managed video encoding plus playback infrastructure with quality analytics.
- **api.video** — api.video is a managed encoding plus delivery platform with a hosted player.
- **Cloudinary** — Cloudinary handles image and video transformations with on-the-fly URL-based pipelines.
- **Vimeo** — Vimeo provides hosted video player and distribution for finished outputs.

## FAQ

### Why is there no official OpenAPI spec for Coconut Video Encoding API?

Coconut publishes prose documentation at docs.coconut.co but does not provide an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Coconut Video Encoding API 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 Coconut Video Encoding API use?

The API uses HTTP Basic authentication. Send the Coconut API key as the username and leave the password blank. Through Jentic the API key is stored encrypted in the vault and assembled into the Authorization header at execution time.

### Can I generate HLS and DASH outputs in a single Coconut job?

Yes. POST /jobs accepts a job specification that lists multiple outputs, including MP4, HLS, and DASH variants in the same submission. Each output is reported separately in the metadata so a front-end player can pick the right manifest at runtime.

### What are the rate limits for the Coconut Video Encoding API?

The OpenAPI spec does not declare numeric rate limits. Coconut applies plan-based concurrency caps on simultaneous jobs, so a high-volume pipeline should track in-flight job ids and throttle new POST /jobs calls until earlier jobs report status completed.

### How do I check whether a transcoding job has finished through Jentic?

Search Jentic for 'check Coconut job status', load the GET `/jobs/{jobId}` schema, and execute with the job id returned by POST /jobs. Install the SDK with pip install jentic and call it via the async client. The response includes status (pending, processing, completed, or failed) and the underlying error if the job failed.

### Can I run jobs in EU regions for data residency?

Yes. The spec lists three server URLs - https://api.coconut.co/v2 (North Virginia), https://api-us-west-2.coconut.co/v2 (Oregon), and https://api-eu-west-1.coconut.co/v2 (Ireland). Pick the EU base URL when source storage and output destinations are also in the EU.

### Can I limit what my agent is allowed to do with the Coconut Video Encoding API?

Yes. Because Jentic One is self-hosted, you decide which Coconut operations your agent may call, so you can grant read-only access to GET `/jobs/{jobId}` for job status and GET `/metadata/jobs/{jobId}` or GET `/metadata/jobs/{jobId}/{outputKey}` for output details while withholding POST /jobs so the agent cannot submit new transcoding jobs. Coconut identifies each job by the id it returns rather than a resource you own, so you scope the agent to exactly the operations it needs and add job creation only if you want it. The Basic auth API key stays with your own instance and is attached at execution time, so the agent never handles the credential directly.