PraloDevelopersOpenAPI 3.1

Build with Pralo

Connect your applications and AI agents to your Pralo workspace.

This reference describes the implemented interface. Endpoint availability follows deployment and workspace enablement.

Getting started

In Pralo, select your workspace and open Developers. An owner or administrator enables developer access and creates a scoped key. Use a dedicated sandbox workspace for test keys. Your workspace identity comes from your credential; never send a workspace ID.

Store keys on your server. Start with workspace:read and products:read. Requests and error responses include a request ID for support.

export PRALO_API_KEY='YOUR_TEST_KEY'
curl https://api.pralo.ai/v1/workspace \
  -H "Authorization: Bearer $PRALO_API_KEY"
const response = await fetch('https://api.pralo.ai/v1/products?limit=25', {
  headers: { Authorization: `Bearer ${process.env.PRALO_API_KEY}` }
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);
console.log(result.data.items);
import os, json, urllib.request
request = urllib.request.Request('https://api.pralo.ai/v1/products?limit=25',
    headers={'Authorization': 'Bearer ' + os.environ['PRALO_API_KEY']})
with urllib.request.urlopen(request) as response:
    print(json.load(response)['data']['items'])

Authentication & API keys

Send Authorization: Bearer followed by your Pralo key or OAuth access token. Keys are workspace, environment and permission scoped. The issuing owner/admin must remain authorized. Revocation, expiration and loss of the issuer’s workspace role prevent subsequent requests.

Keys expire after 90 days by default; the maximum is 366 days. Rotation immediately revokes the old key. Full secrets are shown once and only hashes are stored. Test keys work only in a dedicated sandbox workspace; they cannot authorize live operations. Payment writes, refunds and storefront deployment are not grantable in this release.

OAuth

Register your application and exact callback URLs in Developers → OAuth Apps. This release uses registered public clients. Copy the client ID; no client secret is required. Use Authorization Code with PKCE S256, state and a cryptographically random verifier. Dynamic registration is not available.

  1. Discover https://api.pralo.ai/.well-known/oauth-authorization-server and the target server’s protected-resource metadata.
  2. Open https://pralo.ai/developers/authorize with response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256 and resource.
  3. The user signs in, selects an owner/admin workspace, reviews permissions and approves.
  4. Verify returned state. Exchange the code at POST https://api.pralo.ai/oauth/token using form URL encoding, grant_type=authorization_code, client_id, redirect_uri, code, code_verifier and resource.

Use resource=https://mcp.pralo.ai for MCP or https://api.pralo.ai for REST. Tokens for one resource cannot be used at the other. Access tokens last one hour; refresh tokens rotate, with a 30-day absolute grant lifetime. Store the new refresh token atomically before discarding the old one. Refresh-token reuse revokes the whole connection.

curl https://api.pralo.ai/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$PRALO_CLIENT_ID" \
  --data-urlencode "refresh_token=$PRALO_REFRESH_TOKEN" \
  --data-urlencode 'resource=https://mcp.pralo.ai'

Revoke a token at POST /oauth/revoke with client_id, token and token_type_hint=access_token or refresh_token. Workspace owners can revoke the connection in Pralo. A connection does not authorize unscoped financial actions.

MCP

Add https://mcp.pralo.ai as a remote Streamable HTTP MCP server and select OAuth. Register your client callback in Pralo if your client requires a preconfigured client ID. Configuration shape depends on the client. API keys are also accepted by clients that support explicit bearer headers; never paste secrets into shared configuration.

{"mcpServers":{"pralo":{"url":"https://mcp.pralo.ai"}}}

Initialize using protocol version 2025-11-25 (2025-06-18 is also supported). POST requests accept application/json and text/event-stream; replies use JSON. This server is stateless and has no GET event stream. Initialization, discovery and execution require authentication. The tool list includes only tools authorized by your scopes.

All tools return structuredContent containing data and request_id, plus a text representation for compatible clients. Tool errors set isError. Write tools require idempotency_key; live external tools also require approval_id. Tool schemas and scope requirements appear in the generated reference below.

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"pralo_list_orders","arguments":{"status":"paid","limit":25}}}

Products & inventory

Products use Pralo’s existing workspace inventory. unit_price and retail_price are decimal amounts in the product currency, not integer minor units. Product creation starts with zero physical stock. Inventory updates require expected_stock_quantity to prevent lost updates. Reserved/committed stock cannot be overwritten.

