Skills

List skills

get

List skills for a workspace with pagination. Optionally filter by enabled status. Requires Skill.view permission.

Authorizations

BearerAuth

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

enabledboolean · nullableOptional

searchstring · min: 1 · max: 200 · nullableOptional

sort_bystring · nullableOptional

limitinteger · max: 100OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

401

Missing or invalid API key.

403

Insufficient permissions.

422

Validation Error

application/json

429

Rate limited.

get/v1/{workspace_id}/skills

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/skills 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",
      "slug": "text",
      "name": "text",
      "description": "text",
      "system_prompt": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "result_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "model": "text",
      "max_tokens": 1,
      "max_result_chars": 1,
      "max_input_tokens": 1,
      "timeout_s": 1,
      "thinking_effort": "low",
      "temperature": 1,
      "top_p": 1,
      "enable_caching": true,
      "enable_citations": true,
      "use_structured_output": true,
      "integration_tools": [
        {
          "integration": "text",
          "endpoint": "text"
        }
      ],
      "static_tools": [
        {
          "name": "text",
          "description": "text",
          "input_schema": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      ],
      "enabled": true,
      "max_agent_turns": 1,
      "checkpoint_enabled": true,
      "approval_required": true,
      "created_at": "2026-07-10T21:26:19.871Z",
      "updated_at": "2026-07-10T21:26:19.871Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1,
  "total": 1
}

Create a skill

post

Create a new companion agent skill in a workspace. Requires Skill.create permission.

Authorizations

BearerAuth

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

application/json

slugstring · min: 2 · max: 63RequiredPattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$

namestring · min: 1 · max: 256Required

descriptionstring · max: 2000Required

system_promptstring · max: 10000 · nullableOptional

modelstring · min: 1 · max: 128OptionalDefault: claude-sonnet-4-6

max_tokensinteger · min: 1 · max: 200000OptionalDefault: 4096

max_result_charsinteger · min: 1 · max: 200000OptionalDefault: 2000

max_input_tokensinteger · min: 1 · max: 2000000 · nullableOptional

timeout_snumber · min: 0.1 · max: 900OptionalDefault: 60

thinking_effortstring · enum · nullableOptionalPossible values:

temperaturenumber · max: 1 · nullableOptional

Anthropic sampling temperature (0-1). Ignored on models that reject sampling params (Opus 4.7+/Fable, which 400 otherwise). Set at most one of temperature/top_p -- Claude 4+ rejects both; the runtime keeps temperature and drops top_p.

top_pnumber · max: 1 · nullableOptional

Anthropic nucleus sampling (0-1). Ignored on sampling-param-rejecting models; see temperature.

enable_cachingbooleanOptionalDefault: true

enable_citationsbooleanOptionalDefault: false

use_structured_outputbooleanOptionalDefault: false

enabledbooleanOptionalDefault: true

max_agent_turnsinteger · min: 1 · max: 200OptionalDefault: 20

checkpoint_enabledbooleanOptionalDefault: true

approval_requiredbooleanOptionalDefault: false

Responses

201

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

slugstringRequired

namestringRequired

descriptionstringRequired

system_promptstringRequired

modelstringRequired

max_tokensintegerRequired

max_result_charsintegerRequired

max_input_tokensinteger · nullableRequired

timeout_snumberRequired

thinking_effortstring · enum · nullableRequiredPossible values:

temperaturenumber · nullableRequired

top_pnumber · nullableRequired

enable_cachingbooleanRequired

enable_citationsbooleanRequired

use_structured_outputbooleanRequired

enabledbooleanRequired

max_agent_turnsintegerRequired

checkpoint_enabledbooleanRequired

approval_requiredbooleanRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Workspace not found.

409

Skill slug already taken or conflicts with a built-in tool name.

422

Invalid request body.

429

Rate limited.

post/v1/{workspace_id}/skills

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/skills HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 674

