API overview
How the Koil API is shaped — resources, ids, content addressing — and where each part is documented.
The Koil API is a REST API at https://api.koil.co, versioned under /v1. Requests and responses are JSON, every request is authenticated with an API key, and asynchronous changes are delivered as signed events rather than polled.
Every endpoint, with its parameters, request and response schemas, and samples, is in the generated API endpoints reference; the OpenAPI document it is built from is the contract to generate clients from. This page covers the model the endpoints share.
Principles
- Versioned. Everything is under
/v1; changes within a version are additive. - Connected Profile-scoped. Provider work names the
connectedProfileIdit acts through, never a raw token or provider account id. - Safe to retry. Writes that start work take an
Idempotency-Key. - Events first. Publishes, uploads, connections, and provider content report their outcomes as events.
- Nothing kept that need not be. Provider content is delivered and discarded, held no longer than 24 hours; see Data and storage.
- One contract in two modes. Test-mode keys use the same endpoints, schemas, and events against simulated providers.
Resources
| Resource | Id | What it is |
|---|---|---|
| Auth Integration | int_… | Your own provider OAuth app, registered with Koil. See Bring your own provider app. |
| Connect Session | cs_… | A short-lived hosted authorization flow; its authorizationUrl sends your end user to the provider's consent screen. |
| Connection | conn_… | One end user's provider grant, created by a Connect Session or imported. Koil holds and refreshes the credential. |
| Connected Profile | cp_… | One provider account, Page, channel, or number reachable through one Connection — what provider operations act through. |
| Publish request | pub_… | One item of content Koil creates on a provider: a post, comment, reply, or message, now or scheduled. |
| Backfill request | bf_… | One re-delivery of a content type's history for a profile. See Backfill history. |
| Media | med_… | An image or video staged for publishing. |
| Event Destination | opaque | Where events are delivered and which topics it receives. |
Test-mode ids carry a test_ prefix before these (test_cp_…). Provider-owned ids — a post's, a comment's, an account's — stay as the provider defines them and appear as externalId.
Content types
Provider content is addressed by content type, {provider}.{surface}.{resource} — instagram.media.comments, youtube.videos.items. The same name is the path of content reads, the contentType of a publish request, and the middle of every content event topic. Providers lists every content type and what it supports.
| To | Call | Stored by Koil |
|---|---|---|
| Read provider content | GET /v1/content/{contentType}?connectedProfileId=… and GET /v1/content/{contentType}/{externalId}?connectedProfileId=… | Nothing |
| Moderate content | POST /v1/content/{contentType}/{externalId}/moderate | Nothing |
| Delete content | DELETE /v1/content/{contentType}/{externalId}?connectedProfileId=…, where supported | Nothing |
| Create content | POST /v1/publish-requests with contentType | The ledger entry only |
| Receive content | content.{contentType}.{action} events | Nothing |
Replies, comments, reposts, and messages are publish requests too — a variant or a target field, not a separate endpoint. See Publish content and Reply to content.
Reading content
Content reads go to the provider every time; in test mode they return deterministic fixtures through the same schemas. A read returns the content type's own schema — the same shape its events carry as data — so a live read and an event about the same item are interchangeable. There is no cross-content-type aggregate: to build a unified inbox or timeline, persist the events you receive.
Add includeProviderRaw=true to a read to receive the provider's own payload as providerRaw beside Koil's fields. It is opaque, provider-defined, and never stored by Koil; events do not carry it.
Moderating and deleting
moderate acts on existing provider content, whether Koil published it or only observed it; each content type's moderation input (hide, reject, ban…) is on its provider page. As on every content route, connectedProfileId goes in the query string; the body carries the moderation. The call's response is its outcome, and a failure is its error. Moderation done on the provider itself — a comment hidden in the provider's own app — arrives as content.{contentType}.moderated on content types that observe it.
Media
Publish inputs reference media by mediaId or by sourceUrl. Prefer mediaId: create it with POST /v1/media (from an HTTPS sourceUrl Koil fetches, or as a direct upload to the pre-signed URL the response returns), and Koil validates and stages the file before any publish runs. A sourceUrl given directly in a publish must be HTTPS; Koil creates the media from it when the request is submitted.
Billing
GET /v1/billing/account reports the Organization's plan, the free plan's hard caps (null on paid plans), and the live Connected Profile count the platform fee is billed on. Invoices and payment methods are in the billing portal, reachable from the admin console.