curl https://api.pralo.ai/v1/products \
  -H "Authorization: Bearer $PRALO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: catalog_import_000001' \
  --data '{"name":"Sandbox item","sku":"TEST-001","currency":"USD","unit_price":5}'

Lists use limit (1–100) and next_cursor. Pass next_cursor as cursor on the next request. Treat cursors as opaque IDs; ordering is stable by ID, not creation time.

Orders, checkout & payments

Read orders and payment status from existing Pralo commerce. Order and payment amounts use integer currency minor units. Order reads include fulfillment_status and shipped_at from existing shipment records. Unknown means no conclusive record; it must not be presented as proof that an order has not shipped. POST /v1/orders requires orders:write plus checkout:create and uses the same checkout operation. Checkout requires a cart already created through the existing storefront and a storefront in the same workspace. It applies existing stock, merchant binding, return-origin and payment-mode rules.

A checkout URL is not proof of payment, delivery or settlement. GET /v1/checkout/{id} uses the returned order ID. Payment reads describe existing checkout intents; they do not grant processor access. Refunds, transfers, payment writes and settlement actions are not exposed. Sandbox checkout works only when the existing storefront has a configured TEST payment binding; it is never silently switched to live.

Customers & conversations

Customers are existing workspace contacts. Search by partial name or exact email. Customer writes require customers:write; MCP currently supports read/search. Conversations are restricted to supported shared messaging channels. Private email-account threads are excluded from this interface. List and get responses expose a minimal conversation summary, not private message bodies.

Agents

Create draft agents in the existing Pralo catalog, then provision their Connections runtime through Pralo. Live developer runs ask knowledge-only questions through that runtime. They do not authorize arbitrary tools, billing actions or outbound messaging. Test runs are explicitly simulated without calling a model and are recorded in usage and logs. Agent creation does not itself provision an external runtime.

Messaging & approvals

Email, WhatsApp and SMS use the workspace’s existing Pralo integrations and account permissions. A send response means accepted or simulated; delivered is false until a separate provider delivery event proves delivery. Test-mode messages are simulated and never sent to providers.

Live messages, agent runs and checkout require external actions enabled plus an owner/admin approval in Developers → Logs. Select the credential and operation, review exact input, and obtain a five-minute approval ID. Send it as X-Pralo-Approval (REST) or approval_id (MCP). Approvals are bound to one credential, workspace, operation and normalized input and are consumed once. Permission scopes are also checked. Supply all defaulted input fields shown by the schema so the approved payload matches execution.

Storefronts & analytics

Storefront reads expose names, domains, environment and status from existing Pralo websites. Deployment is not exposed because the existing release approval and customer-source checks must remain authoritative. Analytics supports from/to UTC timestamps, an optional website_id and a maximum 93-day range. Totals are grouped by currency. Large ranges return an explicit error instead of silently truncating results.

Webhooks

Add an HTTPS endpoint and select events in Developers → Webhooks. Save the signing secret when it is shown once. Endpoint URLs must resolve to public addresses. Redirects are not followed. Payloads contain a stable event ID, type, workspace ID, timestamp and minimal resource identifiers; fetch authorized details through the API.

Verify Pralo-Signature before parsing or acting. Its format is t=TIMESTAMP,v1=HEX. Compute HMAC-SHA256 over TIMESTAMP + "." + the exact raw request body using the signing secret. Reject timestamps more than five minutes from your clock and compare signatures in constant time. Deduplicate by event ID and return 2xx promptly after durably recording the event.

