Developers

Every agent is an API your apps can call.

Deploy an agent once and call it from any backend, script, workflow tool or other agent over HTTPS. BeansHost handles keys, rate limits, run records and the route to whichever cloud runs it.

Get started beanshost.yaml reference

curl -X POST "https://app.beanshost.com/api/v1/runtime/agents/$AGENT_ID/invoke?environment=production" \
  -H "Authorization: Bearer $BEANSHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

The call

One POST request per run.

Send any JSON body to the agent's endpoint. BeansHost checks the key, applies your plan's limits, forwards the body to the agent unchanged and returns its reply.

Method	`POST`
Path	`/api/v1/runtime/agents/{agentId}/invoke`
Environment	`?environment=production` or `development`, or `?environmentId=` with an ID
Auth	`Authorization: Bearer bhk_…`
Body	Any JSON, up to 1 MiB

200 OK · response body

{
  "executionId": "0b6c2f7e-6d2a-4a0e-9d55-2f4f1c9e8a10",
  "correlationId": "req_8f2d1c",
  "status": "succeeded",
  "data": { "reply": "The agent's own response" }
}

data holds exactly what your agent returned.
Responses carry x-beanshost-execution-id, x-correlation-id and a W3C traceparent header.
Your caller's credentials are never forwarded to the agent.
A timeout or unreachable agent answers { status: "failed", error }.

Connect from anywhere

Use your agent in any platform that can send an HTTPS request.

No SDK, plugin or cloud access to share. Create a key in BeansHost, add it to the platform you already use, and call the agent's endpoint. BeansHost routes the call to whichever cloud runs the agent.

01
Create a key for the agent
In the console, open Agents and choose API on the agent. Create a key limited to that agent and copy it. It is shown once.
bhk_••••7Q2f · this agent only
02
Add it to your platform
Store the key as a secret or environment variable named BEANSHOST_API_KEY, or import the agent's OpenAPI file so the endpoint and auth are filled in.
BEANSHOST_API_KEY = ••••••••
03
Call the endpoint
Send a POST with the key as a Bearer token. The agent's reply comes back with an execution ID, and the run appears in Executions and Usage.
200 OK · executionId 0b6c2f7e

Where it works

One key, any environment.

The same endpoint serves your own code, third-party tools and partner systems. Every call is authenticated, rate limited for your plan and recorded as a run, wherever it comes from.

Your backend and services

Node.js, Python, Go, Java or any language with an HTTP client. Copy the ready-made curl, JavaScript or Python call from the console.

curlJavaScriptPython

API clients such as Postman

Import the agent's OpenAPI 3.1 file. The endpoint, Bearer auth, environment parameter, request body and every error response are described for you.

OpenAPI 3.1Postman

API gateways

Put the agent behind the gateway you already run, under your own domain and policies, using the same OpenAPI description.

OpenAPI 3.1Your domain

Workflow and automation tools

Any tool with an HTTP request step can call the agent: set the method to POST, add the Authorization header and send JSON.

HTTP request stepBearer header

Other agents and AI tool calling

Offer the agent to another model or agent as a tool. The OpenAPI operation gives it a name, a description and an input schema.

Tool definitionAgent to agent

Partner and customer systems

Give a partner a key that can call one agent and nothing else, with an expiry. Revoke it at any time without touching your cloud account.

Agent-scoped keyRevocable

Keep the key on a server. An API key is a secret, so call the agent from server-side code, functions or tools that store secrets. Browser requests from other websites are blocked, so do not put a key in front-end or mobile app code.

support-triage.openapi.json · excerpt

