Deploy your AI agents via API

The DeskFerry API uses bearer token authentication. You generate an API key from inside your DeskFerry workspace, then include it on every request as an Authorization header in the form 'Authorization: Bearer YOUR_API_KEY'. Keys are scoped to your workspace, so anything the key can do maps to the permissions you grant it — you can issue separate keys for different environments (development, staging, production) or for different services, and revoke any one of them independently without affecting the others. Treat your API key like a password: keep it in a secret manager or environment variable rather than committing it to source control, and rotate it if you suspect it has been exposed. Because authentication is a single header, you can call the API from any language or runtime that can make an HTTPS request — cURL, Python, Node.js, or your own backend.

You trigger an agent by sending an authenticated POST request to the agent run endpoint with a JSON body that identifies which agent to run and the input it should work with. The input is a flexible JSON object, so you can pass structured data — a lead record, a support ticket, a document, or any other payload your agent expects. The API returns a task identifier and a status you can use to track the run. From there the agent executes its configured tools and logic, and you receive the result either synchronously in the response or via a webhook once the work completes. Because triggering is just an HTTP call, you can fire agents from a backend service, a cron job, a webhook handler, or any event in your own systems — no complex SDK or infrastructure setup is required.

Responses are returned as JSON. When you trigger an agent, the response includes a task identifier and a status field (for example running, completed, or failed) so your code can tell where the run stands. For quick tasks you can read the result directly from the response; for longer-running work, you can register a webhook so DeskFerry posts the completed result back to a URL you control the moment the agent finishes, rather than making you poll. This lets you build event-driven automations: kick off an agent from your app, keep serving your users, and handle the result asynchronously when it arrives. Webhook payloads are also JSON and carry the same task identifier so you can correlate the callback with the request that started it.

Yes — like most production APIs, the DeskFerry API applies rate limits to keep the platform stable and fair for everyone. Limits are tied to your plan, and the infrastructure is built to scale from a prototype making a handful of calls to production systems handling high request volumes. If you exceed your limit, the API responds with a standard rate-limit status code so your client can detect it and back off. The recommended pattern is to handle that response gracefully with exponential backoff and retries, and to batch or queue work on your side when you expect bursts. If you anticipate sustained high throughput or need higher limits for a large rollout, reach out and we can discuss capacity for your workload.

Because the DeskFerry API is a standard RESTful HTTP API that speaks JSON, you can call it from virtually any language or platform that can make an HTTPS request — including cURL from the command line, Python, JavaScript and TypeScript on Node.js, Go, Ruby, PHP, Java, and more. You do not need a proprietary client library to get started: a single POST request with your API key and a JSON body is enough to trigger an agent. This keeps integration lightweight and avoids vendor lock-in, so you can wire DeskFerry into an existing backend, a serverless function, or a data pipeline using the same HTTP tooling you already use. Our documentation includes ready-to-copy examples in cURL, Python, JavaScript, and TypeScript to help you get running quickly.

The API uses conventional HTTP status codes to signal the outcome of a request, so your existing error-handling patterns apply. Success codes in the 2xx range mean the request was accepted, 4xx codes indicate a problem with the request itself (such as a missing or invalid API key, a malformed body, or an unknown agent), and 5xx codes indicate a transient server-side issue you can safely retry. Error responses are returned as JSON with a message describing what went wrong, so you can log it, surface it to your own users, or branch on it in code. A robust integration checks the status code on every call, retries idempotent operations with backoff on transient failures and rate limits, validates input before sending, and never assumes a request succeeded without inspecting the response.