import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody: Buffer, header: string, secret: string) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header);
  if (!match || Math.abs(Date.now()/1000 - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Deliveries retry up to eight attempts with exponential backoff. Retry and replay preserve event IDs. History exposes attempt count, response status and sanitized failure details. GET /v1/webhooks/deliveries includes the event resource ID so public clients can verify receipts for their own changes. Disable endpoints to stop new delivery claims; a request already in flight may finish. Manual replay queues another attempt and receivers must still deduplicate. Test events and simulated message events must not be treated as proof of real provider delivery.

Errors

{"error":{"code":"insufficient_scope","message":"Credential lacks the required scope."},"request_id":"..."}

Use status and error.code for decisions; messages may change. Common statuses: 400 invalid input, 401 invalid/expired/revoked credential, 402 insufficient credits, 403 denied permission/approval, 404 unavailable resource, 409 idempotency/stock conflict, 429 rate limit and 503 uncertain/unavailable service. Never retry an uncertain side effect with a new idempotency key. Retain its request ID for reconciliation.

Rate limits

Limits apply by workspace, credential, OAuth application and operation. Expensive agent/messaging requests have a separate shared limit. Responses include RateLimit-Remaining and RateLimit-Reset (Unix seconds). On 429, respect Retry-After and use exponential backoff with jitter. Limits are centrally configurable; do not hardcode a presumed plan allowance.

Idempotency

Every POST/PATCH business operation requires a 16–128 character Idempotency-Key containing letters, digits, underscores or hyphens. MCP uses idempotency_key. Scope is workspace + credential + operation. Identical retries return the stored response without another business action or charge; changed input returns a conflict. A retry may have a new X-Request-ID header while its stored body retains the original request ID. Concurrent in-progress requests return a conflict and must be retried with the same key.

Timeouts or unclear external outcomes retain the request and credit reservation for operator reconciliation. There is no automatic rerun of an uncertain financial or messaging action. Never use a new key to bypass an uncertain result.

Usage & credits

REST, MCP and protocol control operations are attributed to the authorized workspace and credential/application. Usage reuses the existing Pralo credit wallet, ledger and usage records. No second subscription is created. GET /v1/usage reports monthly included, purchased, used, available and reserved credits. GET /v1/usage/events normalizes existing API, MCP, agent and SMS provider records. Legacy records may have no developer credential; provider cost remains separate from customer credit charges.

Operation pricing is centrally configured and disabled by default. Example prices are not active billing. Existing subscription and credit-pack flows remain authoritative. Successful priced operations settle a reservation once; definite rejected operations release it; uncertain external outcomes retain it. Overages are not activated. Provider cost and variable model usage must be reconciled before enabling paid external operations. Sandbox operations do not debit real credits.

SDK readiness

Download the generated OpenAPI 3.1 specification. Stable operation IDs, typed envelopes and strict resource schemas support future TypeScript and Python SDK generation. No SDK package is published by this change. Keep credentials server-side, propagate request IDs, implement cursor iteration and preserve idempotency keys across retries.

The reference is generated from the runtime operation registry. Run npm run docs:developers after schema changes and npm run docs:developers:check in CI. This directory is a standalone static site suitable for developers.pralo.ai.

API reference

Generated from the same schemas used by REST and MCP. Every response wraps the output below in { data, request_id }.

GET /v1/workspace

Read the authorized workspace.

workspace:read · READ · MCP: pralo_get_workspace

Input schema
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": [
        "string",
        "null"
      ]
    },
    "environment": {
      "type": "string",
      "enum": [
        "test",
        "live"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "environment"
  ],
  "additionalProperties": false
}

GET /v1/commissions

Read append-only commission accruals and refund adjustments in minor currency units. These are not payout confirmations.

