Call the API

Run an agent from your application server with a small REST request.

Use the API when your backend, workflow, or custom UI needs to call an agent directly. Server-side API calls use secret API keys and project headers.

Run an Agent

curl https://api.fluo.one/api/v1/agents/agent_123/run \
  -X POST \
  -H "content-type: application/json" \
  -H "x-project-id: project_123" \
  -H "x-api-key: $FLUO_API_KEY" \
  -d '{
    "query": "Summarize the refund policy for a customer."
  }'

The response is the agent's final output.

JavaScript Example

const response = await fetch("https://api.fluo.one/api/v1/agents/agent_123/run", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-project-id": process.env.FLUO_PROJECT_ID!,
    "x-api-key": process.env.FLUO_API_KEY!,
  },
  body: JSON.stringify({
    query: "Write a concise answer about the refund policy.",
  }),
});

if (!response.ok) {
  throw new Error(`Fluo request failed: ${response.status}`);
}

const output = await response.text();

Server-side only:

Secret API keys belong on your server. If you are building a browser widget, use the embed flow instead.

Request Body

FieldTypeDescription
querystringThe user request or task for the agent.
imagesstring[]Optional image URLs the agent can inspect.
documentsstring[]Optional document URLs the agent can inspect.
audiosstring[]Optional audio URLs the agent can inspect.
contextsstring[]Optional context IDs to make available during the run.
metadataobjectOptional structured metadata for your application.

When To Use Threads

Use a one-off run when the request is stateless. Use Streaming Threads when you need:

  • Multi-turn chat history.
  • Token-by-token streaming.
  • A UI that shows tool activity or progress.
  • A thread ID that can continue later.