Installation & Setup

Overview

Ploton is a REST API. There’s nothing to install — no packages, no dependencies, no build tools.

Environment variables

Set your API key as an environment variable. Every request needs it.

# Required — your Ploton API key
export PLOTON_API_KEY="pk_test_your_api_key_here"

# Optional — webhook signature secret (for verifying inbound webhooks)
export PLOTON_WEBHOOK_SECRET="whsec_your_webhook_secret"

Test keys vs. live keys

Test keys work for development and CI. They run the full pipeline — tool selection, workflow generation, execution — but connected services use sandbox mode where available.

Generate and manage keys from your Ploton dashboard.

Making your first request

Verify your setup with a health check:

curl https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY"

A new account returns an empty task list:

{
  "data": [],
  "has_more": false
}

If you see this, you’re connected. A 401 means the API key is wrong or missing.

Language-specific setup

Ploton works with any language. Here are minimal examples for common stacks:

Node.js / TypeScript

const PLOTON_API_KEY = process.env.PLOTON_API_KEY;
const PLOTON_BASE_URL = "https://api.ploton.ai/v1";

async function createTask(prompt: string, userId?: string) {
  const response = await fetch(`${PLOTON_BASE_URL}/tasks`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${PLOTON_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt,
      user_id: userId,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Ploton API error: ${error.error.message}`);
  }

  return response.json();
}

Python

import os
import requests

PLOTON_API_KEY = os.environ["PLOTON_API_KEY"]
PLOTON_BASE_URL = "https://api.ploton.ai/v1"

def create_task(prompt: str, user_id: str | None = None) -> dict:
    response = requests.post(
        f"{PLOTON_BASE_URL}/tasks",
        headers={
            "Authorization": f"Bearer {PLOTON_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "user_id": user_id,
        },
    )
    response.raise_for_status()
    return response.json()

cURL

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Your task prompt here",
  }'

Webhook endpoint setup

If you’re using webhooks (recommended), you need an HTTPS endpoint that accepts POST requests. During development, ngrok or localtunnel can expose your local server.

# Expose local port 3000 for webhook testing
ngrok http 3000

Copy the generated URL and set it as your webhook endpoint in the Ploton dashboard.

Next steps

• Quickstart — Create your first task end-to-end
• Authentication — API key management, OAuth, and security
• API Overview — Base URL, response format, rate limits