analytics:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "beneficiary_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "website_id": {
            "type": "string",
            "format": "uuid"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "beneficiary_id": {
            "type": "string",
            "format": "uuid"
          },
          "award_id": {
            "type": "string",
            "format": "uuid"
          },
          "currency": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer"
          },
          "refunded_amount": {
            "type": "integer"
          },
          "entry_type": {
            "type": "string",
            "enum": [
              "accrual",
              "refund_adjustment"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "website_id",
          "order_id",
          "beneficiary_id",
          "award_id",
          "currency",
          "amount_minor",
          "refunded_amount",
          "entry_type",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/commissions/:id

Read one commission entry referenced by a commission.entry.created webhook.

analytics:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "beneficiary_id": {
      "type": "string",
      "format": "uuid"
    },
    "award_id": {
      "type": "string",
      "format": "uuid"
    },
    "currency": {
      "type": "string"
    },
    "amount_minor": {
      "type": "integer"
    },
    "refunded_amount": {
      "type": "integer"
    },
    "entry_type": {
      "type": "string",
      "enum": [
        "accrual",
        "refund_adjustment"
      ]
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "website_id",
    "order_id",
    "beneficiary_id",
    "award_id",
    "currency",
    "amount_minor",
    "refunded_amount",
    "entry_type",
    "created_at"
  ],
  "additionalProperties": false
}

GET /v1/referral-members

Read affiliate and sales rep identities for this workspace.

analytics:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "affiliate",
              "sales_rep"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "kind",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/products

List products in this workspace with cursor pagination.

products:read · READ · MCP: pralo_list_products

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "unit_price": {
            "type": "number"
          },
          "retail_price": {
            "type": [
              "number",
              "null"
            ]
          },
          "stock_quantity": {
            "type": "integer"
          },
          "committed_stock": {
            "type": "integer"
          },
          "is_active": {
            "type": "boolean"
          },
          "website_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "sku",
          "description",
          "currency",
          "unit_price",
          "retail_price",
          "stock_quantity",
          "committed_stock",
          "is_active",
          "website_id",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/products/:id

Read one product in this workspace.

products:read · READ · MCP: pralo_get_product

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "sku": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "type": "string"
    },
    "unit_price": {
      "type": "number"
    },
    "retail_price": {
      "type": [
        "number",
        "null"
      ]
    },
    "stock_quantity": {
      "type": "integer"
    },
    "committed_stock": {
      "type": "integer"
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "sku",
    "description",
    "currency",
    "unit_price",
    "retail_price",
    "stock_quantity",
    "committed_stock",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/orders

List orders in this workspace with cursor pagination.

orders:read · READ · MCP: pralo_list_orders

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "maxLength": 40
    },
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "website_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "customer_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "subtotal_amount": {
            "type": "number"
          },
          "total_amount": {
            "type": "number"
          },
          "paid_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "fulfillment_status": {
            "type": "string",
            "enum": [
              "unknown",
              "needs_label",
              "label_ready",
              "shipped"
            ]
          },
          "shipped_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "website_id",
          "customer_email",
          "status",
          "currency",
          "subtotal_amount",
          "total_amount",
          "paid_at",
          "fulfillment_status",
          "shipped_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/orders/:id

Read one order in this workspace.

orders:read · READ · MCP: pralo_get_order

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "customer_email": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "subtotal_amount": {
      "type": "number"
    },
    "total_amount": {
      "type": "number"
    },
    "paid_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "fulfillment_status": {
      "type": "string",
      "enum": [
        "unknown",
        "needs_label",
        "label_ready",
        "shipped"
      ]
    },
    "shipped_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "website_id",
    "customer_email",
    "status",
    "currency",
    "subtotal_amount",
    "total_amount",
    "paid_at",
    "fulfillment_status",
    "shipped_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/customers

List customers in this workspace with cursor pagination.

customers:read · READ · MCP: pralo_list_customers

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "full_name": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsapp_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "is_active": {
            "type": "boolean"
          },
          "website_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "full_name",
          "email",
          "whatsapp_number",
          "tags",
          "is_active",
          "website_id",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/customers/:id

Read one customer in this workspace.

customers:read · READ · MCP: pralo_get_customer

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "full_name": {
      "type": "string"
    },
    "email": {
      "type": [
        "string",
        "null"
      ]
    },
    "whatsapp_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "full_name",
    "email",
    "whatsapp_number",
    "tags",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/agents

List agents in this workspace with cursor pagination.

agents:read · READ · MCP: pralo_list_agents

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "status",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/agents/:id

Read one agent in this workspace.

agents:read · READ · MCP: pralo_get_agent

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/conversations

List conversations in this workspace with cursor pagination.

conversations:read · READ · MCP: pralo_list_conversations

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "last_message_at": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "channel",
          "status",
          "last_message_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/conversations/:id

Read one conversation in this workspace.

conversations:read · READ · MCP: pralo_get_conversation

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "channel": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "last_message_at": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "channel",
    "status",
    "last_message_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/payments

List payments in this workspace with cursor pagination.

payments:read · READ · MCP: pralo_list_payments

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "website_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "total_amount": {
            "type": "number"
          },
          "refunded_amount": {
            "type": "number"
          },
          "paid_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "order_id",
          "website_id",
          "status",
          "currency",
          "total_amount",
          "refunded_amount",
          "paid_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/payments/:id

Read one payment in this workspace.

