Amigo is now Concurrence
Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agents

Define agent identity, voice, background, and behaviors with immutable versioning in the Platform API.

Agents define the AI persona: identity, voice, background knowledge, behavioral guidelines, and communication style. Each agent supports immutable versioning. Creating a new version auto-increments the version number, and existing versions stay untouched.

Classic API vs Platform API: The Classic API also has agent endpoints. The Platform API agents are workspace-scoped and support richer configuration. Use the Platform API for agent setup; the Classic API resolves agents at conversation runtime.

Key Concepts

  • Agent: A named container with a description. Holds multiple versions.

  • Agent Version: An immutable snapshot of the agent's full configuration, including identity, voice, background, behaviors, and communication patterns.

  • Identity: The agent's persona name, role, developer attribution, default language, and relationship-to-developer settings (ownership, conversation/thought visibility).

  • Voice Config: Links the agent to a specific voice for text-to-speech.

Endpoints

Create an agent

Create an agent

post

Create a new agent in a workspace. Requires Agent.create permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body
namestring · min: 1 · max: 256Required
descriptionstring · max: 2000OptionalDefault: ""
Responses
201

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired
descriptionstringRequired
latest_versionintegerOptionalDefault: 0
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
post/v1/{workspace_id}/agents
POST /v1/{workspace_id}/agents HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "name": "text",
  "description": ""
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

List agents

Paginated and searchable.

List agents

get

List agents in a workspace with pagination. Requires Agent.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
sort_bystring[]OptionalDefault: []
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
searchstring · min: 1 · max: 200 · nullableOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/agents
GET /v1/{workspace_id}/agents HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "latest_version": 0,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get an agent

Get an agent

get

Retrieve an agent by ID. Requires Agent.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired
descriptionstringRequired
latest_versionintegerOptionalDefault: 0
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/{workspace_id}/agents/{agent_id}
GET /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update agent name/description

Update an agent

put

Update an agent's name or description. Requires Agent.update permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
Body
namestring · min: 1 · max: 256 · nullableOptional
descriptionstring · max: 2000 · nullableOptional
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
namestringRequired
descriptionstringRequired
latest_versionintegerOptionalDefault: 0
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
put/v1/{workspace_id}/agents/{agent_id}
PUT /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "name": "text",
  "description": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "latest_version": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Delete an agent

Deletion returns 409 Conflict while one or more services reference the agent. Update or delete those services before retrying.

Delete an agent

delete

Delete an agent. Agent versions are retained. Requires Agent.delete permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
Responses
204

Successful Response

No content
delete/v1/{workspace_id}/agents/{agent_id}
DELETE /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create a new version

Create an agent version

post

Create a new version of an agent. Version number is auto-incremented. Requires Agent.create permission for the first version and Agent.update permission afterward.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
Body
namestring · min: 1 · max: 256Required
initialsstring · max: 10OptionalDefault: ""
backgroundstring · max: 10000OptionalDefault: ""
behaviorsstring[] · max: 200Optional
communication_patternsstring[] · max: 200Optional
Responses
201

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
versionintegerRequired
namestringRequired
initialsstringRequired
backgroundstringRequired
behaviorsstring[]Required
communication_patternsstring[]Required
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
post/v1/{workspace_id}/agents/{agent_id}/versions
POST /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 626

{
  "name": "text",
  "initials": "",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ]
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "name": "text",
  "initials": "text",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "text",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

List versions

Paginated.

List agent versions

get

List versions of an agent with pagination. Requires Agent.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/agents/{agent_id}/versions
GET /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "version": 1,
      "name": "text",
      "initials": "text",
      "identity": {
        "name": "text",
        "role": "text",
        "developed_by": "text",
        "default_spoken_language": "text",
        "relationship_to_developer": {
          "ownership": "text",
          "type": "text",
          "conversation_visibility": "text",
          "thought_visibility": "text"
        }
      },
      "voice_config": {
        "voice_id": "text",
        "stability": 0,
        "similarity_boost": 0,
        "style": 0,
        "tts_provider": "cartesia",
        "tts_config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "language_providers": {
          "ANY_ADDITIONAL_PROPERTY": {
            "provider": "cartesia",
            "config": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          }
        },
        "session_provider": "amigo"
      },
      "background": "text",
      "behaviors": [
        "text"
      ],
      "communication_patterns": [
        "text"
      ],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get a specific version

Use the version number or latest to retrieve the most recent version.

Get an agent version

get

Retrieve a specific agent version by number, or 'latest'. Requires Agent.view permission.

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
versionany ofRequired
integer · min: 1 · max: 2147483647Optional
or
const: latestOptional
Responses
200

Successful Response

application/json
idstring · uuidRequired
workspace_idstring · uuidRequired
agent_idstring · uuidRequired
versionintegerRequired
namestringRequired
initialsstringRequired
backgroundstringRequired
behaviorsstring[]Required
communication_patternsstring[]Required
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/{workspace_id}/agents/{agent_id}/versions/{version}
GET /v1/{workspace_id}/agents/{agent_id}/versions/{version} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "version": 1,
  "name": "text",
  "initials": "text",
  "identity": {
    "name": "text",
    "role": "text",
    "developed_by": "text",
    "default_spoken_language": "text",
    "relationship_to_developer": {
      "ownership": "text",
      "type": "text",
      "conversation_visibility": "text",
      "thought_visibility": "text"
    }
  },
  "voice_config": {
    "voice_id": "text",
    "stability": 0,
    "similarity_boost": 0,
    "style": 0,
    "tts_provider": "cartesia",
    "tts_config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "language_providers": {
      "ANY_ADDITIONAL_PROPERTY": {
        "provider": "cartesia",
        "config": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      }
    },
    "session_provider": "amigo"
  },
  "background": "text",
  "behaviors": [
    "text"
  ],
  "communication_patterns": [
    "text"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Versioning Workflow

  1. Create an agent (name + description)

  2. Create version 1 with full identity, background, and behaviors

  3. Iterate by creating new versions. Each gets an auto-incremented number.

  4. Pin specific versions in Services via version sets

Use latest as the version parameter to retrieve the most recent version without knowing its number.

Deleting an agent removes its metadata but keeps all versions for audit. Services continue to function with their pinned versions.

PreviousWorkspaces
NextSkills

Last updated

Was this helpful?