Publish content

Use Publish Requests to create provider content through a Connected Profile. Koil validates the request, runs the provider operation, and gives you one status to track.

Start here after you have a connectedProfileId from Connect provider accounts.

How it works

1. Check what the Connected Profile can publish. GET /v1/connected-profiles/{connectedProfileId}/capabilities

2. Choose a supported contentType and, when required, a variant.

3. Upload or stage media if the publish schema requires it. POST /v1/media

4. Submit one or more publish items. POST /v1/publish-requests

5. Store each returned publish request ID and status URL.

6. Read status until the request is completed, failed, or canceled. GET /v1/publish-requests/{publishRequestId}

For scheduled work, update or cancel before it runs. PATCH /v1/publish-requests/{publishRequestId} POST /v1/publish-requests/{publishRequestId}/cancel

Example

{
  "publishRequests": [
    {
      "contentType": "instagram.media.items",
      "variant": "feed",
      "connectedProfileId": "cp_123",
      "groupId": "campaign-42",
      "clientItemId": "draft-1",
      "args": {
        "text": "Hello world",
        "media": [{ "mediaId": "media_123", "altText": "A cat" }],
        "scheduling": { "at": "2026-05-01T10:00:00Z" }
      }
    }
  ]
}

Koil validates contentType, variant, and args before anything is sent to the provider. If one item in a batch is invalid, the batch is rejected.

Media Inputs

Use mediaId for images, videos, and other assets whenever possible. Koil can stage, validate, and reuse the media before the provider request runs.

Some publish schemas also accept sourceUrl. Use HTTPS URLs only.

Batches and retries

POST /v1/publish-requests accepts up to 100 items or a 1 MB body, whichever is lower. Koil validates the request first, then runs accepted items independently.

Use groupId to connect related items, such as a campaign. Use clientItemId to map each Koil item back to a draft or record in your system.

Send an Idempotency-Key header when submitting publish requests. Koil requires it and dedupes the whole submit operation:

• Reusing the same key and payload returns the same accepted result after the first submission resolves.
• Reusing the same key with a different payload returns 409 conflict.
• To retry failed items, submit only those items with a new idempotency key.

What not to send

Use Koil fields in args. Do not send raw provider payloads or provider OAuth credentials.