{ "openapi": "3.1.0", "info": { "title": "Koil API", "version": "0.1.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "additionalProperties": false, "title": "Error", "type": "object", "properties": { "error": { "additionalProperties": false, "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "unauthorized", "invalid_token", "quota_exceeded", "scope_insufficient", "not_found", "conflict", "rate_limit_exceeded", "platform_rate_limit", "internal", "not_supported", "service_unavailable" ], "description": "Stable error code. `validation_error` (400), `unauthorized` (401), `invalid_token` (401), `quota_exceeded` (402), `scope_insufficient` (403), `not_found` (404), `conflict` (409), `rate_limit_exceeded` (429), `platform_rate_limit` (429), `internal` (500), `not_supported` (501), `service_unavailable` (503)." }, "message": { "description": "Human-readable summary.", "type": "string" }, "meta": { "description": "Structured detail. A `validation_error` carries `validationErrors` (each with a `field`); one from the input schema or an admission check also carries `violations` (each with a `code` and a JSON-pointer `path`).", "type": "object", "additionalProperties": {} } }, "required": [ "code", "message", "meta" ] } }, "required": [ "error" ] } } }, "paths": { "/v1/content/instagram.media.items": { "get": { "operationId": "instagram.media.items.list", "summary": "List Instagram profile media items", "tags": [ "Content: instagram" ], "description": "List Instagram profile media items.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "feed" ] }, { "type": "string", "enum": [ "reel" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.media.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.media.items/{externalId}": { "get": { "operationId": "instagram.media.items.get", "summary": "Get one Instagram media item by provider id", "tags": [ "Content: instagram" ], "description": "Get one Instagram media item by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "feed" ] }, { "type": "string", "enum": [ "reel" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.media.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.media.comments": { "get": { "operationId": "instagram.media.comments.list", "summary": "List Instagram comments on one media item", "tags": [ "Content: instagram" ], "description": "List Instagram comments on one media item.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.media.comments" ] } }, "required": [ "externalId", "mediaExternalId", "text", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.media.comments/{externalId}": { "get": { "operationId": "instagram.media.comments.get", "summary": "Get one Instagram media comment by provider id", "tags": [ "Content: instagram" ], "description": "Get one Instagram media comment by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.media.comments" ] } }, "required": [ "externalId", "mediaExternalId", "text", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.media.comments/{externalId}/moderate": { "post": { "operationId": "instagram.media.comments.moderate", "summary": "Hide or unhide an Instagram media comment", "tags": [ "Content: instagram" ], "description": "Hide or unhide an Instagram media comment.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "hidden": { "type": "boolean" } }, "required": [ "hidden" ] } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "hidden": { "type": "boolean" }, "success": { "type": "boolean" } }, "required": [ "externalId", "hidden", "success" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.stories.items": { "get": { "operationId": "instagram.stories.items.list", "summary": "List the Instagram profile's live stories", "tags": [ "Content: instagram" ], "description": "List the Instagram profile's live stories.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.stories.items" ] } }, "required": [ "externalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.stories.items/{externalId}": { "get": { "operationId": "instagram.stories.items.get", "summary": "Get one Instagram story by provider id", "tags": [ "Content: instagram" ], "description": "Get one Instagram story by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.stories.items" ] } }, "required": [ "externalId", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.dm.threads": { "get": { "operationId": "instagram.dm.threads.list", "summary": "List Instagram DM threads", "tags": [ "Content: instagram" ], "description": "List Instagram DM threads.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "participantExternalIds": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.dm.threads" ] } }, "required": [ "externalId", "participantExternalIds", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/instagram.dm.messages": { "get": { "operationId": "instagram.dm.messages.list", "summary": "List Instagram DM messages in one thread", "tags": [ "Content: instagram" ], "description": "List Instagram DM messages in one thread.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "threadExternalId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "threadExternalId": { "minLength": 1, "description": "Owning conversation id. Present on messages read through instagram.dm.threads; absent on webhook-observed messages because the provider's messaging webhooks do not identify the conversation.", "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "instagram.dm.messages" ] } }, "required": [ "externalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.media.items": { "get": { "operationId": "facebook.media.items.list", "summary": "List published Facebook Page posts", "tags": [ "Content: facebook" ], "description": "List published Facebook Page posts.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "feed" ] }, { "type": "string", "enum": [ "reel" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.media.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.media.items/{externalId}": { "get": { "operationId": "facebook.media.items.get", "summary": "Get one Facebook Page post by provider id", "tags": [ "Content: facebook" ], "description": "Get one Facebook Page post by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "feed" ] }, { "type": "string", "enum": [ "reel" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.media.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.media.comments": { "get": { "operationId": "facebook.media.comments.list", "summary": "List comments on one Facebook Page post, replies included", "tags": [ "Content: facebook" ], "description": "List comments on one Facebook Page post, replies included.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "hidden": { "type": "boolean" }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.media.comments" ] } }, "required": [ "externalId", "mediaExternalId", "text", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.media.comments/{externalId}": { "get": { "operationId": "facebook.media.comments.get", "summary": "Get one Facebook Page comment by provider id", "tags": [ "Content: facebook" ], "description": "Get one Facebook Page comment by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "hidden": { "type": "boolean" }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.media.comments" ] } }, "required": [ "externalId", "mediaExternalId", "text", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "facebook.media.comments.delete", "summary": "Delete a comment on a Facebook Page post", "tags": [ "Content: facebook" ], "description": "Delete a comment on a Facebook Page post.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.media.comments/{externalId}/moderate": { "post": { "operationId": "facebook.media.comments.moderate", "summary": "Hide or unhide a comment on a Facebook Page post", "tags": [ "Content: facebook" ], "description": "Hide or unhide a comment on a Facebook Page post.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "hidden": { "type": "boolean" } }, "required": [ "hidden" ] } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "hidden": { "type": "boolean" }, "success": { "type": "boolean" } }, "required": [ "externalId", "hidden", "success" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.stories.items": { "get": { "operationId": "facebook.stories.items.list", "summary": "List the Page's stories", "tags": [ "Content: facebook" ], "description": "List the Page's stories.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "photo" ] }, { "type": "string", "enum": [ "video" ] } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "archived" ] } ] }, "mediaExternalId": { "minLength": 1, "description": "Meta's id for the story's photo or video.", "type": "string" }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.stories.items" ] } }, "required": [ "externalId", "variant", "status", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.dm.threads": { "get": { "operationId": "facebook.dm.threads.list", "summary": "List the Page's Messenger threads", "tags": [ "Content: facebook" ], "description": "List the Page's Messenger threads.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "participantExternalIds": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.dm.threads" ] } }, "required": [ "externalId", "participantExternalIds", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.dm.threads/{externalId}": { "get": { "operationId": "facebook.dm.threads.get", "summary": "Get one Messenger thread by provider id", "tags": [ "Content: facebook" ], "description": "Get one Messenger thread by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "participantExternalIds": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.dm.threads" ] } }, "required": [ "externalId", "participantExternalIds", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/facebook.dm.messages": { "get": { "operationId": "facebook.dm.messages.list", "summary": "List Messenger messages in one thread", "tags": [ "Content: facebook" ], "description": "List Messenger messages in one thread.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "threadExternalId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "threadExternalId": { "minLength": 1, "description": "Owning conversation id. Present on messages read through facebook.dm.threads; absent on webhook-observed messages because Messenger webhooks do not identify the conversation.", "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "facebook.dm.messages" ] } }, "required": [ "externalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.items": { "get": { "operationId": "tiktok.posts.items.list", "summary": "List the TikTok account's public posts, newest first", "tags": [ "Content: tiktok" ], "description": "List the TikTok account's public posts, newest first.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "photo" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "embedUrl": { "minLength": 1, "type": "string" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "durationSeconds": { "minimum": 0, "type": "number" }, "isAd": { "type": "boolean" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.items/{externalId}": { "get": { "operationId": "tiktok.posts.items.get", "summary": "Get one TikTok post by provider id", "tags": [ "Content: tiktok" ], "description": "Get one TikTok post by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "photo" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "embedUrl": { "minLength": 1, "type": "string" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "durationSeconds": { "minimum": 0, "type": "number" }, "isAd": { "type": "boolean" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.items" ] } }, "required": [ "externalId", "variant", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.comments": { "get": { "operationId": "tiktok.posts.comments.list", "summary": "List comments on one TikTok post, or the replies to one of its comments", "tags": [ "Content: tiktok" ], "description": "List comments on one TikTok post, or the replies to one of its comments.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "parentExternalId", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeReplies", "required": false, "description": "Include up to three replies inline under each top-level comment." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC" ] }, { "type": "string", "enum": [ "ALL" ] } ] }, "in": "query", "name": "status", "required": false, "description": "Visibility filter; defaults to ALL (hidden included)." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "likes" ] }, { "type": "string", "enum": [ "replies" ] }, { "type": "string", "enum": [ "create_time" ] } ] }, "in": "query", "name": "sort", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "hidden": { "type": "boolean" }, "pinned": { "type": "boolean" }, "liked": { "type": "boolean" }, "ownerAuthored": { "type": "boolean" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.comments" ] } }, "required": [ "externalId", "mediaExternalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.comments/{externalId}": { "get": { "operationId": "tiktok.posts.comments.get", "summary": "Get one TikTok comment by provider id", "tags": [ "Content: tiktok" ], "description": "Get one TikTok comment by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "hidden": { "type": "boolean" }, "pinned": { "type": "boolean" }, "liked": { "type": "boolean" }, "ownerAuthored": { "type": "boolean" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.comments" ] } }, "required": [ "externalId", "mediaExternalId", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "tiktok.posts.comments.delete", "summary": "Delete a TikTok comment the account made", "tags": [ "Content: tiktok" ], "description": "Delete a TikTok comment the account made.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.comments/{externalId}/moderate": { "post": { "operationId": "tiktok.posts.comments.moderate", "summary": "Hide, unhide, like, or unlike a TikTok comment", "tags": [ "Content: tiktok" ], "description": "Hide, unhide, like, or unlike a TikTok comment.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "mediaExternalId": { "minLength": 1, "description": "The post the comment is on. Required for hide and unhide; ignored by like and unlike, which TikTok addresses by comment id alone.", "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "hide" ] }, { "type": "string", "enum": [ "unhide" ] }, { "type": "string", "enum": [ "like" ] }, { "type": "string", "enum": [ "unlike" ] } ] } }, "required": [ "action" ] } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "action": { "anyOf": [ { "type": "string", "enum": [ "hide" ] }, { "type": "string", "enum": [ "unhide" ] }, { "type": "string", "enum": [ "like" ] }, { "type": "string", "enum": [ "unlike" ] } ] }, "success": { "type": "boolean" } }, "required": [ "externalId", "action", "success" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.mentions": { "get": { "operationId": "tiktok.posts.mentions.list", "summary": "List the top mentions of the TikTok account in other users' captions or comments", "tags": [ "Content: tiktok" ], "description": "List the top mentions of the TikTok account in other users' captions or comments.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "caption" ] }, { "type": "string", "enum": [ "comment" ] } ] }, "in": "query", "name": "variant", "required": true }, { "schema": { "minimum": 1, "maximum": 90, "type": "integer" }, "in": "query", "name": "days", "required": false, "description": "Look-back window in days; defaults to 90." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "caption" ] }, { "type": "string", "enum": [ "comment" ] } ] }, "mediaExternalId": { "minLength": 1, "type": "string" }, "commentExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.mentions" ] } }, "required": [ "externalId", "variant", "mediaExternalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.posts.mentions/{externalId}": { "get": { "operationId": "tiktok.posts.mentions.get", "summary": "Get one mention in full, hydrating a mention event", "tags": [ "Content: tiktok" ], "description": "Get one mention in full, hydrating a mention event: TikTok's webhook payload carries no engagement counts or thumbnail, and no comment text or author handle for a comment mention. Details stay readable for 48 hours after the webhook.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "caption" ] }, { "type": "string", "enum": [ "comment" ] } ] }, "in": "query", "name": "variant", "required": true }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "caption" ] }, { "type": "string", "enum": [ "comment" ] } ] }, "mediaExternalId": { "minLength": 1, "type": "string" }, "commentExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" }, "shares": { "minimum": 0, "description": "Times the content was shared or reposted.", "type": "number" }, "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.posts.mentions" ] } }, "required": [ "externalId", "variant", "mediaExternalId", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.dm.threads": { "get": { "operationId": "tiktok.dm.threads.list", "summary": "List the TikTok Business Account's direct-message conversations from the last 90 days", "tags": [ "Content: tiktok" ], "description": "List the TikTok Business Account's direct-message conversations from the last 90 days.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "stranger" ] }, { "type": "string", "enum": [ "single" ] } ] }, "in": "query", "name": "variant", "required": true, "description": "stranger: message requests the account has not replied to; single: conversations it has replied in." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "variant": { "anyOf": [ { "type": "string", "enum": [ "stranger" ] }, { "type": "string", "enum": [ "single" ] } ] }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "referral": { "additionalProperties": false, "type": "object", "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "ad" ] }, { "type": "string", "enum": [ "shortLink" ] } ] }, "ads": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "advertiserId": { "minLength": 1, "type": "string" }, "adId": { "minLength": 1, "type": "string" }, "adName": { "minLength": 1, "type": "string" }, "embedUrl": { "minLength": 1, "type": "string" }, "materialId": { "minLength": 1, "type": "string" }, "referredAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" } } } }, "shortLinks": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "ref": { "minLength": 1, "type": "string" }, "prefilledMessage": { "minLength": 1, "type": "string" }, "prefilledMessageAuditStatus": { "anyOf": [ { "type": "string", "enum": [ "PASS" ] }, { "type": "string", "enum": [ "REJECT" ] } ] } } } } } }, "lastReadAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.dm.threads" ] } }, "required": [ "externalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/tiktok.dm.messages": { "get": { "operationId": "tiktok.dm.messages.list", "summary": "List the 20 most recent messages of one TikTok direct-message conversation", "tags": [ "Content: tiktok" ], "description": "List the 20 most recent messages of one TikTok direct-message conversation.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "threadExternalId", "required": true }, { "schema": { "type": "boolean" }, "in": "query", "name": "resolveMedia", "required": false, "description": "Resolve inbound images and videos to a fetchable URL, one extra call per attachment. The URL TikTok mints lasts 24 hours, so ask for it when the media is about to be shown." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "threadExternalId": { "minLength": 1, "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "sharePost" ] }, { "type": "string", "enum": [ "emoji" ] }, { "type": "string", "enum": [ "sticker" ] }, { "type": "string", "enum": [ "template" ] }, { "type": "string", "enum": [ "other" ] } ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "recipient": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "attachments": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "kind": { "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "sharePost" ] }, { "type": "string", "enum": [ "emoji" ] }, { "type": "string", "enum": [ "sticker" ] }, { "type": "string", "enum": [ "template" ] }, { "type": "string", "enum": [ "other" ] } ] }, "externalId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" } }, "required": [ "kind" ] } }, "source": { "minLength": 1, "type": "string" }, "autoMessageType": { "anyOf": [ { "type": "string", "enum": [ "welcomeMessage" ] }, { "type": "string", "enum": [ "suggestedQuestion" ] }, { "type": "string", "enum": [ "autoReply" ] } ] }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "tiktok.dm.messages" ] } }, "required": [ "externalId", "threadExternalId", "kind", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/youtube.videos.items": { "get": { "operationId": "youtube.videos.items.list", "summary": "List the channel's videos and Shorts, newest first", "tags": [ "Content: youtube" ], "description": "List the channel's videos and Shorts, newest first.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "title": { "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "tags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "privacyStatus": { "description": "Who can see the video.", "anyOf": [ { "type": "string", "enum": [ "public" ] }, { "type": "string", "enum": [ "private" ] }, { "type": "string", "enum": [ "unlisted" ] } ] }, "aspectRatio": { "exclusiveMinimum": 0, "type": "number" }, "uploadStatus": { "minLength": 1, "type": "string" }, "liveBroadcast": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "live" ] }, { "type": "string", "enum": [ "upcoming" ] } ] }, "madeForKids": { "type": "boolean" }, "durationSeconds": { "minimum": 0, "type": "number" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" }, "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "scheduledPublishAt": { "format": "date-time", "description": "When a private video is scheduled to go public.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "youtube.videos.items" ] } }, "required": [ "externalId", "title", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/youtube.videos.items/{externalId}": { "get": { "operationId": "youtube.videos.items.get", "summary": "Get one YouTube video by provider id", "tags": [ "Content: youtube" ], "description": "Get one YouTube video by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "title": { "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "tags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "privacyStatus": { "description": "Who can see the video.", "anyOf": [ { "type": "string", "enum": [ "public" ] }, { "type": "string", "enum": [ "private" ] }, { "type": "string", "enum": [ "unlisted" ] } ] }, "aspectRatio": { "exclusiveMinimum": 0, "type": "number" }, "uploadStatus": { "minLength": 1, "type": "string" }, "liveBroadcast": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "live" ] }, { "type": "string", "enum": [ "upcoming" ] } ] }, "madeForKids": { "type": "boolean" }, "durationSeconds": { "minimum": 0, "type": "number" }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" }, "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "scheduledPublishAt": { "format": "date-time", "description": "When a private video is scheduled to go public.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "youtube.videos.items" ] } }, "required": [ "externalId", "title", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "youtube.videos.items.delete", "summary": "Delete one of the channel's videos", "tags": [ "Content: youtube" ], "description": "Delete one of the channel's videos.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/youtube.videos.comments": { "get": { "operationId": "youtube.videos.comments.list", "summary": "List comments across the channel's videos (newest thread first, replies inline), one video's comments, or the replies to one comment", "tags": [ "Content: youtube" ], "description": "List comments across the channel's videos (newest thread first, replies inline), one video's comments, or the replies to one comment.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": false, "description": "Only this video's comments; every video of the channel otherwise." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "parentExternalId", "required": false, "description": "The replies to this top-level comment instead of the threads." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "heldForReview" ] }, { "type": "string", "enum": [ "likelySpam" ] } ] }, "in": "query", "name": "moderationStatus", "required": false, "description": "Which of YouTube's queues to read; defaults to published. Ignored with parentExternalId." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "searchTerms", "required": false, "description": "Only threads containing these terms. Ignored with parentExternalId." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "authorProfileImageUrl": { "minLength": 1, "type": "string" }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "moderationStatus": { "description": "YouTube's moderation state of a comment.", "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "heldForReview" ] }, { "type": "string", "enum": [ "likelySpam" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" }, "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "youtube.videos.comments" ] } }, "required": [ "externalId", "mediaExternalId", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/youtube.videos.comments/{externalId}": { "get": { "operationId": "youtube.videos.comments.get", "summary": "Get one YouTube comment by provider id", "tags": [ "Content: youtube" ], "description": "Get one YouTube comment by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "authorProfileImageUrl": { "minLength": 1, "type": "string" }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "moderationStatus": { "description": "YouTube's moderation state of a comment.", "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "heldForReview" ] }, { "type": "string", "enum": [ "likelySpam" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "views": { "minimum": 0, "description": "Times the content was viewed.", "type": "number" }, "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "providerPermalink": { "format": "uri", "description": "Canonical provider URL for content.", "minLength": 1, "pattern": "^https?://", "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "youtube.videos.comments" ] } }, "required": [ "externalId", "mediaExternalId", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "youtube.videos.comments.delete", "summary": "Delete a comment on one of the channel's videos", "tags": [ "Content: youtube" ], "description": "Delete a comment on one of the channel's videos.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/youtube.videos.comments/{externalId}/moderate": { "post": { "operationId": "youtube.videos.comments.moderate", "summary": "Publish, hold for review, or reject a comment on one of the channel's videos, optionally banning its author", "tags": [ "Content: youtube" ], "description": "Publish, hold for review, or reject a comment on one of the channel's videos, optionally banning its author.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "moderationStatus": { "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "heldForReview" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "banAuthor": { "description": "Also block the comment's author from the channel. Only with moderationStatus rejected.", "type": "boolean" } }, "required": [ "moderationStatus" ] } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "moderationStatus": { "anyOf": [ { "type": "string", "enum": [ "published" ] }, { "type": "string", "enum": [ "heldForReview" ] }, { "type": "string", "enum": [ "rejected" ] } ] }, "banAuthor": { "type": "boolean" } }, "required": [ "externalId", "moderationStatus", "banAuthor" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/google_business_profile.locations.reviews": { "get": { "operationId": "google_business_profile.locations.reviews.list", "summary": "List the location's reviews, most recently changed first", "tags": [ "Content: google_business_profile" ], "description": "List the location's reviews, most recently changed first.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "locationExternalId": { "minLength": 1, "type": "string" }, "rating": { "additionalProperties": false, "description": "A score on the provider's own scale, with its position on that scale as a percentage.", "type": "object", "properties": { "value": { "description": "The score as the provider reports it, on its own scale.", "type": "number" }, "min": { "description": "The lowest score the provider's scale allows.", "type": "number" }, "max": { "description": "The highest score the provider's scale allows.", "type": "number" }, "percent": { "minimum": 0, "maximum": 100, "description": "Where `value` sits on the scale: 0 at `min`, 100 at `max`, to two decimal places. Derived, and comparable across providers.", "type": "number" } }, "required": [ "value", "min", "max", "percent" ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "reviewer": { "additionalProperties": false, "description": "The reviewer as Google reports them: a name and photo, or neither when anonymous. Google publishes no stable reviewer id.", "type": "object", "properties": { "displayName": { "minLength": 1, "type": "string" }, "profilePhotoUrl": { "minLength": 1, "type": "string" }, "isAnonymous": { "type": "boolean" } }, "required": [ "isAnonymous" ] }, "media": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "thumbnailUrl": { "minLength": 1, "type": "string" }, "videoUrl": { "minLength": 1, "type": "string" } } } }, "reply": { "additionalProperties": false, "type": "object", "properties": { "text": { "description": "Caption/body text for content.", "type": "string" }, "state": { "description": "Google's moderation state of the owner's reply.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "APPROVED" ] }, { "type": "string", "enum": [ "REJECTED" ] } ] }, "policyViolation": { "minLength": 1, "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" } }, "required": [ "text" ] }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "google_business_profile.locations.reviews" ] } }, "required": [ "externalId", "locationExternalId", "reviewer", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/google_business_profile.locations.reviews/{externalId}": { "get": { "operationId": "google_business_profile.locations.reviews.get", "summary": "Get one review of the location by provider id", "tags": [ "Content: google_business_profile" ], "description": "Get one review of the location by provider id.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "locationExternalId": { "minLength": 1, "type": "string" }, "rating": { "additionalProperties": false, "description": "A score on the provider's own scale, with its position on that scale as a percentage.", "type": "object", "properties": { "value": { "description": "The score as the provider reports it, on its own scale.", "type": "number" }, "min": { "description": "The lowest score the provider's scale allows.", "type": "number" }, "max": { "description": "The highest score the provider's scale allows.", "type": "number" }, "percent": { "minimum": 0, "maximum": 100, "description": "Where `value` sits on the scale: 0 at `min`, 100 at `max`, to two decimal places. Derived, and comparable across providers.", "type": "number" } }, "required": [ "value", "min", "max", "percent" ] }, "text": { "description": "Caption/body text for content.", "type": "string" }, "reviewer": { "additionalProperties": false, "description": "The reviewer as Google reports them: a name and photo, or neither when anonymous. Google publishes no stable reviewer id.", "type": "object", "properties": { "displayName": { "minLength": 1, "type": "string" }, "profilePhotoUrl": { "minLength": 1, "type": "string" }, "isAnonymous": { "type": "boolean" } }, "required": [ "isAnonymous" ] }, "media": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "thumbnailUrl": { "minLength": 1, "type": "string" }, "videoUrl": { "minLength": 1, "type": "string" } } } }, "reply": { "additionalProperties": false, "type": "object", "properties": { "text": { "description": "Caption/body text for content.", "type": "string" }, "state": { "description": "Google's moderation state of the owner's reply.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "APPROVED" ] }, { "type": "string", "enum": [ "REJECTED" ] } ] }, "policyViolation": { "minLength": 1, "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" } }, "required": [ "text" ] }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "google_business_profile.locations.reviews" ] } }, "required": [ "externalId", "locationExternalId", "reviewer", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/google_business_profile.locations.review_replies/{externalId}": { "get": { "operationId": "google_business_profile.locations.review_replies.get", "summary": "Get the owner's reply to one review", "tags": [ "Content: google_business_profile" ], "description": "Get the owner's reply to one review.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "locationExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "state": { "description": "Google's moderation state of the owner's reply.", "anyOf": [ { "type": "string", "enum": [ "PENDING" ] }, { "type": "string", "enum": [ "APPROVED" ] }, { "type": "string", "enum": [ "REJECTED" ] } ] }, "policyViolation": { "minLength": 1, "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "google_business_profile.locations.review_replies" ] } }, "required": [ "externalId", "locationExternalId", "text", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "google_business_profile.locations.review_replies.delete", "summary": "Remove the owner's reply to a review", "tags": [ "Content: google_business_profile" ], "description": "Remove the owner's reply to a review.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.items": { "get": { "operationId": "linkedin.feed.items.list", "summary": "List the Page's posts, newest created first", "tags": [ "Content: linkedin" ], "description": "List the Page's posts, newest created first.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "organizationExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "mentions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "urn": { "minLength": 1, "type": "string" } }, "required": [ "name", "urn" ] } }, "hashtags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "content": { "additionalProperties": false, "type": "object", "properties": { "kind": { "description": "What the post carries besides its text. `image`, `video` and `document` name a single uploaded asset by its LinkedIn URN.", "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "document" ] }, { "type": "string", "enum": [ "article" ] }, { "type": "string", "enum": [ "multi_image" ] }, { "type": "string", "enum": [ "poll" ] }, { "type": "string", "enum": [ "reshare" ] }, { "type": "string", "enum": [ "other" ] } ] }, "mediaUrn": { "minLength": 1, "type": "string" }, "imageUrns": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "url": { "minLength": 1, "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "altText": { "type": "string" }, "resharedPostUrn": { "minLength": 1, "type": "string" } }, "required": [ "kind" ] }, "visibility": { "description": "`PUBLIC`, `CONNECTIONS`, `LOGGED_IN` or `CONTAINER`. Only `PUBLIC` posts raise LinkedIn's comment notifications.", "type": "string" }, "lifecycleState": { "description": "`PUBLISHED`, or `PUBLISH_REQUESTED` while LinkedIn processes it, `PUBLISH_FAILED`, `DRAFT`.", "type": "string" }, "reshareDisabled": { "type": "boolean" }, "permalink": { "minLength": 1, "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.items" ] } }, "required": [ "externalId", "organizationExternalId", "content", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.items/{externalId}": { "get": { "operationId": "linkedin.feed.items.get", "summary": "Get one of the Page's posts by its share or ugcPost URN", "tags": [ "Content: linkedin" ], "description": "Get one of the Page's posts by its share or ugcPost URN.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "organizationExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "mentions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "urn": { "minLength": 1, "type": "string" } }, "required": [ "name", "urn" ] } }, "hashtags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "content": { "additionalProperties": false, "type": "object", "properties": { "kind": { "description": "What the post carries besides its text. `image`, `video` and `document` name a single uploaded asset by its LinkedIn URN.", "anyOf": [ { "type": "string", "enum": [ "text" ] }, { "type": "string", "enum": [ "image" ] }, { "type": "string", "enum": [ "video" ] }, { "type": "string", "enum": [ "document" ] }, { "type": "string", "enum": [ "article" ] }, { "type": "string", "enum": [ "multi_image" ] }, { "type": "string", "enum": [ "poll" ] }, { "type": "string", "enum": [ "reshare" ] }, { "type": "string", "enum": [ "other" ] } ] }, "mediaUrn": { "minLength": 1, "type": "string" }, "imageUrns": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "url": { "minLength": 1, "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "altText": { "type": "string" }, "resharedPostUrn": { "minLength": 1, "type": "string" } }, "required": [ "kind" ] }, "visibility": { "description": "`PUBLIC`, `CONNECTIONS`, `LOGGED_IN` or `CONTAINER`. Only `PUBLIC` posts raise LinkedIn's comment notifications.", "type": "string" }, "lifecycleState": { "description": "`PUBLISHED`, or `PUBLISH_REQUESTED` while LinkedIn processes it, `PUBLISH_FAILED`, `DRAFT`.", "type": "string" }, "reshareDisabled": { "type": "boolean" }, "permalink": { "minLength": 1, "type": "string" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.items" ] } }, "required": [ "externalId", "organizationExternalId", "content", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "linkedin.feed.items.delete", "summary": "Delete one of the Page's posts", "tags": [ "Content: linkedin" ], "description": "Delete one of the Page's posts.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.comments": { "get": { "operationId": "linkedin.feed.comments.list", "summary": "List the comments on one of the Page's posts, or the replies to one of its comments", "tags": [ "Content: linkedin" ], "description": "List the comments on one of the Page's posts, or the replies to one of its comments.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": true, "description": "The post's urn:li:share:… or urn:li:ugcPost:… URN." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "parentExternalId", "required": false, "description": "A comment URN on that post, to list its replies." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "commentId": { "minLength": 1, "type": "string" }, "threadUrn": { "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "mentions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "start": { "minimum": 0, "type": "integer" }, "length": { "minimum": 0, "type": "integer" }, "urn": { "minLength": 1, "type": "string" } }, "required": [ "start", "length", "urn" ] } }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "ownerAuthored": { "type": "boolean" }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.comments" ] } }, "required": [ "externalId", "commentId", "threadUrn", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.comments/{externalId}": { "get": { "operationId": "linkedin.feed.comments.get", "summary": "Get one comment by its URN", "tags": [ "Content: linkedin" ], "description": "Get one comment by its URN.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "mediaExternalId", "required": false, "description": "The post's URN, echoed on the result; LinkedIn's comment read does not return it." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "commentId": { "minLength": 1, "type": "string" }, "threadUrn": { "minLength": 1, "type": "string" }, "mediaExternalId": { "minLength": 1, "type": "string" }, "text": { "description": "Caption/body text for content.", "type": "string" }, "mentions": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "start": { "minimum": 0, "type": "integer" }, "length": { "minimum": 0, "type": "integer" }, "urn": { "minLength": 1, "type": "string" } }, "required": [ "start", "length", "urn" ] } }, "media": { "type": "array", "items": { "additionalProperties": false, "description": "A staged or remote media asset. Source constraints are enforced by operation schemas.", "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "filename": { "minLength": 1, "type": "string" }, "checksum": { "pattern": "^sha256:[0-9a-fA-F]{64}$", "type": "string" }, "altText": { "minLength": 1, "type": "string" } } } }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "ownerAuthored": { "type": "boolean" }, "thread": { "additionalProperties": false, "description": "Parent/root identifiers for threaded contexts.", "type": "object", "properties": { "parentId": { "minLength": 1, "type": "string" }, "rootId": { "minLength": 1, "type": "string" }, "threadId": { "minLength": 1, "type": "string" } } }, "engagement": { "additionalProperties": false, "description": "Provider-reported engagement counts.", "type": "object", "properties": { "likes": { "minimum": 0, "description": "Likes, favourites, or reactions on the content.", "type": "number" }, "comments": { "minimum": 0, "description": "Comments or replies on the content.", "type": "number" } } }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "updatedAt": { "format": "date-time", "description": "Provider update timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.comments" ] } }, "required": [ "externalId", "commentId", "threadUrn", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "linkedin.feed.comments.delete", "summary": "Delete a comment the Page wrote", "tags": [ "Content: linkedin" ], "description": "Delete a comment the Page wrote.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.reactions": { "get": { "operationId": "linkedin.feed.reactions.list", "summary": "List the reactions on one post or comment, newest first", "tags": [ "Content: linkedin" ], "description": "List the reactions on one post or comment, newest first.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "entityExternalId", "required": true, "description": "A post URN or a comment URN." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minimum": 1, "type": "number" }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "entityExternalId": { "minLength": 1, "type": "string" }, "reactionType": { "minLength": 1, "description": "One of LinkedIn's reaction types, passed through as LinkedIn reports it.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "ownerAuthored": { "type": "boolean" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.reactions" ] } }, "required": [ "externalId", "entityExternalId", "reactionType", "contentType" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content/linkedin.feed.reactions/{externalId}": { "get": { "operationId": "linkedin.feed.reactions.get", "summary": "Get one reaction by its URN", "tags": [ "Content: linkedin" ], "description": "Get one reaction by its URN.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "boolean" }, "in": "query", "name": "includeProviderRaw", "required": false, "description": "Whether to include transient provider-native payloads." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "description": "Provider-owned content identifier.", "minLength": 1, "type": "string" }, "entityExternalId": { "minLength": 1, "type": "string" }, "reactionType": { "minLength": 1, "description": "One of LinkedIn's reaction types, passed through as LinkedIn reports it.", "type": "string" }, "author": { "additionalProperties": false, "description": "Provider actor reference for observed content.", "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "username": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "ownerAuthored": { "type": "boolean" }, "publishedAt": { "format": "date-time", "description": "Provider publish timestamp as an ISO-8601 string.", "type": "string" }, "providerRaw": { "description": "Optional provider-native payload included only for transient delivery/debug use." }, "contentType": { "type": "string", "enum": [ "linkedin.feed.reactions" ] } }, "required": [ "externalId", "entityExternalId", "reactionType", "contentType" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "linkedin.feed.reactions.delete", "summary": "Remove the Page's own reaction", "tags": [ "Content: linkedin" ], "description": "Remove the Page's own reaction.", "parameters": [ { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": true, "description": "Koil Connected Profile associated with the operation." }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "externalId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "externalId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "externalId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth-integrations": { "post": { "operationId": "koil.auth_integrations.create", "summary": "Create a customer-owned OAuth Auth Integration", "tags": [ "Auth integrations" ], "description": "Create a customer-owned OAuth Auth Integration.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "clientReferenceId": { "minLength": 1, "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "oauthClient": { "additionalProperties": false, "type": "object", "properties": { "clientId": { "minLength": 1, "type": "string" }, "clientSecret": { "minLength": 1, "type": "string" }, "scopes": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "clientId", "clientSecret" ] } }, "required": [ "authProviderId", "displayName", "oauthClient" ] }, "example": { "authProviderId": "facebook", "displayName": "Acme Meta App", "oauthClient": { "clientId": "1234567890", "clientSecret": "app-secret", "scopes": [ "instagram_basic", "pages_show_list", "pages_read_engagement" ] } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "clientReferenceId": { "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "webhookVerifyToken": { "minLength": 1, "description": "Verify token for the provider developer console's webhook callback-URL handshake. Enter it beside Koil's callback URL, `/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId}`.", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "authIntegrationId", "authProviderId", "displayName", "webhookVerifyToken", "status" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "koil.auth_integrations.list", "summary": "List Auth Integrations for the current Organization", "tags": [ "Auth integrations" ], "description": "List Auth Integrations for the current Organization.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "clientReferenceId": { "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "webhookVerifyToken": { "minLength": 1, "description": "Verify token for the provider developer console's webhook callback-URL handshake. Enter it beside Koil's callback URL, `/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId}`.", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "authIntegrationId", "authProviderId", "displayName", "webhookVerifyToken", "status" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth-integrations/{authIntegrationId}": { "get": { "operationId": "koil.auth_integrations.get", "summary": "Get an Auth Integration", "tags": [ "Auth integrations" ], "description": "Get an Auth Integration.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "authIntegrationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "clientReferenceId": { "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "webhookVerifyToken": { "minLength": 1, "description": "Verify token for the provider developer console's webhook callback-URL handshake. Enter it beside Koil's callback URL, `/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId}`.", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "authIntegrationId", "authProviderId", "displayName", "webhookVerifyToken", "status" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "koil.auth_integrations.update", "summary": "Update an Auth Integration", "tags": [ "Auth integrations" ], "description": "Update an Auth Integration.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "displayName": { "minLength": 1, "type": "string" }, "clientReferenceId": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] } }, "required": [] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "authIntegrationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "clientReferenceId": { "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "webhookVerifyToken": { "minLength": 1, "description": "Verify token for the provider developer console's webhook callback-URL handshake. Enter it beside Koil's callback URL, `/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId}`.", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "authIntegrationId", "authProviderId", "displayName", "webhookVerifyToken", "status" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "koil.auth_integrations.delete", "summary": "Delete an Auth Integration", "tags": [ "Auth integrations" ], "description": "Delete an Auth Integration.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "authIntegrationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth-integrations/{authIntegrationId}/rotate-secret": { "post": { "operationId": "koil.auth_integrations.rotate_secret", "summary": "Rotate an Auth Integration OAuth client secret", "tags": [ "Auth integrations" ], "description": "Rotate an Auth Integration OAuth client secret.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "oauthClient": { "additionalProperties": false, "type": "object", "properties": { "clientId": { "minLength": 1, "type": "string" }, "clientSecret": { "minLength": 1, "type": "string" }, "scopes": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "clientId", "clientSecret" ] } }, "required": [ "oauthClient" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "authIntegrationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "authProviderId": { "description": "The upstream credential issuer the OAuth app belongs to, such as `facebook` for Facebook Login or `instagram` for Instagram Login.", "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "clientReferenceId": { "type": "string" }, "providerAppId": { "minLength": 1, "description": "The provider's own id for your app, where a provider needs one that is not the OAuth client id: LinkedIn's developer application id, the number in your app's Developer Portal URL. Required for an auth provider whose provider declares it (`providerAppId` on `GET /v1/providers`), refused for any other, and fixed once the Auth Integration exists.", "type": "string" }, "webhookVerifyToken": { "minLength": 1, "description": "Verify token for the provider developer console's webhook callback-URL handshake. Enter it beside Koil's callback URL, `/webhooks/providers/{providerId}?authIntegrationId={authIntegrationId}`.", "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "disabled" ] } ] }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "authIntegrationId", "authProviderId", "displayName", "webhookVerifyToken", "status" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/backfill-requests": { "post": { "operationId": "koil.backfill_requests.create", "summary": "Submit one or more backfill requests, each for one content type's history on one Connected Profile", "tags": [ "Backfill requests" ], "description": "Submit one or more backfill requests, each for one content type's history on one Connected Profile. Historical items are delivered as ordinary `content.*` events; nothing is stored. Validation is atomic across the submission and every item then runs independently. Requires an `Idempotency-Key`; one run per content type per profile may be in flight at a time.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 100, "description": "The runs to start. Each item becomes its own backfill request with its own progress; a profile onboarding lists its content types, an incident recovery lists its profiles.", "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "description": "Fully qualified content type to backfill, e.g. `instagram.media.items`. It must belong to the profile's provider and declare a supported backfill capability.", "type": "string" } }, "required": [ "connectedProfileId", "contentType" ] } }, "since": { "format": "date-time", "description": "Oldest item time to emit, applied to every item. Omit for no lower bound, in which case each run is bounded only by `maxItems` and the provider's history.", "type": "string" }, "maxItems": { "minimum": 1, "maximum": 10000, "default": 1000, "description": "Hard cap on emitted events per item, not in total. A run that stops here finishes `partial`.", "type": "integer" } }, "required": [ "items" ] }, "example": { "items": [ { "connectedProfileId": "cp_123", "contentType": "instagram.media.items" }, { "connectedProfileId": "cp_123", "contentType": "instagram.stories.items" } ], "since": "2026-06-01T00:00:00Z", "maxItems": 1000 } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "pattern": "\\S", "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "A unique key for this request, scoped to the Organization and operation. Retrying with the same key and payload returns the first result instead of repeating the work; the same key with a different payload is refused with `409 conflict`. Keys expire 24 hours after first use, and a request still in flight after 15 minutes releases its key." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "backfillRequests": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "backfillRequestId": { "description": "Koil backfill request identifier.", "minLength": 1, "type": "string" }, "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "since": { "format": "date-time", "type": "string" }, "maxItems": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "running" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "exhausted" ] }, { "type": "string", "enum": [ "reached_since" ] }, { "type": "string", "enum": [ "capped" ] } ] }, "emitted": { "type": "integer" }, "fetched": { "type": "integer" }, "skipped": { "type": "integer" }, "oldestEmittedAt": { "format": "date-time", "type": "string" }, "error": { "type": "string" }, "startedAt": { "format": "date-time", "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "backfillRequestId", "connectedProfileId", "contentType", "maxItems", "status", "emitted", "fetched", "skipped", "createdAt", "updatedAt" ] } } }, "required": [ "backfillRequests" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "koil.backfill_requests.list", "summary": "List the Organization's backfill requests, newest first, optionally narrowed to one Connected Profile and one status", "tags": [ "Backfill requests" ], "description": "List the Organization's backfill requests, newest first, optionally narrowed to one Connected Profile and one status.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": false, "description": "Koil Connected Profile identifier." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "running" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "in": "query", "name": "status", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "backfillRequestId": { "description": "Koil backfill request identifier.", "minLength": 1, "type": "string" }, "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "since": { "format": "date-time", "type": "string" }, "maxItems": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "running" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "exhausted" ] }, { "type": "string", "enum": [ "reached_since" ] }, { "type": "string", "enum": [ "capped" ] } ] }, "emitted": { "type": "integer" }, "fetched": { "type": "integer" }, "skipped": { "type": "integer" }, "oldestEmittedAt": { "format": "date-time", "type": "string" }, "error": { "type": "string" }, "startedAt": { "format": "date-time", "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "backfillRequestId", "connectedProfileId", "contentType", "maxItems", "status", "emitted", "fetched", "skipped", "createdAt", "updatedAt" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] }, "example": { "data": [ { "backfillRequestId": "bf_2Jd8kQm4ZtPw7XcR1nVb", "connectedProfileId": "cp_123", "contentType": "instagram.media.items", "since": "2026-06-01T00:00:00.000Z", "maxItems": 1000, "status": "completed", "stopReason": "reached_since", "emitted": 212, "fetched": 240, "skipped": 28, "oldestEmittedAt": "2026-06-01T08:14:03.000Z", "startedAt": "2026-07-01T10:00:01.000Z", "completedAt": "2026-07-01T10:02:37.000Z", "createdAt": "2026-07-01T10:00:00.000Z", "updatedAt": "2026-07-01T10:02:37.000Z" } ], "nextCursor": "WyIyMDI2LTA3LTAxVDEwOjAwOjAwLjAwMFoiLCJiZl8ySmQ4a1FtNFp0UHc3WGNSMW5WYiJd", "hasMore": true } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/backfill-requests/{backfillRequestId}": { "get": { "operationId": "koil.backfill_requests.get", "summary": "Get one backfill request and its progress", "tags": [ "Backfill requests" ], "description": "Get one backfill request and its progress.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "backfillRequestId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "backfillRequestId": { "description": "Koil backfill request identifier.", "minLength": 1, "type": "string" }, "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "since": { "format": "date-time", "type": "string" }, "maxItems": { "type": "integer" }, "status": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "running" ] }, { "type": "string", "enum": [ "completed" ] }, { "type": "string", "enum": [ "partial" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "stopReason": { "anyOf": [ { "type": "string", "enum": [ "exhausted" ] }, { "type": "string", "enum": [ "reached_since" ] }, { "type": "string", "enum": [ "capped" ] } ] }, "emitted": { "type": "integer" }, "fetched": { "type": "integer" }, "skipped": { "type": "integer" }, "oldestEmittedAt": { "format": "date-time", "type": "string" }, "error": { "type": "string" }, "startedAt": { "format": "date-time", "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "backfillRequestId", "connectedProfileId", "contentType", "maxItems", "status", "emitted", "fetched", "skipped", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/billing/account": { "get": { "operationId": "koil.billing.account", "summary": "Get the current Organization's plan, entitlement caps, and Connected Profile count", "tags": [ "Billing" ], "description": "Get the current Organization's plan, entitlement caps, and Connected Profile count.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string", "enum": [ "free" ] }, { "type": "string", "enum": [ "payg" ] }, { "type": "string", "enum": [ "enterprise" ] } ] }, "caps": { "additionalProperties": false, "type": "object", "properties": { "connectedProfiles": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "publishItems": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "connectedProfiles", "publishItems" ] }, "connectedProfiles": { "minimum": 0, "type": "integer" } }, "required": [ "plan", "caps", "connectedProfiles" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connect-sessions": { "post": { "operationId": "koil.connect_sessions.create", "summary": "Create a Koil Connect Session", "tags": [ "Connect sessions" ], "description": "Create a Koil Connect Session.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "externalActorId": { "description": "External actor identifier. Empty string is treated as omitted.", "type": "string" } }, "required": [ "authIntegrationId" ] }, "example": { "authIntegrationId": "int_123", "externalActorId": "customer-user-123" } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectSessionToken": { "description": "Short-lived Koil Connect Session token.", "minLength": 1, "type": "string" }, "authorizationUrl": { "format": "uri", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "connectSessionToken", "authorizationUrl", "expiresAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connect-sessions/{connectSessionToken}": { "get": { "operationId": "koil.connect_sessions.get", "summary": "Get a Koil Connect Session by token", "tags": [ "Connect sessions" ], "description": "Get a Koil Connect Session by token.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectSessionToken", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectSessionToken": { "description": "Short-lived Koil Connect Session token.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "connectSessionToken", "status" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections": { "get": { "operationId": "koil.connections.list", "summary": "List Koil Connections for the current Organization", "tags": [ "Connections" ], "description": "List Koil Connections for the current Organization.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectionId", "authIntegrationId", "status", "scopes" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections/import": { "post": { "operationId": "koil.connections.import", "summary": "Import an existing provider grant as a Koil Connection", "tags": [ "Connections" ], "description": "Import an existing provider grant as a Koil Connection.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "externalActorId": { "minLength": 1, "type": "string" }, "grant": { "type": "object", "additionalProperties": {} }, "scopes": { "description": "The scopes the grant holds. Required when `grant` carries no `scope` and the provider cannot report them (Google, LinkedIn).", "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "authIntegrationId", "grant" ] } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectionId", "authIntegrationId", "status", "scopes" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections/{connectionId}": { "get": { "operationId": "koil.connections.get", "summary": "Get a Koil Connection", "tags": [ "Connections" ], "description": "Get a Koil Connection.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectionId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectionId", "authIntegrationId", "status", "scopes" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "koil.connections.delete", "summary": "Delete a Koil Connection", "tags": [ "Connections" ], "description": "Delete a Koil Connection.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectionId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections/{connectionId}/health": { "get": { "operationId": "koil.connections.get_health", "summary": "Get health for a Koil Connection", "tags": [ "Connections" ], "description": "Get health for a Koil Connection.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectionId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "authIntegrationId": { "description": "OAuth integration identifier used to authorize the Connection.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "healthy": { "type": "boolean" }, "checkedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectionId", "authIntegrationId", "status", "healthy", "checkedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connections/{connectionId}/eligible-profiles": { "get": { "operationId": "koil.connections.list_eligible_profiles", "summary": "List provider profiles eligible for Connected Profile creation", "tags": [ "Connections" ], "description": "List provider profiles eligible for Connected Profile creation.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectionId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "providerId": { "description": "Koil provider identifier.", "minLength": 1, "type": "string" }, "providerProfileExternalId": { "minLength": 1, "type": "string" }, "displayName": { "type": "string" }, "accountKind": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "resourceRefs": { "type": "object", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "providerId", "providerProfileExternalId", "capabilities" ] } } }, "required": [ "data" ] }, "example": { "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 } } ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connected-profiles": { "get": { "operationId": "koil.connected_profiles.list", "summary": "List Koil Connected Profiles for the current Organization", "tags": [ "Connected profiles" ], "description": "List Koil Connected Profiles for the current Organization.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "providerId": { "description": "Koil provider identifier.", "minLength": 1, "type": "string" }, "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "providerProfileExternalId": { "minLength": 1, "type": "string" }, "resourceRefs": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectedProfileId", "providerId", "connectionId", "providerProfileExternalId", "createdAt", "updatedAt" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "koil.connected_profiles.create", "summary": "Create a Koil Connected Profile from an eligible provider profile", "tags": [ "Connected profiles" ], "description": "Create a Koil Connected Profile from an eligible provider profile.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "providerId": { "description": "Koil provider identifier.", "minLength": 1, "type": "string" }, "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "providerProfileExternalId": { "minLength": 1, "type": "string" } }, "required": [ "providerId", "connectionId", "providerProfileExternalId" ] }, "examples": { "example1": { "value": { "providerId": "youtube", "connectionId": "test_conn_youtube_healthy", "providerProfileExternalId": "UCtest_yt_channel_1" } }, "example2": { "value": { "providerId": "instagram", "connectionId": "conn_123", "providerProfileExternalId": "17841400000000000" } } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "providerId": { "description": "Koil provider identifier.", "minLength": 1, "type": "string" }, "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "providerProfileExternalId": { "minLength": 1, "type": "string" }, "resourceRefs": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectedProfileId", "providerId", "connectionId", "providerProfileExternalId", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connected-profiles/{connectedProfileId}": { "get": { "operationId": "koil.connected_profiles.get", "summary": "Get a Koil Connected Profile", "tags": [ "Connected profiles" ], "description": "Get a Koil Connected Profile.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectedProfileId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "providerId": { "description": "Koil provider identifier.", "minLength": 1, "type": "string" }, "connectionId": { "description": "Koil Connection identifier.", "minLength": 1, "type": "string" }, "providerProfileExternalId": { "minLength": 1, "type": "string" }, "resourceRefs": { "type": "object", "additionalProperties": { "type": "string" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectedProfileId", "providerId", "connectionId", "providerProfileExternalId", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "koil.connected_profiles.delete", "summary": "Delete a Koil Connected Profile", "tags": [ "Connected profiles" ], "description": "Delete a Koil Connected Profile.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectedProfileId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connected-profiles/{connectedProfileId}/capabilities": { "get": { "operationId": "koil.connected_profiles.get_capabilities", "summary": "Get operation capabilities for a Koil Connected Profile", "tags": [ "Connected profiles" ], "description": "Get operation capabilities for a Koil Connected Profile.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "connectedProfileId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "connectedProfileId": { "description": "Koil Connected Profile identifier.", "minLength": 1, "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "connectedProfileId", "capabilities" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/event-destinations": { "post": { "operationId": "koil.event_destinations.create", "summary": "Create an Event Destination", "tags": [ "Event destinations" ], "description": "Create an Event Destination: where events are delivered, which topics it receives, and optionally which Connected Profiles.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "type": { "minLength": 1, "type": "string" }, "topics": { "minItems": 1, "type": "array", "items": { "description": "Koil event routing topic.", "minLength": 1, "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "type", "topics" ] }, "examples": { "example1": { "value": { "type": "webhook", "topics": [ "publish_request.*" ], "config": { "url": "https://example.com/koil/events" } } }, "example2": { "value": { "type": "webhook", "topics": [ "content.instagram.media.comments.*", "content.instagram.dm.messages.*", "publish_request.*" ], "scope": { "type": "connected_profiles", "connectedProfileIds": [ "cp_123" ] }, "config": { "url": "https://example.com/koil/events" }, "credentials": { "secret": "your-signing-secret" } } } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "destinationId": { "description": "Event Destination identifier.", "minLength": 1, "type": "string" }, "type": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "destinationId", "type", "topics" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "koil.event_destinations.list", "summary": "List Event Destinations for the current Organization", "tags": [ "Event destinations" ], "description": "List Event Destinations for the current Organization.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "destinationId": { "description": "Event Destination identifier.", "minLength": 1, "type": "string" }, "type": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "destinationId", "type", "topics" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/event-destinations/{destinationId}": { "get": { "operationId": "koil.event_destinations.get", "summary": "Get an Event Destination", "tags": [ "Event destinations" ], "description": "Get an Event Destination.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "destinationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "destinationId": { "description": "Event Destination identifier.", "minLength": 1, "type": "string" }, "type": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "destinationId", "type", "topics" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "koil.event_destinations.update", "summary": "Update an Event Destination", "tags": [ "Event destinations" ], "description": "Update an Event Destination.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "topics": { "minItems": 1, "type": "array", "items": { "description": "Koil event routing topic.", "minLength": 1, "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" } }, "required": [] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "destinationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "destinationId": { "description": "Event Destination identifier.", "minLength": 1, "type": "string" }, "type": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "destinationId", "type", "topics" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "koil.event_destinations.delete", "summary": "Delete an Event Destination", "tags": [ "Event destinations" ], "description": "Delete an Event Destination.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "destinationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/event-destinations/{destinationId}/rotate-secret": { "post": { "operationId": "koil.event_destinations.rotate_secret", "summary": "Rotate an Event Destination webhook secret", "tags": [ "Event destinations" ], "description": "Rotate an Event Destination webhook secret.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "previousSecretInvalidAt": { "format": "date-time", "type": "string" } }, "required": [] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "destinationId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "destinationId": { "description": "Event Destination identifier.", "minLength": 1, "type": "string" }, "type": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "scope": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "organization" ] } }, "required": [ "type" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string", "enum": [ "connected_profiles" ] }, "connectedProfileIds": { "minItems": 1, "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "type", "connectedProfileIds" ] } ] }, "config": { "type": "object", "additionalProperties": {} }, "filter": { "type": "object", "additionalProperties": {} }, "enabled": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "destinationId", "type", "topics" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/event-destination-types": { "get": { "operationId": "koil.event_destination_types.list", "summary": "List the Event Destination types Koil can deliver to", "tags": [ "Event destination types" ], "description": "List the Event Destination types Koil can deliver to.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/event-destination-types/{type}": { "get": { "operationId": "koil.event_destination_types.get", "summary": "Get one Event Destination type with the schemas of its `config` and `credentials`", "tags": [ "Event destination types" ], "description": "Get one Event Destination type with the schemas of its `config` and `credentials`.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "type", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "schema": { "type": "object", "additionalProperties": {} }, "configSchema": { "type": "object", "additionalProperties": {} }, "credentialsSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "type" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/media": { "post": { "operationId": "koil.media.create", "summary": "Create a media object", "tags": [ "Media" ], "description": "Create a media object. Give an HTTPS `sourceUrl` for Koil to fetch, or omit it to get a pre-signed upload URL in the response. Images may be up to 50 MB and 100 megapixels, videos up to 1 GB. Reference the returned `mediaId` from publish requests within 24 hours of creating it. Requires an `Idempotency-Key`.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "filename": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "sourceUrl": { "minLength": 1, "type": "string" } } } } } }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "pattern": "\\S", "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "A unique key for this request, scoped to the Organization and operation. Retrying with the same key and payload returns the first result instead of repeating the work; the same key with a different payload is refused with `409 conflict`. Keys expire 24 hours after first use, and a request still in flight after 15 minutes releases its key." } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "status": { "minLength": 1, "type": "string" }, "uploadUrl": { "minLength": 1, "type": "string" }, "statusUrl": { "minLength": 1, "type": "string" } }, "required": [ "mediaId", "status", "statusUrl" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/media/{mediaId}": { "get": { "operationId": "koil.media.get", "summary": "Get a media object's processing status and derived variants", "tags": [ "Media" ], "description": "Get a media object's processing status and derived variants.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "mediaId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "status": { "minLength": 1, "type": "string" }, "origin": { "minLength": 1, "type": "string" }, "kind": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "sizeBytes": { "type": "number" }, "sourceUrl": { "minLength": 1, "type": "string" }, "error": { "type": "object", "additionalProperties": {} }, "statusUrl": { "minLength": 1, "type": "string" }, "previewUrl": { "minLength": 1, "type": "string" }, "createdAt": { "minLength": 1, "type": "string" }, "updatedAt": { "minLength": 1, "type": "string" } }, "required": [ "mediaId", "status", "origin", "statusUrl", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "koil.media.delete", "summary": "Delete a media object and its derived variants", "tags": [ "Media" ], "description": "Delete a media object and its derived variants. Publishes already running keep their own staged copy.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "mediaId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "mediaId": { "minLength": 1, "type": "string" }, "deleted": { "type": "boolean" } }, "required": [ "mediaId", "deleted" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/providers": { "get": { "operationId": "koil.providers.list", "summary": "List provider capabilities available through Koil", "tags": [ "Providers" ], "description": "List provider capabilities available through Koil.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "providerId": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "description": "How customers name the provider.", "type": "string" }, "summary": { "description": "What Koil reaches on the provider, and through what.", "type": "string" }, "notes": { "description": "Facts an integration with this provider depends on.", "type": "array", "items": { "type": "string" } }, "caution": { "additionalProperties": false, "description": "A limitation to know before building on the provider.", "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "required": [ "title", "body" ] }, "authProviderIds": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "providerAppId": { "additionalProperties": false, "description": "The provider's own id for your app that an Auth Integration of `authProviderId` must carry as `providerAppId`, because the provider needs it and it is not the OAuth client id.", "type": "object", "properties": { "authProviderId": { "minLength": 1, "type": "string" }, "description": { "minLength": 1, "type": "string" }, "pattern": { "minLength": 1, "type": "string" } }, "required": [ "authProviderId", "description" ] }, "capabilities": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "capability": { "minLength": 1, "type": "string" }, "supported": { "type": "boolean" }, "reason": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "credentials": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "kind": { "minLength": 1, "type": "string" }, "authProviderId": { "minLength": 1, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "grant" ] }, { "type": "string", "enum": [ "connect" ] }, { "type": "string", "enum": [ "app" ] } ] }, "scopes": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "resourceRefs": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "kind", "authProviderId", "source", "scopes", "resourceRefs" ] } } }, "required": [ "capability", "supported", "credentials" ] } }, "requiredScopes": { "type": "object", "additionalProperties": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "surfaces": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "surfaceId": { "minLength": 1, "type": "string" }, "resources": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "surfaceId", "resources" ] } } }, "required": [ "providerId", "displayName", "authProviderIds", "capabilities", "requiredScopes", "surfaces" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/providers/{providerId}": { "get": { "operationId": "koil.providers.get", "summary": "Get provider capabilities available through Koil", "tags": [ "Providers" ], "description": "Get provider capabilities available through Koil.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "providerId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "providerId": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "description": "How customers name the provider.", "type": "string" }, "summary": { "description": "What Koil reaches on the provider, and through what.", "type": "string" }, "notes": { "description": "Facts an integration with this provider depends on.", "type": "array", "items": { "type": "string" } }, "caution": { "additionalProperties": false, "description": "A limitation to know before building on the provider.", "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "required": [ "title", "body" ] }, "authProviderIds": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "providerAppId": { "additionalProperties": false, "description": "The provider's own id for your app that an Auth Integration of `authProviderId` must carry as `providerAppId`, because the provider needs it and it is not the OAuth client id.", "type": "object", "properties": { "authProviderId": { "minLength": 1, "type": "string" }, "description": { "minLength": 1, "type": "string" }, "pattern": { "minLength": 1, "type": "string" } }, "required": [ "authProviderId", "description" ] }, "capabilities": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "capability": { "minLength": 1, "type": "string" }, "supported": { "type": "boolean" }, "reason": { "minLength": 1, "type": "string" }, "detail": { "minLength": 1, "type": "string" }, "credentials": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "kind": { "minLength": 1, "type": "string" }, "authProviderId": { "minLength": 1, "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "grant" ] }, { "type": "string", "enum": [ "connect" ] }, { "type": "string", "enum": [ "app" ] } ] }, "scopes": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "resourceRefs": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "kind", "authProviderId", "source", "scopes", "resourceRefs" ] } } }, "required": [ "capability", "supported", "credentials" ] } }, "requiredScopes": { "type": "object", "additionalProperties": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "surfaces": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "surfaceId": { "minLength": 1, "type": "string" }, "resources": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "surfaceId", "resources" ] } } }, "required": [ "providerId", "displayName", "authProviderIds", "capabilities", "requiredScopes", "surfaces" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/providers/{providerId}/surfaces": { "get": { "operationId": "koil.providers.list_surfaces", "summary": "List surfaces available for a provider through Koil", "tags": [ "Providers" ], "description": "List surfaces available for a provider through Koil.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "providerId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "surfaceId": { "minLength": 1, "type": "string" }, "resources": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "surfaceId", "resources" ] } } }, "required": [ "data" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/publish-requests": { "post": { "operationId": "koil.publish_requests.create", "summary": "Submit one or more publish requests", "tags": [ "Publish requests" ], "description": "Submit one or more publish requests. Each item creates provider content — a post, a comment, a reply, a message — through a Connected Profile. Every item's `args` is validated against its content type's publish input first and the submission is rejected whole if any item fails; each item then runs independently with its own `pub_*` ledger entry. Requires an `Idempotency-Key`.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "publishRequests": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "contentType": { "minLength": 1, "type": "string" }, "variant": { "minLength": 1, "type": "string" }, "connectedProfileId": { "minLength": 1, "type": "string" }, "groupId": { "minLength": 1, "type": "string" }, "clientItemId": { "minLength": 1, "type": "string" }, "args": {} }, "required": [ "contentType", "connectedProfileId", "args" ] } } }, "required": [ "publishRequests" ] }, "examples": { "example1": { "value": { "publishRequests": [ { "contentType": "youtube.videos.comments", "connectedProfileId": "test_cp_4T2cgH9gnSqEb9DrntKA", "args": { "target": { "contentType": "youtube.videos.items", "externalId": "test_video_1" }, "text": "Hello from Koil" } } ] } }, "example2": { "value": { "publishRequests": [ { "contentType": "instagram.media.items", "variant": "feed", "connectedProfileId": "cp_123", "groupId": "campaign-42", "clientItemId": "draft-1", "args": { "text": "Hello world", "media": [ { "mediaId": "med_123", "altText": "A cat" } ], "scheduling": { "at": "2026-05-01T10:00:00Z" } } } ] } }, "example3": { "value": { "publishRequests": [ { "contentType": "instagram.media.comments", "connectedProfileId": "cp_123", "clientItemId": "reply-comment-456", "args": { "target": { "contentType": "instagram.media.comments", "externalId": "comment_456" }, "text": "Thanks for reaching out." } } ] } } } } }, "required": true }, "parameters": [ { "schema": { "minLength": 1, "maxLength": 255, "pattern": "\\S", "type": "string" }, "in": "header", "name": "idempotency-key", "required": true, "description": "A unique key for this request, scoped to the Organization and operation. Retrying with the same key and payload returns the first result instead of repeating the work; the same key with a different payload is refused with `409 conflict`. Keys expire 24 hours after first use, and a request still in flight after 15 minutes releases its key." } ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "publishRequests": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "description": "The call that creates the content failed ambiguously (a timeout, a dropped connection, a provider 5xx), so the provider may have published it. Koil does not retry it. Check the provider before submitting again, or the content may be published twice.", "type": "string", "enum": [ "outcome_unknown" ] } ] }, "contentType": { "minLength": 1, "type": "string" }, "variant": { "minLength": 1, "type": "string" }, "connectedProfileId": { "minLength": 1, "type": "string" }, "groupId": { "minLength": 1, "type": "string" }, "clientItemId": { "minLength": 1, "type": "string" }, "publishRequestId": { "minLength": 1, "type": "string" }, "error": {}, "statusUrl": { "minLength": 1, "type": "string" } }, "required": [ "status", "contentType", "connectedProfileId", "publishRequestId", "statusUrl" ] } } }, "required": [ "publishRequests" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "koil.publish_requests.list", "summary": "List the Organization's publish requests, newest first, optionally narrowed to one Connected Profile or status", "tags": [ "Publish requests" ], "description": "List the Organization's publish requests, newest first, optionally narrowed to one Connected Profile or status.", "parameters": [ { "schema": { "minimum": 1, "maximum": 100, "type": "integer" }, "in": "query", "name": "limit", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque cursor for fetching the next result page." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "description": "The call that creates the content failed ambiguously (a timeout, a dropped connection, a provider 5xx), so the provider may have published it. Koil does not retry it. Check the provider before submitting again, or the content may be published twice.", "type": "string", "enum": [ "outcome_unknown" ] } ] }, "in": "query", "name": "status", "required": false }, { "schema": { "minLength": 1, "type": "string" }, "in": "query", "name": "connectedProfileId", "required": false } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "publishRequestId": { "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "description": "The call that creates the content failed ambiguously (a timeout, a dropped connection, a provider 5xx), so the provider may have published it. Koil does not retry it. Check the provider before submitting again, or the content may be published twice.", "type": "string", "enum": [ "outcome_unknown" ] } ] }, "statusUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "variant": { "minLength": 1, "type": "string" }, "connectedProfileId": { "minLength": 1, "type": "string" }, "groupId": { "minLength": 1, "type": "string" }, "clientItemId": { "minLength": 1, "type": "string" }, "scheduledAt": { "minLength": 1, "type": "string" }, "workflowId": { "minLength": 1, "type": "string" }, "externalId": { "minLength": 1, "type": "string" }, "error": {}, "createdAt": { "minLength": 1, "type": "string" }, "updatedAt": { "minLength": 1, "type": "string" }, "startedAt": { "minLength": 1, "type": "string" }, "succeededAt": { "minLength": 1, "type": "string" }, "failedAt": { "minLength": 1, "type": "string" }, "cancelledAt": { "minLength": 1, "type": "string" } }, "required": [ "publishRequestId", "status", "statusUrl", "contentType", "connectedProfileId", "workflowId", "createdAt", "updatedAt" ] } }, "nextCursor": { "description": "Opaque cursor for fetching the next result page.", "minLength": 1, "type": "string" }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/publish-requests/{publishRequestId}": { "get": { "operationId": "koil.publish_requests.get", "summary": "Get one publish request and its current status", "tags": [ "Publish requests" ], "description": "Get one publish request and its current status.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "publishRequestId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "publishRequestId": { "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "description": "The call that creates the content failed ambiguously (a timeout, a dropped connection, a provider 5xx), so the provider may have published it. Koil does not retry it. Check the provider before submitting again, or the content may be published twice.", "type": "string", "enum": [ "outcome_unknown" ] } ] }, "statusUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "variant": { "minLength": 1, "type": "string" }, "connectedProfileId": { "minLength": 1, "type": "string" }, "groupId": { "minLength": 1, "type": "string" }, "clientItemId": { "minLength": 1, "type": "string" }, "scheduledAt": { "minLength": 1, "type": "string" }, "workflowId": { "minLength": 1, "type": "string" }, "externalId": { "minLength": 1, "type": "string" }, "error": {}, "createdAt": { "minLength": 1, "type": "string" }, "updatedAt": { "minLength": 1, "type": "string" }, "startedAt": { "minLength": 1, "type": "string" }, "succeededAt": { "minLength": 1, "type": "string" }, "failedAt": { "minLength": 1, "type": "string" }, "cancelledAt": { "minLength": 1, "type": "string" } }, "required": [ "publishRequestId", "status", "statusUrl", "contentType", "connectedProfileId", "workflowId", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/publish-requests/{publishRequestId}/cancel": { "post": { "operationId": "koil.publish_requests.cancel", "summary": "Cancel a publish request that has not started", "tags": [ "Publish requests" ], "description": "Cancel a publish request that has not started. A request whose provider execution has begun answers `409 conflict` with its current status.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "publishRequestId", "required": true } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "publishRequestId": { "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "scheduled" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "started" ] }, { "type": "string", "enum": [ "succeeded" ] }, { "type": "string", "enum": [ "failed" ] }, { "description": "The call that creates the content failed ambiguously (a timeout, a dropped connection, a provider 5xx), so the provider may have published it. Koil does not retry it. Check the provider before submitting again, or the content may be published twice.", "type": "string", "enum": [ "outcome_unknown" ] } ] }, "statusUrl": { "minLength": 1, "type": "string" }, "contentType": { "minLength": 1, "type": "string" }, "variant": { "minLength": 1, "type": "string" }, "connectedProfileId": { "minLength": 1, "type": "string" }, "groupId": { "minLength": 1, "type": "string" }, "clientItemId": { "minLength": 1, "type": "string" }, "scheduledAt": { "minLength": 1, "type": "string" }, "workflowId": { "minLength": 1, "type": "string" }, "externalId": { "minLength": 1, "type": "string" }, "error": {}, "createdAt": { "minLength": 1, "type": "string" }, "updatedAt": { "minLength": 1, "type": "string" }, "startedAt": { "minLength": 1, "type": "string" }, "succeededAt": { "minLength": 1, "type": "string" }, "failedAt": { "minLength": 1, "type": "string" }, "cancelledAt": { "minLength": 1, "type": "string" } }, "required": [ "publishRequestId", "status", "statusUrl", "contentType", "connectedProfileId", "workflowId", "createdAt", "updatedAt" ] } } } }, "default": { "description": "Error. `error.code` names the failure; the HTTP status follows from it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "servers": [ { "url": "https://api.koil.co" } ], "tags": [ { "name": "Auth integrations", "description": "Koil auth integrations operations." }, { "name": "Backfill requests", "description": "Koil backfill requests operations." }, { "name": "Billing", "description": "Koil billing operations." }, { "name": "Connect sessions", "description": "Koil connect sessions operations." }, { "name": "Connections", "description": "Koil connections operations." }, { "name": "Connected profiles", "description": "Koil connected profiles operations." }, { "name": "Event destinations", "description": "Koil event destinations operations." }, { "name": "Event destination types", "description": "Koil event destination types operations." }, { "name": "Media", "description": "Koil media operations." }, { "name": "Providers", "description": "Koil providers operations." }, { "name": "Publish requests", "description": "Koil publish requests operations." }, { "name": "Content: instagram", "description": "Read and act on instagram content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." }, { "name": "Content: facebook", "description": "Read and act on facebook content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." }, { "name": "Content: tiktok", "description": "Read and act on tiktok content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." }, { "name": "Content: youtube", "description": "Read and act on youtube content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." }, { "name": "Content: google_business_profile", "description": "Read and act on google_business_profile content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." }, { "name": "Content: linkedin", "description": "Read and act on linkedin content through a Connected Profile. Publishing goes through publish requests; see the provider's page for every content type and its publish `args`." } ] }