payments:read · READ · MCP: pralo_get_payment

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "order_id": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "total_amount": {
      "type": "number"
    },
    "refunded_amount": {
      "type": "number"
    },
    "paid_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "order_id",
    "website_id",
    "status",
    "currency",
    "total_amount",
    "refunded_amount",
    "paid_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/storefronts

List storefronts in this workspace with cursor pagination.

storefronts:read · READ · MCP: pralo_list_storefronts

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "primary_domain": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "environment": {
            "type": "string"
          },
          "default_currency": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "slug",
          "primary_domain",
          "status",
          "environment",
          "default_currency",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/storefronts/:id

Read one storefront in this workspace.

storefronts:read · READ · MCP: pralo_get_storefront

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "primary_domain": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "environment": {
      "type": "string"
    },
    "default_currency": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "primary_domain",
    "status",
    "environment",
    "default_currency",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

POST /v1/products

Create a canonical workspace inventory product. Stock starts at zero.

products:write · WRITE · MCP: pralo_create_product

Input schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "sku": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 4000
        },
        {
          "type": "null"
        }
      ]
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "default": "USD"
    },
    "unit_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000000,
      "default": 0
    },
    "retail_price": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 10000000
        },
        {
          "type": "null"
        }
      ]
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "is_active": {
      "type": "boolean"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "sku": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "type": "string"
    },
    "unit_price": {
      "type": "number"
    },
    "retail_price": {
      "type": [
        "number",
        "null"
      ]
    },
    "stock_quantity": {
      "type": "integer"
    },
    "committed_stock": {
      "type": "integer"
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "sku",
    "description",
    "currency",
    "unit_price",
    "retail_price",
    "stock_quantity",
    "committed_stock",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

PATCH /v1/products/:id

Update product details without modifying stock reservations.

products:write · WRITE · MCP: pralo_update_product

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "sku": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "description": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 4000
        },
        {
          "type": "null"
        }
      ]
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "default": "USD"
    },
    "unit_price": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000000,
      "default": 0
    },
    "retail_price": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 10000000
        },
        {
          "type": "null"
        }
      ]
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "is_active": {
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "sku": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "type": "string"
    },
    "unit_price": {
      "type": "number"
    },
    "retail_price": {
      "type": [
        "number",
        "null"
      ]
    },
    "stock_quantity": {
      "type": "integer"
    },
    "committed_stock": {
      "type": "integer"
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "sku",
    "description",
    "currency",
    "unit_price",
    "retail_price",
    "stock_quantity",
    "committed_stock",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/inventory

Read physical and reserved inventory quantities.

inventory:read · READ · MCP: pralo_get_inventory

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "stock_quantity": {
            "type": "integer"
          },
          "committed_stock": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "sku",
          "stock_quantity",
          "committed_stock",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

PATCH /v1/inventory/:id

Set physical stock only if expected stock still matches. Reserved stock remains protected.

inventory:write · WRITE · MCP: pralo_update_inventory

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "stock_quantity": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "expected_stock_quantity": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    }
  },
  "required": [
    "id",
    "stock_quantity",
    "expected_stock_quantity"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "sku": {
      "type": [
        "string",
        "null"
      ]
    },
    "stock_quantity": {
      "type": "integer"
    },
    "committed_stock": {
      "type": "integer"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "sku",
    "stock_quantity",
    "committed_stock",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

POST /v1/customers

Create a workspace customer.

customers:write · WRITE

Input schema
{
  "type": "object",
  "properties": {
    "full_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "format": "email",
          "maxLength": 254
        },
        {
          "type": "null"
        }
      ]
    },
    "whatsapp_number": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{7,14}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 30
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "full_name"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "full_name": {
      "type": "string"
    },
    "email": {
      "type": [
        "string",
        "null"
      ]
    },
    "whatsapp_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "full_name",
    "email",
    "whatsapp_number",
    "tags",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

PATCH /v1/customers/:id

Update customer contact details.

customers:write · WRITE

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "full_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "email": {
      "anyOf": [
        {
          "type": "string",
          "format": "email",
          "maxLength": 254
        },
        {
          "type": "null"
        }
      ]
    },
    "whatsapp_number": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\+[1-9]\\d{7,14}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 50
      },
      "maxItems": 30
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "full_name": {
      "type": "string"
    },
    "email": {
      "type": [
        "string",
        "null"
      ]
    },
    "whatsapp_number": {
      "type": [
        "string",
        "null"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "is_active": {
      "type": "boolean"
    },
    "website_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "full_name",
    "email",
    "whatsapp_number",
    "tags",
    "is_active",
    "website_id",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

GET /v1/customers/search

Search customers by name or exact email.

customers:read · READ · MCP: pralo_search_customers

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  },
  "required": [
    "search"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "full_name": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "whatsapp_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "is_active": {
            "type": "boolean"
          },
          "website_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "full_name",
          "email",
          "whatsapp_number",
          "tags",
          "is_active",
          "website_id",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

POST /v1/agents

Create a draft in the existing agent catalog. Provision its Connections runtime in Pralo before running.

agents:write · WRITE · MCP: pralo_create_agent

Input schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "instructions": {
      "type": "string",
      "maxLength": 4000,
      "default": ""
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

POST /v1/agents/:id/run

Ask a provisioned agent a knowledge-only question. Does not authorize tool actions or sending messages.

agents:run · EXTERNAL_ACTION · MCP: pralo_run_agent

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 8000
    }
  },
  "required": [
    "id",
    "message"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "reply": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "simulated"
      ]
    },
    "simulated": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "reply",
    "status",
    "simulated"
  ],
  "additionalProperties": false
}