{
  "slug": "text",
  "name": "text",
  "description": "text",
  "system_prompt": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "result_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "max_result_chars": 2000,
  "max_input_tokens": 1,
  "timeout_s": 60,
  "thinking_effort": "low",
  "temperature": 1,
  "top_p": 1,
  "enable_caching": true,
  "enable_citations": false,
  "use_structured_output": false,
  "integration_tools": [
    {
      "integration": "text",
      "endpoint": "text"
    }
  ],
  "static_tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "enabled": true,
  "max_agent_turns": 20,
  "checkpoint_enabled": true,
  "approval_required": false
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "text",
  "name": "text",
  "description": "text",
  "system_prompt": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "result_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "text",
  "max_tokens": 1,
  "max_result_chars": 1,
  "max_input_tokens": 1,
  "timeout_s": 1,
  "thinking_effort": "low",
  "temperature": 1,
  "top_p": 1,
  "enable_caching": true,
  "enable_citations": true,
  "use_structured_output": true,
  "integration_tools": [
    {
      "integration": "text",
      "endpoint": "text"
    }
  ],
  "static_tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "enabled": true,
  "max_agent_turns": 1,
  "checkpoint_enabled": true,
  "approval_required": true,
  "created_at": "2026-07-10T21:26:19.871Z",
  "updated_at": "2026-07-10T21:26:19.871Z"
}

Get a skill

get

Retrieve a skill by ID. Requires Skill.view permission.

Authorizations

BearerAuth

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

skill_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

slugstringRequired

namestringRequired

descriptionstringRequired

system_promptstringRequired

modelstringRequired

max_tokensintegerRequired

max_result_charsintegerRequired

max_input_tokensinteger · nullableRequired

timeout_snumberRequired

thinking_effortstring · enum · nullableRequiredPossible values:

temperaturenumber · nullableRequired

top_pnumber · nullableRequired

enable_cachingbooleanRequired

enable_citationsbooleanRequired

use_structured_outputbooleanRequired

enabledbooleanRequired

max_agent_turnsintegerRequired

checkpoint_enabledbooleanRequired

approval_requiredbooleanRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

422

Validation Error

application/json

429

Rate limited.

