---
sidebar:
  order: 1
title: "HTTP API"
description: "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](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), 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.

```sh
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](/api-reference) or [download the OpenAPI specification](/specs/influence.openapi.json).