Skip to content
Influence
Esc
↑↓navigate↵open⌘Jpreview
On this page

HTTP API

Authenticate, discover tools and confirm changes through the existing HTTP API.

Send product API requests to your trusted Influence origin, such as https://influence.so. The documentation domain does not accept product API requests. Use the exact paths below without query parameters.

Create a scoped API key

In Influence settings, open Apps and automations → API keys. Choose the permissions you need and an expiry. Store the shown-once key in your secret store as PUBLISH_API_TOKEN. Send it in Authorization: Bearer …; never put it in a URL, request body or chat. Revoke it when no longer needed.

Discover tools and make a read

Set PUBLISH_API_URL to the trusted origin. These examples assume your process already has PUBLISH_API_TOKEN. accountList requires integrations:read; follow its pagination fields to retrieve further pages.

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

Request paths

Method Path Purpose
GET /api/v1/tools List the tools available to this credential.
POST /api/v1/tools/{tool}/call Call a read-only tool.
POST /api/v1/tools/{tool}/prepare Prepare an exact write without executing it.
POST /api/v1/tools/{tool}/confirm Confirm the prepared write.
POST /api/v1/media/import Confirm a prepared small binary image upload.

JSON tool requests use Content-Type: application/json and a body containing only input: {"input":{…}}. Get each tool’s input schema from the current tool catalog.

Prepare and confirm writes

  1. Send the exact business input to /prepare. A successful response has status: "confirmation_required", confirmationCapability, expiresAt, inputDigest and an optional summary.
  2. Before expiry, send the same input to /confirm. Put the returned capability in X-Publish-Confirmation and a new caller-generated key in Idempotency-Key.
  3. Keep the input, capability and key together. After an interrupted or uncertain confirmation, reuse all three for that same request. Do not prepare a replacement to recover an uncertain result.

An idempotency key contains 16–200 characters from A–Z, a–z, 0–9, ., _, : and -. Confirmation capabilities are opaque secrets. A key sent to /call or /prepare does not reserve a confirmed write.

Transport confirmation is separate from publishing approval. For publication or schedule changes, create and show the complete current review. Text publication requires a fresh approval after that review. Images and videos require the person’s visual approval in a supported review interface or signed-in Influence. A prepared review does not publish anything. Read the saved receipt before further action; needs_review requires reconciliation, not another send.

Handle errors and uncertain results

Check both the HTTP status and response body. Successful tools return {"ok":true,"toolName":"…","output":{…}}. Tool failures return {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}} and can arrive with HTTP 200. Transport failures use {"error":{"code":"…","message":"…","retryable":false}} without ok or toolName.

A 401 means authentication is required; check expiry or revocation. A missing permission needs the appropriate grant, not repeated requests. A 503 means the API is unavailable in that environment. Respect returned errors and retry guidance. A timeout does not prove that a write failed: keep its confirmation data and read current status before resubmitting. Accepted, scheduled and published are different outcomes.

Upload media

Prefer the SDK’s uploadMedia or the CLI’s media:upload for local files. They use the same multipart upload tools and preserve a stable clientKey for retries. Only a ready result with an assetId can be attached. For authorized HTTPS file references, use mediaImport; a local file path is not a download URL.

POST /api/v1/media/import supports the existing small-image transport: prepare mediaImport with the exact upload descriptor, then send the same bytes as application/octet-stream. Include X-Publish-Confirmation, Idempotency-Key and X-Publish-Upload containing the URI-encoded JSON descriptor. The bytes must match its size and SHA-256. This transport is limited to 3 MiB; use the upload helper for larger supported files. Uploading never approves publication.

Browse the API reference or download the OpenAPI specification.