{
  "openapi": "3.1.0",
  "info": { "title": "support-triage API", "version": "1.0.0" },
  "servers": [{ "url": "https://app.beanshost.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/v1/runtime/agents/{agentId}/invoke": {
      "post": {
        "operationId": "invokeSupportTriage",
        "parameters": [{ "name": "environment", "in": "query", "required": true }],
        "requestBody": { "description": "Passed to the agent unchanged." },
        "responses": { "200": {}, "401": {}, "429": {}, "504": {} }
      }
    }
  }
}

OpenAPI file

Import the agent instead of configuring it.

Every agent's API panel has a download for an OpenAPI 3.1 file. Import it into Postman, an API gateway, a low-code tool or an AI tool-calling setup and the integration is described for you.

Server URL, path and operation name for the agent
Bearer authentication with a BeansHost API key
The environment parameter for Development or Production
The response shape and every error status

API keys

Keys you can hand to another app safely.

Create keys from the agent's API panel or from Settings. A key made for one agent cannot call any other agent, even inside the same project.

Shown once

Keys look like bhk_ followed by 32 characters. BeansHost stores only a SHA-256 hash, so a lost key is replaced, never recovered.

Two scopes

Invoke agents calls agents. Report runs lets an agent that is called directly record its own runs.

Narrow by default

Limit a key to a project and to a single agent. Keys from Settings can cover every agent in an organization or project.

Expire and revoke

Choose 30 days, 90 days, one year or never, and revoke any key at any time. Key changes are written to the audit log.

Errors

Every answer that is not the agent's reply.

Errors are returned as problem details with a stable code, so your application can tell a missing deployment from a rate limit without parsing messages.

Status	Code	Meaning
400	`environment_required`	No environment was named.
401	`api_key_invalid`	The key is not valid, has expired or is revoked.
403	`api_key_agent_mismatch`	The key is limited to a different agent.
404	`active_deployment_not_found`	The agent is not deployed in that environment.
409	`agent_endpoint_unavailable`	The agent is still starting or has no HTTP trigger.
413	`request_too_large`	The request body is over 1 MiB.
429	`tenant_rate_limit`	The plan's calls per minute are used. Retry shortly.
429	`execution_quota_exceeded`	The plan's runs for this month are used.
502	`agent_unreachable`	The agent could not be reached.
503	`runtime_circuit_open`	Repeated failures paused calls to the agent briefly.
504	`agent_timeout`	The agent did not answer in time.

Limits follow your plan. Builder allows 60 calls per minute and 1,000 runs per month, Team 600 and 100,000, and Enterprise 3,000 calls per minute with unlimited runs. Usage resets each calendar month in UTC.

Report a run

curl -X POST "https://app.beanshost.com/api/v1/runtime/agents/$AGENT_ID/runs?environmentId=$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $BEANSHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "succeeded", "durationMs": 840}'

Only metadata is recorded: status, duration, provider, error category, byte counts and correlation IDs.

Report runs

Already calling the agent directly? Keep the record anyway.

If your product talks to the agent on its provider URL, the agent can report each run with a key that has the Report runs scope. Those runs appear in Executions and Usage next to the ones BeansHost made, labelled by source.

beanshost.yaml

Describe the agent once.

The specification lives in the root of your repository. BeansHost validates it when you connect and when you register, so problems show up before anything reaches your cloud. No file yet? BeansHost AI can write one and commit it to your branch.

apiVersion beanshost.io/v1alpha1, kind Agent
Agent names are lowercase DNS labels
Secret names are uppercase, values never live in the file
Content capture is off unless you turn it on

beanshost.yaml

apiVersion: beanshost.io/v1alpha1
kind: Agent
metadata:
  name: support-triage
  displayName: Support triage
  description: Sorts incoming support tickets by urgency.
spec:
  runtime:
    type: container
    entrypoint: app/main.py
  source:
    type: github
    repository: acme/support-triage
    branch: main
  health:
    path: /health
    timeoutSeconds: 10
  scaling:
    minimumInstances: 1
    maximumInstances: 3
    concurrency: 50
  triggers:
    - type: http
      path: /invoke
  secrets:
    - name: OPENAI_API_KEY
      reference: support-triage/openai
  resilience:
    retry:
      maximumAttempts: 3
    timeoutSeconds: 60
  governance:
    registrationRequired: true
    approvalRequiredForProduction: true
    riskClassification: medium
  observability:
    logs: true
    traces: true
    usageMetering: true
    captureContent: false

Field reference

What each section controls.

Section	What it sets
`spec.runtime`	worker for a JavaScript worker on Web-standard APIs, or container for anything built from a Dockerfile. Plus the entrypoint path in the repository.
`spec.source`	The GitHub repository in owner/name form and the branch. BeansHost pins the exact commit when you register.
`spec.health`	The path BeansHost checks before a release becomes active, with a timeout of 1 to 30 seconds.
`spec.scaling`	Minimum and maximum instances (0 to 300) and concurrency per instance (1 to 1,000).
`spec.triggers`	At least one trigger. HTTP triggers serve the agent's API. Schedule and queue triggers are accepted by the schema and are planned.
`spec.secrets`	Up to 20 environment variable names, each with a reference. Values are set in the console, never in the file.
`spec.resilience`	Retry attempts (1 to 10) and a request timeout of 1 to 300 seconds.
`spec.governance`	Risk classification from low to critical and whether production needs approval.
`spec.observability`	Logs, traces and usage metering flags. captureContent is false by default, so prompts and responses are not stored.
`spec.models`	Optional. Records the primary model and fallbacks your agent uses, for example OpenAI, Anthropic, Google, Azure OpenAI, AWS Bedrock or Cloudflare AI. Agents call their model providers directly today.

Runtimes

Bring any agent that speaks HTTP.

No agent framework is required. The agent needs an HTTP trigger for calls and a health path BeansHost can check before the release goes live.

JavaScript worker

runtime.type: worker. Built on Web-standard APIs and packaged directly from the entrypoint, with no container build.

Your Dockerfile

runtime.type: container. If the repository has a Dockerfile, BeansHost always uses it, so any language that builds into a container works.

A generated Dockerfile

No Dockerfile? BeansHost generates one for Node.js 22, or Python 3.12 with FastAPI on uvicorn, Flask on gunicorn or a plain script. Generated images listen on port 8080.

See where each provider builds and runs your agent.

Deploy targets