get/v1/{workspace_id}/skills/{skill_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/skills/{skill_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",
  "slug": "text",
  "name": "text",
  "description": "text",
  "system_prompt": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "result_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "text",
  "max_tokens": 1,
  "max_result_chars": 1,
  "max_input_tokens": 1,
  "timeout_s": 1,
  "thinking_effort": "low",
  "temperature": 1,
  "top_p": 1,
  "enable_caching": true,
  "enable_citations": true,
  "use_structured_output": true,
  "integration_tools": [
    {
      "integration": "text",
      "endpoint": "text"
    }
  ],
  "static_tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "enabled": true,
  "max_agent_turns": 1,
  "checkpoint_enabled": true,
  "approval_required": true,
  "created_at": "2026-07-10T21:26:19.871Z",
  "updated_at": "2026-07-10T21:26:19.871Z"
}

Update a skill

put

Update a skill's configuration in place.

Field semantics. Omitted fields and explicit null are treated identically — both leave the existing value unchanged. Empty-string is rejected with 422 for fields that carry a minLength bound (model). Clearing a previously-set optional value back to null is not currently supported via PUT.

Requires Skill.update permission.

Authorizations

BearerAuth

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

skill_idstring · uuidRequired

Body

application/json

namestring · min: 1 · max: 256 · nullableOptional

descriptionstring · max: 2000 · nullableOptional

system_promptstring · max: 10000 · nullableOptional

modelstring · min: 1 · max: 128 · nullableOptional

max_tokensinteger · min: 1 · max: 200000 · nullableOptional

max_result_charsinteger · min: 1 · max: 200000 · nullableOptional

max_input_tokensinteger · min: 1 · max: 2000000 · nullableOptional

timeout_snumber · min: 0.1 · max: 900 · nullableOptional

thinking_effortstring · enum · nullableOptionalPossible values:

temperaturenumber · max: 1 · nullableOptional

Anthropic sampling temperature (0-1); see CreateSkillRequest. null/absent leaves it unchanged.

top_pnumber · max: 1 · nullableOptional

Anthropic nucleus sampling (0-1); see CreateSkillRequest. null/absent leaves it unchanged.

enable_cachingboolean · nullableOptional

enable_citationsboolean · nullableOptional

use_structured_outputboolean · nullableOptional

enabledboolean · nullableOptional

max_agent_turnsinteger · min: 1 · max: 200 · nullableOptional

checkpoint_enabledboolean · nullableOptional

approval_requiredboolean · nullableOptional

Responses

200

Successful Response

application/json

idstring · uuidRequired

workspace_idstring · uuidRequired

slugstringRequired

namestringRequired

descriptionstringRequired

system_promptstringRequired

modelstringRequired

max_tokensintegerRequired

max_result_charsintegerRequired

max_input_tokensinteger · nullableRequired

timeout_snumberRequired

thinking_effortstring · enum · nullableRequiredPossible values:

temperaturenumber · nullableRequired

top_pnumber · nullableRequired

enable_cachingbooleanRequired

enable_citationsbooleanRequired

use_structured_outputbooleanRequired

enabledbooleanRequired

max_agent_turnsintegerRequired

checkpoint_enabledbooleanRequired

approval_requiredbooleanRequired

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

422

Invalid request body.

429

Rate limited.

put/v1/{workspace_id}/skills/{skill_id}

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/skills/{skill_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 636

{
  "name": "text",
  "description": "text",
  "system_prompt": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "result_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "text",
  "max_tokens": 1,
  "max_result_chars": 1,
  "max_input_tokens": 1,
  "timeout_s": 1,
  "thinking_effort": "low",
  "temperature": 1,
  "top_p": 1,
  "enable_caching": true,
  "enable_citations": true,
  "use_structured_output": true,
  "integration_tools": [
    {
      "integration": "text",
      "endpoint": "text"
    }
  ],
  "static_tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "enabled": true,
  "max_agent_turns": 1,
  "checkpoint_enabled": true,
  "approval_required": true
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "text",
  "name": "text",
  "description": "text",
  "system_prompt": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "result_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "model": "text",
  "max_tokens": 1,
  "max_result_chars": 1,
  "max_input_tokens": 1,
  "timeout_s": 1,
  "thinking_effort": "low",
  "temperature": 1,
  "top_p": 1,
  "enable_caching": true,
  "enable_citations": true,
  "use_structured_output": true,
  "integration_tools": [
    {
      "integration": "text",
      "endpoint": "text"
    }
  ],
  "static_tools": [
    {
      "name": "text",
      "description": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "enabled": true,
  "max_agent_turns": 1,
  "checkpoint_enabled": true,
  "approval_required": true,
  "created_at": "2026-07-10T21:26:19.871Z",
  "updated_at": "2026-07-10T21:26:19.871Z"
}

Delete a skill

delete

Delete a skill.

Not idempotent. A second concurrent caller racing the same delete will receive 404 Not Found once the row is gone — clients should treat 404 as success-equivalent for cleanup workflows. Requires Skill.delete permission.

Authorizations

BearerAuth

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

skill_idstring · uuidRequired

Responses

204

Successful Response

No content

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

409

Skill is referenced by one or more context graphs.

422

Validation Error

application/json

429

Rate limited.

delete/v1/{workspace_id}/skills/{skill_id}

HTTPcURLJavaScriptPython

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

No content

Get skill references

get

Find all HSMs and services that reference this skill's slug in their latest version's tool_call_specs. Requires Skill.view permission.

Authorizations

BearerAuth

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

skill_idstring · uuidRequired

Responses

200

Successful Response

application/json

skill_idstring · uuidRequired

skill_slugstringRequired

service_referencesstring · uuid[]Required

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

422

Validation Error

application/json

429

Rate limited.

get/v1/{workspace_id}/skills/{skill_id}/references

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/skills/{skill_id}/references HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "skill_id": "123e4567-e89b-12d3-a456-426614174000",
  "skill_slug": "text",
  "context_graph_references": [
    {
      "context_graph_id": "123e4567-e89b-12d3-a456-426614174000",
      "context_graph_name": "text",
      "version": 1,
      "states": [
        {
          "state_name": "text",
          "tool_spec_category": "text"
        }
      ]
    }
  ],
  "service_references": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Test a skill

post

Execute a skill in isolation with the given input.

Authorizations

BearerAuth

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

skill_idstring · uuidRequired

Body

application/json

Responses

200

Successful Response

application/json

resultstringRequired

Final result text produced by the skill

duration_msnumberRequired

Total execution time in milliseconds

input_tokensintegerRequired

Number of input tokens consumed

output_tokensintegerRequired

Number of output tokens generated

cached_tokensintegerRequired

Number of tokens served from cache

roundsintegerRequired

Number of agent reasoning rounds executed

errorstring · nullableOptional

Error message if the skill execution failed

401

Missing or invalid API key.

403

Insufficient permissions.

404

Skill not found.

422

Validation Error

application/json

post/v1/{workspace_id}/skills/{skill_id}/test

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/skills/{skill_id}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "static_tool_mocks": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "result": "text",
  "duration_ms": 1,
  "input_tokens": 1,
  "output_tokens": 1,
  "cached_tokens": 1,
  "rounds": 1,
  "sub_tool_logs": [
    {
      "tool_name": "text",
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": "text",
      "duration_ms": 1,
      "succeeded": true,
      "round": 1
    }
  ],
  "error": "text"
}