Tools API

ActionKit Tools API provides our complete library of pre-built tools (actions in third-party systems) to expose as capabilities for AI agents, workflow builders, or other front-end functions that require integration data.

API Usage

Base URL

https://actionkit.useparagon.com/projects/[Project ID]

For on-premise instances

https://worker-actionkit.[On-Prem Base URL]/projects/[Project ID]

Authentication To authenticate to ActionKit API, present a Bearer token with the Paragon User Token (a JWT):

Authorization: Bearer [Paragon User Token]

This is the same token that you used to call paragon.authenticate with the Paragon SDK. See examples in Installing the SDK.

If you are using JWT Permissions to control access, your Paragon User Token must include the actionkit permission to make ActionKit API requests.

Pagination

Many list and search actions in ActionKit accept a paginationParameters object as part of the request parameters. When the result set exceeds a single page, the response includes a pageCursor (or equivalent token) that you pass in the next request to retrieve the following page. A typical pagination flow looks like this:

Call an action without any pagination parameters to get the first page.
Check the response for a pagination cursor or token (e.g. nextPageCursor).
If a cursor is present, call the action again with the cursor in paginationParameters.
Repeat until no cursor is returned.

Example: Paginating Asana projects

// First request: no pagination parameters
const firstPage = await fetch(
  `https://actionkit.useparagon.com/projects/${projectId}/actions`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "ASANA_GET_PROJECTS",
      parameters: {},
    }),
  }
);

const firstResult = await firstPage.json();
// Use firstResult.pageCursor for the next request

// Subsequent request: pass the page cursor
const nextPage = await fetch(
  `https://actionkit.useparagon.com/projects/${projectId}/actions`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "ASANA_GET_PROJECTS",
      parameters: {
        paginationParameters: {
          pageCursor: firstResult.pageCursor,
        },
      },
    }),
  }
);

Paragon standardizes vendor-specific pagination mechanics into a few patterns:

Parameter type	Description	Fields	Example integrations
Cursor-based	Receive `nextPageCursor` or `nextPageToken` and pass that field to `paginationParameters` in the next call.	`pageCursor` or `pageToken`	Asana, Confluence, Slack
Offset-based	Count the number of records received in a page and add it to a running `offset` parameter passed to `paginationParameters` in the next call.	`offset` or `skip`	Mailchimp, Sage Intacct, Zoho CRM
Page number	For each page, add 1 to a running `pageOffset` parameter passed to `paginationParameters` in the next call.	`page`, `pageNo`, `pageNumber`, or `pageOffset`	Dropbox Sign, ServiceNow, Xero

You can find the specific pagination parameters available for each action in the Actions Reference. Actions that support pagination include paginationParameters in their input schema.

File Uploads

Actions that accept a file input to upload a file to an integration (for example, Google Drive: Save File and Box: Save File) will need to be encoded as part of the JSON payload provided when the Action is run.

Hex-encode the file With the file contents you want to upload, hex-encode of the bytes file that you intend to upload.

Construct a File object A File object is a JSON object that represents a File to upload. You must provide three standard fields:

File object

{
    "dataType": "FILE", // Always set to "FILE"
    "mimeType": "text/plain", // Set to the file's known MIME type
    "data": "..." // Use the hex-encoded file data
}

Examples

Here are some end-to-end examples of uploading a file with ActionKit in a few different client languages:

import fs from 'node:fs';
const filePath = './report.pdf';
const fileBuffer = fs.readFileSync(filePath);

const body = {
    action: "GOOGLE_DRIVE_SAVE_FILE",
    parameters: {
        filename: "report.pdf",
        file: {
            mimeType: "application/pdf",
            dataType: "FILE",
            data: fileBuffer.toString('hex'),
        },
    },
};

const res = await fetch(
    `https://actionkit.useparagon.com/projects/${PROJECT_ID}/actions`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${PARAGON_USER_TOKEN}`,
        },
        body: JSON.stringify(body),
    },
);

from pathlib import Path
import json
import requests

file_path = Path("./report.pdf")
file_bytes = file_path.read_bytes()

body = {
    "action": "GOOGLE_DRIVE_SAVE_FILE",
    "parameters": {
        "filename": "report.pdf",
        "file": {
            "mimeType": "application/pdf",
            "dataType": "FILE",
            "data": file_bytes.hex(),
        },
    },
}

res = requests.post(
    f"https://actionkit.useparagon.com/projects/{PROJECT_ID}/actions",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {PARAGON_USER_TOKEN}",
    },
    data=json.dumps(body),
)

FILE_HEX="$(xxd -p -c 1000000 "./report.pdf" | tr -d '\n')"

curl "https://actionkit.useparagon.com/projects/${PROJECT_ID}/actions" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${PARAGON_USER_TOKEN}" \
    --data "$(jq -n \
        --arg data "$FILE_HEX" \
        '{
        action: "GOOGLE_DRIVE_SAVE_FILE",
        parameters: {
            filename: "report.pdf",
            file: {
            mimeType: "application/pdf",
            dataType: "FILE",
            data: $data
            }
        }
        }'
    )"

Limitations

ActionKit limits incoming request body payloads to 10 MB. Because of the required hex encoding, uploaded files are effectively limited to 5 MB. For larger file sizes, use the Proxy API to upload to the integration directly.

Using Multi-Account Authorization

Multi-Account Authorization is a set of SDK options that enables you to connect multiple accounts of the same integration type for a Connected User. You can use Multi-Account Authorization with ActionKit by specifying a credential with a header of X-Paragon-Credential.

REST API

POST https://actionkit.useparagon.com/projects/<Project ID>/tools

Authorization: Bearer <Paragon User Token>
X-Paragon-Credential: <Credential ID>

// Body
{
    "tool": "SLACK_SEND_MESSAGE",
    "parameters": {
        "channel": "#general",
        "message": "Hello world!"
    }
}

ActionKit

Triggers API

Integrations Reference

Tools API

API Usage

File Uploads

Examples

Limitations

Using Multi-Account Authorization

​API Usage

​Pagination

​File Uploads

​Examples

​Limitations

​Using Multi-Account Authorization

API Usage

Pagination

File Uploads

Examples

Limitations

Using Multi-Account Authorization