canonical: https://jentic.com/apis/castmagic.io/castmagic

# Castmagic API

Jentic publishes the only available OpenAPI specification for Castmagic API, keeping it validated and agent-ready. Castmagic is a content processing platform that ingests audio and video files and produces transcripts, show notes, social posts, and other derived assets organised into workspaces called Spaces. The Zapier-style API surface lets you list available Spaces, create a new media object from a source URL, subscribe and unsubscribe webhooks for processing events, and validate that an API key is active. It is intended for piping podcast and video content into Castmagic from external recording, scheduling, or storage tools.

## For AI agents

Submit audio or video files to Castmagic for transcription and content generation, list workspaces, and manage webhook subscriptions for processing events.

## Scope

Does not handle transcript retrieval, asset editing, or billing - use for submitting media objects and managing webhook subscriptions on Castmagic only.

## Capabilities

- Validate that a Castmagic API key is active before triggering downstream calls
- List the Spaces available on a Castmagic account for routing new media
- Create a Castmagic media object from an audio or video URL to start processing
- Subscribe a webhook URL to receive notifications when Castmagic processing completes
- Unsubscribe a previously registered Castmagic webhook

## Use cases

### Automated podcast post-production

Once a podcast episode is recorded and uploaded to cloud storage, an automation can POST the file URL to Castmagic /objects to start transcription, show note generation, and clip suggestions. The webhook subscription lets the automation know when the assets are ready to be pulled into a publishing tool.

Example prompt: POST to /objects with the audio file URL and the target space_id, then POST /hooks/subscribe with the callback URL that should receive the completion event.

### Video content repurposing pipeline

A creator uploading a long-form video can have it forwarded to Castmagic as a media object so Castmagic produces transcript, summary, and social caption assets. The same /objects call can route output into a per-client Space, which keeps assets separated for agency workflows.

Example prompt: POST /objects with the video URL and the client-specific space_id obtained from GET /spaces.

### Webhook-driven content publishing

Editorial systems can register a webhook with POST /hooks/subscribe so Castmagic notifies them as soon as transcripts and derivative assets are ready, rather than polling. When a project ends, DELETE /hooks/unsubscribe removes the subscription cleanly.

Example prompt: POST /hooks/subscribe with target_url=https://example.com/castmagic-callback and event='object.completed'.

### AI agent media workflow via Jentic

An AI content agent can collect new audio recordings, push them to Castmagic, and pull back the structured assets without the developer hand-coding the Zapier-style endpoint contract. Jentic stores the bearer API key in the vault and injects it at execution time.

Example prompt: Search Jentic for 'submit an audio file to Castmagic', load POST /objects, and execute it with the user's audio URL and chosen Space.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /validate | Validate the supplied API key |
| GET | /spaces | List available Spaces on the account |
| POST | /objects | Create a media object from an audio or video URL |
| POST | /hooks/subscribe | Subscribe a webhook to processing events |
| DELETE | /hooks/unsubscribe | Remove a webhook subscription |

## Key resources

- **Spaces** — Workspaces inside Castmagic that group related media objects.
- **Objects** — Media objects representing an audio or video file submitted for processing.
- **Hooks** — Webhook subscriptions used to deliver Castmagic processing events.

## Why Jentic

- **Setup:** Wiring the Castmagic API by hand means sending your key as a bearer token on every call and working against the Zapier-style routes on the app.castmagic.io host yourself. Through Jentic you install once, import the Castmagic API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Castmagic takes the media object and hook details in the request body, not the URL path, so you scope by operation: limit the agent to the ones it needs, such as validating the key, listing spaces, and submitting an object, and leave webhook subscribe and unsubscribe out of the allowed set until you want them.
- **Credential handling:** Your Castmagic API key is stored once, encrypted, by your own Jentic One instance and injected as the bearer token at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit an audio file to Castmagic', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AssemblyAI API** — AssemblyAI focuses on raw transcription and audio intelligence rather than full content repurposing.
- **Deepgram API** — Deepgram is a streaming-first transcription provider competing on latency and accuracy.
- **Rev AI API** — Rev AI is a transcription-only competitor without Castmagic's content generation steps.

## FAQ

### Why is there no official OpenAPI spec for Castmagic API?

Castmagic publishes a Zapier-targeted API but no machine-readable OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Castmagic 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 Castmagic API use?

The Castmagic API uses HTTP bearer token authentication. You generate the API key in the Castmagic dashboard and pass it as Authorization: Bearer in every request. Through Jentic the key is held encrypted in your Jentic One instance and never exposed to the agent.

### How do I submit an audio file to Castmagic for processing?

POST a JSON body to /objects containing the source audio or video URL and the target space_id. Castmagic ingests the file asynchronously, and you can register a webhook with POST /hooks/subscribe to be notified when transcription and derivative assets are ready.

### What are the rate limits for the Castmagic API?

Castmagic does not document explicit numeric rate limits in this OpenAPI spec; the Zapier-style endpoints are designed for moderate trigger volume. Avoid tight polling against /spaces or /validate, and prefer webhook subscriptions over polling for completion events.

### How do I create a Castmagic media object through Jentic?

Run pip install jentic, search Jentic with the query 'submit an audio file to Castmagic', load the POST /objects schema, and execute it with the file URL and a space_id obtained from GET /spaces. Jentic handles the bearer key automatically.

### Can I retrieve the generated transcript directly from this API?

No. The current spec covers media submission and webhook management but not transcript retrieval, which happens through the Castmagic web UI or via the webhook payload that fires when processing completes. Use POST /hooks/subscribe to receive the asset URLs.

### Can I limit what my agent is allowed to do with the Castmagic API?

Yes. Because you run Jentic One yourself, your own rules decide which Castmagic operations and credentials the agent may use. Castmagic scopes by operation rather than URL path, so you can allow only what the agent needs, such as validating the key, listing Spaces with GET /spaces, and submitting a media object with POST /objects. You can leave the webhook operations POST /hooks/subscribe and DELETE /hooks/unsubscribe out of the allowed set until you decide the agent should manage subscriptions.