canonical: https://jentic.com/apis/apple.com/sirikit-cloud-media

# Apple SiriKit Cloud Media

Jentic publishes the only available OpenAPI specification for SiriKit Cloud Media, keeping it validated and agent-ready. SiriKit Cloud Media is the server-side contract that third-party music and podcast services implement so Siri can resolve and play their content on Apple devices without an installed app extension. The spec defines six endpoints that Apple invokes against a vendor-hosted cloud extension to add media to a user library, start playback, update affinities like likes or dislikes, and report queue activity. Vendors implement this surface; they do not call it.

## For AI agents

Server-side contract that media providers implement so Siri can resolve, play, and update affinity for their catalog content. Six endpoints invoked by Apple, not by the vendor.

## Scope

Does not handle catalog browsing, search, billing, or DRM - use for receiving Siri-resolved media intents and reporting queue activity only.

## Capabilities

- Add a media item to a user's library when Siri receives an 'add to my music' request
- Start playback of a track, album, or playlist resolved by a Siri voice intent
- Update affinity such as likes, dislikes, or rating against a media item
- Report queue activity back to Siri so it knows what is currently playing
- Expose a /configuration endpoint that describes the supported media types and capabilities
- Receive structured intent payloads from Siri including resolved content identifiers

## Use cases

### Voice-Activated Music Service Integration

A streaming music service stands up a SiriKit Cloud Media extension so users can say 'Hey Siri, play the new Phoebe Bridgers album on MyMusic' without opening an app. The vendor implements `/intent/playMedia` and `/intent/addMedia` so Siri can resolve catalog items and start playback. The /configuration endpoint advertises supported media types - songs, albums, playlists, podcasts.

Example prompt: Implement POST `/intent/playMedia` returning a successful response object for a track id supplied by Siri

### Podcast Affinity Sync

A podcast platform implements `/intent/updateMediaAffinity` so a user saying 'Hey Siri, like this episode' updates the listener's preferences server-side. The endpoint receives the resolved episode identifier from Siri and the affinity verb, and the vendor mirrors the action into its own user-state store. This keeps Siri-driven actions in sync with the user's in-app library.

Example prompt: Handle POST `/intent/updateMediaAffinity` with a payload setting affinity LIKE for episode id 8821 and persist the change to the user's profile

### Queue Activity Reporting

When Siri starts playback, the vendor reports the resulting queue back through `/queues/playMedia` and `/queues/updateActivity` so Siri can present consistent context - current track, position, and what is up next - across HomePod, AirPods, and CarPlay. This keeps follow-up commands like 'skip this' or 'what's playing' grounded in the real queue state.

Example prompt: Send POST `/queues/updateActivity` with the current track id, queue position 3 of 12, and elapsed time 47 seconds

### AI Agent Cloud Extension Scaffolding

An AI agent uses Jentic to scaffold a SiriKit Cloud Media extension server for a media startup, generating handlers for all six endpoints from the validated OpenAPI schema. Because Apple does not publish a public spec, the Jentic-generated version is the only structured source available for code generation and testing.

Example prompt: Generate Python FastAPI handler stubs for /configuration, `/intent/addMedia`, `/intent/playMedia`, `/intent/updateMediaAffinity`, `/queues/playMedia`, and `/queues/updateActivity`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/configuration` | Return supported media types and extension capabilities |
| POST | `/intent/addMedia` | Add a resolved item to the user's library |
| POST | `/intent/playMedia` | Start playback of a resolved media item |
| POST | `/intent/updateMediaAffinity` | Update like, dislike, or rating for a media item |
| POST | `/queues/playMedia` | Report a new playback queue to Siri |
| POST | `/queues/updateActivity` | Update queue position and current playback activity |

## Key resources

- **configuration** — Advertise the media types and capabilities the cloud extension supports
- **intent** — Receive resolved Siri intents for adding, playing, and updating media affinity
- **queues** — Report and update the active playback queue back to Siri

## Why Jentic

- **Setup:** Wiring a SiriKit Cloud Media extension by hand means implementing the receiver contract for Siri-resolved media intents and queue reporting against Apple's prose spec yourself. Through Jentic you install once, import the SiriKit Cloud Media contract from the API Directory, store any shared test secret once, and your agent calls it.
- **Permission scoping:** This contract exposes a fixed set of intent and queue operations that carry their targets in the request body, so you limit the agent to the operations it needs, such as playMedia or addMedia. You choose the operations it may call, so queue or affinity updates are not included unless you add them.
- **Credential handling:** Any shared test or staging secret used during contract testing 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 'play media on Siri', and Jentic returns the matching SiriKit intent operation with its request and response schema so the agent scaffolds a compliant extension without reading Apple's prose docs.

## Related APIs

- **Spotify Web API** — Source-of-truth catalog API for resolving tracks and queues that a SiriKit extension then plays
- **SoundCloud API** — Audio catalog API often paired with a Siri extension for music and podcast playback
- **YouTube Data API** — Different ecosystem (Google Assistant via Actions) for routing voice media intents

## FAQ

### Why is there no official OpenAPI spec for SiriKit Cloud Media?

Apple does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call SiriKit Cloud Media 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 SiriKit Cloud Media use?

The SiriKit Cloud Media spec does not declare a standard securityScheme - Apple authenticates the calling Siri service against the vendor-supplied extension URL using a relationship registered in the developer portal. Implementers typically validate the request signature and pin the source IP at the edge.

### Who calls the SiriKit Cloud Media endpoints?

Apple's Siri service calls them. The vendor (the music or podcast provider) implements the six endpoints; they do not consume them. The OpenAPI spec is therefore most useful for scaffolding an extension server, generating handler stubs, and writing contract tests against the expected request and response shapes.

### What media types does the cloud extension support?

The /configuration endpoint declares supported media types - typically song, album, playlist, station, audiobook, and podcast - and the affinity verbs the vendor honours. Siri uses the response to filter which voice intents it routes to your extension.

### How do I scaffold a SiriKit Cloud Media server through Jentic?

Run pip install jentic, search 'sirikit cloud media playMedia', and load the operation to retrieve the request and response schemas. Use those schemas to generate handler stubs in any framework - FastAPI, Express, or Spring - and validate incoming Siri payloads against them.

### Are the six endpoints stable across iOS releases?

The shape has been stable since the public SiriKit Cloud Media introduction. Apple iterates on supported media types and affinity verbs through the /configuration response, not by adding new endpoints. Treat the six paths as a fixed contract and feature-flag through configuration.

### Can I limit what my agent is allowed to do with the SiriKit Cloud Media API?

Yes. Because you run Jentic One yourself, your own rules decide which of the fixed intent and queue operations your agent may call, so you can allow only what a task needs, such as addMedia or playMedia. Since each operation carries its target in the request body, you can keep affinity or queue-reporting calls like updateMediaAffinity or queues/updateActivity out of scope unless you deliberately add them. Any shared test or staging secret is held encrypted by your own instance and injected at execution time, so it never reaches the agent's prompt or logs.