Agents

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents

GET /v1/{workspace_id}/agents HTTP/1.1
Host: api.platform.amigo.ai
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
}

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post/v1/{workspace_id}/agents

POST /v1/{workspace_id}/agents HTTP/1.1
Host: api.platform.amigo.ai
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"
}

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}

GET /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
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 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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

put/v1/{workspace_id}/agents/{agent_id}

PUT /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
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

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

delete/v1/{workspace_id}/agents/{agent_id}

DELETE /v1/{workspace_id}/agents/{agent_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}/versions

GET /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: api.platform.amigo.ai
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
}

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post/v1/{workspace_id}/agents/{agent_id}/versions

POST /v1/{workspace_id}/agents/{agent_id}/versions HTTP/1.1
Host: api.platform.amigo.ai
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"
}

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

integerOptional

stringOptional

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

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get/v1/{workspace_id}/agents/{agent_id}/versions/{version}

GET /v1/{workspace_id}/agents/{agent_id}/versions/{version} HTTP/1.1
Host: api.platform.amigo.ai
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"
}

PreviousConfig

NextContext Graphs

Last updated 3 days ago

Was this helpful?