Agent Runtime API overview
The UpServe Agent Runtime API is a server-to-server REST API that lets external systems call published AI employees (Deployments) and published workflows. Use it when an internal system, a batch job, or a backend service needs to hand work to an UpServe AI employee and collect the result.
This is not an OpenAI-compatible API. There is no OpenAI style chat completions path, and the request and response formats differ. Changing the base URL of an OpenAI SDK will not work.
Private Beta notice
- This API is in Private Beta. Only approved Projects can call it. For any other Project, every path answers
404 NOT_FOUND. - The contract (paths, fields, limits) may change during the Beta. Changes are recorded in the changelog.
- It is not meant to be called directly from a browser or a mobile app. Keep API keys on your servers only.
Basics
| Item | Value |
|---|---|
| Base URL | https://api.upserve.app/v1 |
| Authentication | Authorization: Bearer up_... (API key) |
| Format | JSON (multipart only for file uploads) |
| Contract source | openapi.json |
The OpenAPI file is the source of truth for request and response schemas of the public /v1 paths. If this documentation and the file disagree, the file wins.
Core concepts
| Concept | Description |
|---|---|
| Project | The unit of access owned by an organization. API keys, Deployments, webhooks, and budget limits belong to a Project. |
| API key | A credential that belongs to a Project. It carries allowed scopes and the list of Deployments and workflows it may call. |
| Deployment | An organization’s AI employee published and frozen at a point in time. Editing the original employee does not change a published Deployment. |
| Session | A conversation with one Deployment. Earlier turns carry over within the same Session. |
| Turn | One input sent to a Session and its execution. A Session runs only one Turn at a time. |
| Workflow | The order and conditions of work that the organization has published. Its published version and input schema are fixed. |
| Run | One execution of a published workflow. It passes through several steps to produce results. |
| Artifact | A file produced by an execution. You download it through a short-lived URL. |
| Event | A record that reports the progress of a Turn or Run. Polling, SSE, and webhooks all use the same records. |
Where to start
- Get your first Turn in 15 minutes with the quickstart.
- Learn how to handle keys in authentication.
- For conversational calls read Sessions and Turns. For workflow calls read Workflows and Runs.
- Before going to production, read events, webhooks, errors, and limits and data.
- To build a new organization team from a work description, read organization works.
When an AI tool writes the integration
If an AI coding tool will read this API and write the calling code, have it read llms.txt first. It collects in one short file the basics, the order of running, checking, reading results and canceling, the rules that prevent duplicate work and cost, and what the API cannot do now. This documentation and openapi.json remain the source of the detailed contract.
Have it decide whether to run a failed execution again with the per-code next step table in errors. It is safer to have a person confirm decisions that cost money again and budget changes.