Verify the account is on an Enterprise plan or above; the skill-based routing API is not available on lower tiers.
List all skill types (named attributes) and their child skills (named attribute values) via GET /api/v2/routing/attributes to build a local mapping of skill IDs to human-readable names.
Retrieve the current skill assignments for a set of agents using GET /api/v2/routing/agents/instance_values with a filter[agent_ids] query parameter.
To add, replace, or remove skills for up to 100 agents at once, send a POST to /api/v2/routing/agents/instance_values/bulk_update with an array of agent-attribute-value objects.
To assign required skills to a ticket, PATCH the ticket's custom_fields or use the skill routing endpoint for that ticket so the routing engine can match agents with the required skills.
Use the Incremental Skill-Based Routing endpoint (GET /api/v2/routing/incremental/attribute_values) with a start_time cursor to sync changes without a full pull.
Known gotchas
Skill types and skills are two distinct resource levels in this API (attribute vs. attribute value); confusing the IDs of the two levels is a common cause of 422 errors.
The bulk update endpoint accepts up to 100 agents per request; larger rosters require batching with a delay to respect rate limits.
Omnichannel routing also considers agent status and channel capacity in addition to skills; assigning skills via the API does not by itself cause the routing engine to assign tickets if an agent is offline or at capacity.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp