Quickstart

Prerequisites

• A Ploton API key (sign up at ploton.ai if you don’t have one)
• curl or any HTTP client

No dependencies, no config files, no build step.

1. Set your API key

export PLOTON_API_KEY="pk_test_your_api_key_here"

Use a test key (pk_test_...) while you’re getting started. Test keys work identically to live keys but won’t trigger real side effects on connected services.

2. Create a task

A task is one unit of work. Describe what you need in plain language.

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Look up the current weather in San Francisco and return temperature, conditions, and humidity"
  }'

Response:

{
  "id": "task_8xK2mP",
  "status": "running",
  "tool": "weather",
  "created_at": "2025-06-15T14:22:00Z"
}

Ploton picked the right tool and started working. The response comes back immediately — your agent doesn’t block.

3. Receive the webhook

When the task finishes, Ploton sends an HTTP POST to your configured webhook endpoint:

{
  "event": "task.complete",
  "task_id": "task_8xK2mP",
  "timestamp": "2025-06-15T14:22:03Z",
  "data": {
    "temperature": "62°F",
    "conditions": "Partly cloudy",
    "humidity": "73%"
  }
}

Your handler should parse the event field, process the result, and respond with a 200. If Ploton doesn’t get a 200 (or gets no response within 30 seconds), it retries with exponential backoff — up to 5 attempts over 24 hours.

POST /webhook HTTP/1.1
Content-Type: application/json
X-Ploton-Signature: <hmac-sha256-hex>

{
  "event": "task.complete",
  "task_id": "task_8xK2mP",
  "timestamp": "2025-06-15T14:22:03Z",
  "data": {
    "temperature": "62°F",
    "conditions": "Partly cloudy",
    "humidity": "73%"
  }
}

4. Check task status (alternative to webhooks)

If you’d rather poll than listen for webhooks:

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

{
  "id": "task_8xK2mP",
  "status": "complete",
  "tool": "weather",
  "created_at": "2025-06-15T14:22:00Z",
  "completed_at": "2025-06-15T14:22:03Z",
  "result": {
    "temperature": "62°F",
    "conditions": "Partly cloudy",
    "humidity": "73%"
  }
}

Task status values

5. A more realistic example

The weather task above is deliberately simple. Here’s one that involves auth, a third-party API, and structured data:

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Connect to user_123'\''s CRM account. Pull all deals in the Negotiation stage. Return deal name, amount, close date, and associated contact email.",
    "user_id": "user_123"
  }'

Ploton handles the OAuth flow with the CRM, queries the right endpoints, filters by deal stage, and returns clean JSON.

What just happened

You created a task with a natural language prompt, got structured data back via webhook, and confirmed the result by polling. Your agent didn’t need to know which API to call, which auth flow to use, or how to parse the response.

Next steps

• Trained Tasks — How tasks get smarter with every execution
• Authentication — API key management, OAuth, and security
• Prompt Engineering — Writing prompts that get reliable, structured results
• API Reference — Full REST API docs