Quickstart
Connect a test profile, publish a comment, and receive its events — in test mode, with no provider app.
This walks through Koil end to end in test mode: no provider app, no OAuth, no real account. You will connect a simulated YouTube channel, subscribe to events, and publish a comment through it. Every step below is also run by Koil's own test suite against test mode, so it stays accurate.
1. Get a test key
Create a test-mode API key in the admin console. It starts with koil_test_.
export KOIL_API_KEY=koil_test_...2. Pick a profile from a magic connection
Magic connections stand in for provider grants in test mode. test_conn_youtube_healthy is a healthy YouTube grant carrying every scope. List the channels it reaches:
curl "https://api.koil.co/v1/connections/test_conn_youtube_healthy/eligible-profiles" \ -H "Authorization: Bearer $KOIL_API_KEY"{ "data": [ { "providerId": "youtube", "providerProfileExternalId": "UCtest_yt_channel_1", "displayName": "Test YouTube Channel", "accountKind": "channel", "capabilities": [ "videos.comments.delete", "videos.comments.get", "videos.comments.list", "videos.comments.moderate", "videos.comments.publish", "videos.comments.update", "videos.items.delete", "videos.items.get", "videos.items.list", "videos.items.publish", "videos.items.update" ], "resourceRefs": { "youtubeChannelId": "UCtest_yt_channel_1", "youtubeUploadsPlaylistId": "UUtest_yt_channel_1" }, "metadata": { "youtubeChannelId": "UCtest_yt_channel_1", "youtubeUploadsPlaylistId": "UUtest_yt_channel_1", "handle": "@testyoutubechannel", "profileImageUrl": "https://fixture.invalid/test_yt_avatar.jpg", "subscriberCount": 0, "videoCount": 0, "madeForKids": false } } ]}3. Create a Connected Profile
Everything Koil does for a provider account goes through a Connected Profile. Create one from the channel:
curl -X POST "https://api.koil.co/v1/connected-profiles" \ -H "Authorization: Bearer $KOIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "providerId": "youtube", "connectionId": "test_conn_youtube_healthy", "providerProfileExternalId": "UCtest_yt_channel_1"}'Keep the connectedProfileId it returns (test_cp_…); the requests below show an example id where yours goes.
4. Subscribe to events
Point an Event Destination at an HTTPS endpoint you control — a request inspector is fine for trying this out — and subscribe it to publish lifecycle events:
curl -X POST "https://api.koil.co/v1/event-destinations" \ -H "Authorization: Bearer $KOIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "webhook", "topics": [ "publish_request.*" ], "config": { "url": "https://example.com/koil/events" }}'5. Publish a comment
Comments, replies, posts, and messages are all publish requests. This one comments on a video:
curl -X POST "https://api.koil.co/v1/publish-requests" \ -H "Authorization: Bearer $KOIL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "publishRequests": [ { "contentType": "youtube.videos.comments", "connectedProfileId": "test_cp_4T2cgH9gnSqEb9DrntKA", "args": { "target": { "contentType": "youtube.videos.items", "externalId": "test_video_1" }, "text": "Hello from Koil" } } ]}'Koil answers 202 Accepted with a publishRequestId (test_pub_…, used below in place of the example's), status: "created", and a statusUrl. As the publish runs, your endpoint receives its publish_request.* events, ending in publish_request.succeeded. You can also poll:
curl "https://api.koil.co/v1/publish-requests/test_pub_7GhQ2dLkP0aZ1xYc9VwN" \ -H "Authorization: Bearer $KOIL_API_KEY"Next
- Try
test_conn_youtube_expiredandtest_conn_youtube_missing_scopesto see how failures surface (Errors). - Verify webhook deliveries before trusting them.
- See everything a YouTube channel supports, and the
argsof every publish, on YouTube. - When your provider app is approved, register it and switch to a live key.