POST /v1/messages/email

Send email through the existing Pralo integration after owner approval. Test mode simulates delivery.

messages:email · EXTERNAL_ACTION · MCP: pralo_send_email

Input schema
{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "format": "uuid"
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      },
      "minItems": 1,
      "maxItems": 25
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50000
    }
  },
  "required": [
    "account_id",
    "to",
    "subject",
    "body"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "simulated": {
      "type": "boolean"
    },
    "delivered": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "id",
    "status",
    "simulated",
    "delivered"
  ],
  "additionalProperties": false
}

POST /v1/messages/whatsapp

Send whatsapp through the existing Pralo integration after owner approval. Test mode simulates delivery.

messages:whatsapp · EXTERNAL_ACTION · MCP: pralo_send_whatsapp

Input schema
{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "format": "uuid"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    }
  },
  "required": [
    "conversation_id",
    "text"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "simulated": {
      "type": "boolean"
    },
    "delivered": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "id",
    "status",
    "simulated",
    "delivered"
  ],
  "additionalProperties": false
}

POST /v1/messages/sms

Send sms through the existing Pralo integration after owner approval. Test mode simulates delivery.

messages:sms · EXTERNAL_ACTION · MCP: pralo_send_sms

Input schema
{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{7,14}$"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1600
    }
  },
  "required": [
    "to",
    "text"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "simulated": {
      "type": "boolean"
    },
    "delivered": {
      "type": "boolean",
      "const": false
    }
  },
  "required": [
    "id",
    "status",
    "simulated",
    "delivered"
  ],
  "additionalProperties": false
}

POST /v1/checkout

Create checkout using an existing cart and Pralo checkout rules. No charge is made by this operation.

checkout:create · EXTERNAL_ACTION · MCP: pralo_create_checkout

Input schema
{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "cart_id": {
      "type": "string",
      "format": "uuid"
    },
    "return_origin": {
      "type": "string",
      "format": "uri"
    },
    "success_path": {
      "type": "string",
      "maxLength": 300
    },
    "cancel_path": {
      "type": "string",
      "maxLength": 300
    }
  },
  "required": [
    "website_id",
    "cart_id",
    "return_origin"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string"
    },
    "url": {
      "type": [
        "string",
        "null"
      ]
    },
    "storefront_id": {
      "type": "string",
      "format": "uuid"
    },
    "payment_mode": {
      "type": "string",
      "enum": [
        "TEST",
        "PRODUCTION"
      ]
    }
  },
  "required": [
    "id",
    "status",
    "url",
    "storefront_id",
    "payment_mode"
  ],
  "additionalProperties": false
}

GET /v1/checkout/:id

Read a checkout using its order ID.

checkout:read · READ · MCP: pralo_get_checkout

Input schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string"
    },
    "url": {
      "type": [
        "string",
        "null"
      ]
    },
    "storefront_id": {
      "type": "string",
      "format": "uuid"
    },
    "payment_mode": {
      "type": "string",
      "enum": [
        "TEST",
        "PRODUCTION"
      ]
    }
  },
  "required": [
    "id",
    "status",
    "url",
    "storefront_id",
    "payment_mode"
  ],
  "additionalProperties": false
}

