Agent API

The Agent API allows external systems to call agents with structured output and receive JSON responses. This is designed for backend integrations, workflows, and API consumers who need predictable, schema-validated responses.

Requirements

Agent must have Output Schema configured
Defaults to latest version (can specify other versions)
Supervisor agents are not supported (use streaming Chat API instead)

Authentication

This endpoint supports both API Key and Signed JWT authentication.

API Key (server-to-server):

curl -X POST https://service.ensembleapp.ai/api/agents/{agentId}/invoke \
  -H "x-api-key: sk_your_api_key" \
  -H "x-tenant-id: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{"message": "Find vendors for office supplies"}'

Signed JWT (frontend integrations):

curl -X POST https://service.ensembleapp.ai/api/agents/{agentId}/invoke \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Find vendors for office supplies"}'

See Authentication for details on creating API keys, signing JWTs, and choosing the right method.

Endpoints

Invoke Agent

POST /api/agents/:agentId/invoke

Request Body:

{
  "message": "string",           // Required: user message
  "dataContext": { ... },        // Optional: key/value context data
  "threadId": "string",          // Optional: for follow-up requests
  "version": "latest"            // Optional: 'latest' (default), 'published', or version number
}

Response:

{
  "data": { ... },               // Structured output matching schema
  "threadId": "string"           // Thread ID for follow-ups
}

Example:

curl -X POST https://service.ensembleapp.ai/api/agents/poem-generator/invoke \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_abc123..." \
  -H "x-tenant-id: my-tenant" \
  -d '{"message": "Write a haiku about coding"}'

{
  "data": {
    "poems": [{
      "content": "Lines of code flow fast\nBugs emerge then fade away\nShip it, hope it works",
      "style": "haiku"
    }]
  },
  "threadId": "invoke-xyz789"
}

Get Agent Schema

GET /api/agents/:agentId/schema?version=latest

Returns the output schema for an agent. Useful for understanding the expected response structure.

Query Parameters:

Parameter	Default	Description
`version`	`latest`	Version selector: `latest`, `published`, or version number (1, 2, 3...)

{
  "agentId": "poem-generator",
  "name": "Poem Generator",
  "outputSchema": {
    "type": "object",
    "properties": {
      "poems": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "content": { "type": "string" },
            "style": { "type": "string" }
          }
        }
      }
    }
  }
}

Follow-up Requests

Pass the threadId from a previous response to maintain conversation history:

# First request
curl -X POST .../api/agents/assistant/invoke \
  -d '{"message": "Find 3 vendors for office supplies"}'
# Response: { "data": {...}, "threadId": "invoke-xyz789" }

# Follow-up with context
curl -X POST .../api/agents/assistant/invoke \
  -d '{
    "message": "Filter by rating above 4.0",
    "threadId": "invoke-xyz789"
  }'

Data Context

Pass contextual data the agent can use:

curl -X POST .../api/agents/vendor-finder/invoke \
  -d '{
    "message": "Find suitable vendors",
    "dataContext": {
      "budget": 10000,
      "department": "Engineering",
      "region": "US-West"
    }
  }'

The agent can access these values in tool calls and decision-making.

Error Responses

Status	Error	Description
400	`message is required`	Missing or invalid message
400	`Agent does not have structured output`	Agent needs outputSchema
400	`Supervisor agents cannot be invoked`	Use /api/chat instead
401	`Invalid or disabled API key`	Check API key and tenant ID
404	`Agent not found`	Agent doesn't exist or version not found
500	`Internal server error`	Server-side error

On this page