Create Agent Version — API

Create a new version of an agent definition. Accepts agent name, language, system prompt, commit message, and provider config. Returns the new version object.

POST https://api.futureagi.com/simulate/agent-definitions/{agent_id}/versions/create/

Authentication

X-Api-Key API Key Required

Your Future AGI API key used to authenticate requests. You can find and manage your API keys in the Dashboard under Settings.

X-Secret-Key Secret Key Required

Your Future AGI secret key, used alongside the API key for request authentication. This is generated when you create an API key in the Dashboard.

Path parameters

agent_id UUID Required

The agent definition ID.

Request body

All fields are optional. Omitted fields inherit values from the current agent definition.

agent_type string Optional

The agent type. Must be "voice" or "text".

agent_name string Optional

Updated display name for the agent.

provider string Optional

Voice provider. One of "vapi", "retell", "eleven_labs", "livekit", "livekit_bridge", or "others".

api_key string Optional

API key for the external voice provider.

assistant_id string Optional

Assistant identifier from the external provider.

description string Optional

Description for this version.

language string Optional

Primary language as an ISO 639-1 code (e.g., "en", "es").

knowledge_base string Optional

UUID of a knowledge base to link. Pass null to remove.

contact_number string Optional

Phone number with country code prefix. Must be 10-12 digits.

inbound boolean Optional

Whether the agent handles inbound calls.

commit_message string Optional

Commit message describing the changes in this version. Defaults to an empty string.

observability_enabled boolean Optional

Toggle provider observability integration.

model string Optional

The AI model identifier to use for this agent version (e.g., "gpt-4o", "claude-3-opus").

model_details object Optional

Extended model configuration options, such as temperature, max tokens, or other provider-specific settings.

authentication_method string Optional

The authentication method used for provider communication (e.g., "api_key").

languages array of strings Optional

A list of supported language codes (e.g., ["en", "es", "fr"]). Use this when the agent supports multiple languages.

Response

201 Created
message string
Confirmation message.
version object

The newly created agent version.

id string
UUID of the version.
version_number integer
Sequential version number starting from 1.
version_name string
Short version name (e.g. v1, v2).
version_name_display string
Formatted display name.
status string
Lifecycle status: draft, active, archived, or deprecated.
status_display string
Human-readable status label.
score number
Evaluation score (0.0–10.0). null if untested.
test_count integer
Total test executions run against this version.
pass_rate number
Test pass percentage (0–100). null if untested.
description string
Version description.
commit_message string
Commit message for this version.
release_notes string
Release notes, or null.
agent_definition string
UUID of the parent agent definition.
organization string
UUID of the owning organization.
configuration_snapshot object
Immutable snapshot of agent config at version creation.
is_active boolean
Whether this is the currently active version.
is_latest boolean
Whether this is the most recent version.
created_at datetime
ISO 8601 creation timestamp.
updated_at datetime
ISO 8601 last-modified timestamp.

Errors

400 Bad Request Optional

Invalid field values or missing commit_message.

401 Unauthorized Optional

Invalid or missing API credentials.

404 Not Found Optional

Agent definition not found.

500 Internal Server Error Optional

Unexpected server error.

GET /
Authentication
REQUEST 
 
 
  
 
 RESPONSE