POST /v1/orders

Create an order through checkout from an existing cart; also requires checkout:create.

orders:write · EXTERNAL_ACTION

Input schema
{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "string",
      "format": "uuid"
    },
    "cart_id": {
      "type": "string",
      "format": "uuid"
    },
    "return_origin": {
      "type": "string",
      "format": "uri"
    },
    "success_path": {
      "type": "string",
      "maxLength": 300
    },
    "cancel_path": {
      "type": "string",
      "maxLength": 300
    }
  },
  "required": [
    "website_id",
    "cart_id",
    "return_origin"
  ],
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string"
    },
    "url": {
      "type": [
        "string",
        "null"
      ]
    },
    "storefront_id": {
      "type": "string",
      "format": "uuid"
    },
    "payment_mode": {
      "type": "string",
      "enum": [
        "TEST",
        "PRODUCTION"
      ]
    }
  },
  "required": [
    "id",
    "status",
    "url",
    "storefront_id",
    "payment_mode"
  ],
  "additionalProperties": false
}

GET /v1/analytics

Summarize orders by currency over at most 93 days.

analytics:read · READ · MCP: pralo_get_analytics

Input schema
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "format": "date-time"
    },
    "to": {
      "type": "string",
      "format": "date-time"
    },
    "website_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "from": {
      "type": "string"
    },
    "to": {
      "type": "string"
    },
    "currencies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string"
          },
          "orders": {
            "type": "number"
          },
          "paid_orders": {
            "type": "number"
          },
          "paid_amount": {
            "type": "number"
          }
        },
        "required": [
          "currency",
          "orders",
          "paid_orders",
          "paid_amount"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "from",
    "to",
    "currencies"
  ],
  "additionalProperties": false
}

GET /v1/usage

Read the existing Pralo credit wallet and current month usage. No new subscription is created.

usage:read · READ

Input schema
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "monthly_included_credits": {
      "type": "number"
    },
    "purchased_credits": {
      "type": "number"
    },
    "used_credits": {
      "type": "number"
    },
    "remaining_credits": {
      "type": "number"
    },
    "reserved_credits": {
      "type": "number"
    },
    "pricing_active": {
      "type": "boolean"
    }
  },
  "required": [
    "monthly_included_credits",
    "purchased_credits",
    "used_credits",
    "remaining_credits",
    "reserved_credits",
    "pricing_active"
  ],
  "additionalProperties": false
}

GET /v1/logs

Read sanitized developer request logs. Credentials and request bodies are never returned.

logs:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "operation": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "status": {
            "type": "number"
          },
          "latency_ms": {
            "type": "number"
          },
          "credits": {
            "type": "number"
          },
          "error_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "operation",
          "method",
          "endpoint",
          "status",
          "latency_ms",
          "credits",
          "error_code",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/webhooks/deliveries

Read developer webhook delivery receipts without signing material or response bodies.

webhooks:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "format": "uuid"
    },
    "event_type": {
      "type": "string",
      "maxLength": 100
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "resource_id": {
            "type": "string",
            "format": "uuid"
          },
          "webhook_id": {
            "type": "string",
            "format": "uuid"
          },
          "event_id": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attempt_count": {
            "type": "integer"
          },
          "response_status": {
            "type": [
              "number",
              "null"
            ]
          },
          "next_attempt_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "delivered_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "resource_id",
          "webhook_id",
          "event_id",
          "event_type",
          "status",
          "attempt_count",
          "response_status",
          "next_attempt_at",
          "delivered_at",
          "last_error",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}

GET /v1/usage/events

Read a shared, sanitized usage view across existing Pralo API, MCP, agent and provider records.

usage:read · READ

Input schema
{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "maxLength": 100
    }
  },
  "additionalProperties": false
}
Output data schema
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "operation": {
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "credits": {
            "type": "number"
          },
          "provider_cost": {
            "type": [
              "number",
              "null"
            ]
          },
          "provider_currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "credential_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "developer_app_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "source",
          "operation",
          "quantity",
          "credits",
          "provider_cost",
          "provider_currency",
          "credential_id",
          "developer_app_id",
          "created_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "items",
    "next_cursor"
  ],
  "additionalProperties": false
}