Skip to main content

Actors API

Actor endpoints are called through the same OpenAI-compatible inference API as provider models. From the API's perspective, an Actor is just a model ID — the CleverThis gateway handles the complexity of executing the Actor's YAML-defined graph before returning a standard chat completion response.

This section covers the API mechanics of calling Actors and the complete YAML configuration standard.

Calling an Actor​

Once an Actor is deployed to a namespace, it appears in GET /v1/models and accepts POST /v1/chat/completions requests:

curl https://api.cleverthis.com/v1/chat/completions \
  -H "Authorization: Bearer ct_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-namespace/my-actor",
    "messages": [{"role": "user", "content": "Summarize this document..."}]
  }'

The response shape is identical to a regular chat completion. Token usage in the response reflects the aggregate tokens consumed across all agent steps within the Actor.

Actor model IDs​

Actor model IDs follow the pattern {namespace-slug}/{actor-name} or whatever alias was set when the Actor was deployed. Check GET /v1/models or the Deployments page to see the exact ID.

Extended response metadata​

When calling an Actor, CleverThis adds an x-cleveractors-trace header to the response containing a trace ID. You can use this trace ID to retrieve execution details from the management API (this feature is being added).

What's in this section​

Coming soon

Actor-specific request parameters (e.g. passing context variables into the actor graph) are being designed.