Workspace tools
Inspect skills, organize labels, and manage runtime readiness.
Use these operations to choose skills, organize conversations, and check whether the workspace can run work.
The examples use the authenticated api helper from your first request.
Choose skills for an Agent
List the skills already available in this workspace:
api /agent/skills | jq '.data'For a meeting assistant, look for a skill that works with your document format. Use its exact name when updating the Agent's configuration.
Built-in skills are already available. For a marketplace skill, read its detail and install it first. Then save its name in the Agent's configuration.
Selecting a missing skill does not install it. Removing a skill does not remove its name from existing Agent configurations.
Skill endpoints
| Method and path | Use |
|---|---|
GET /v1/agent/skills | List built-in and workspace skills. |
GET /v1/agent/skills/marketplace | Browse the installable catalog. |
GET /v1/agent/skills/marketplace/{skill_id} | Read catalog and installation metadata. |
GET /v1/agent/skills/marketplace/{skill_id}/detail | Review a skill's instructions before installation. |
GET /v1/agent/skills/repo/{skill_id}/detail | Read a built-in skill's instructions. |
GET /v1/agent/skills/workspace/{skill_id}/detail | Read an installed skill's instructions. |
POST /v1/agent/skills/marketplace/{skill_id}/install | Install the selected catalog skill. |
DELETE /v1/agent/skills/marketplace/{skill_id} | Remove its installed marketplace copy. |
DELETE /v1/agent/skills/workspace/{skill_id} | Remove the named workspace skill directory. |
Reading a skill document does not execute it. After removal, update Agents that selected the skill or reinstall it.
Organize with labels
For example, mark the quickstart conversation for review. Create a label first:
label=$(api /agent/labels \
-H 'Content-Type: application/json' -d '{"name":"API review"}') &&
label_id=$(printf '%s' "$label" | jq -er '.id')If that label already exists, reuse its ID from GET /v1/agent/labels. After a lost creation response, check that list before creating another.
Add the label to the conversation without removing its existing labels:
thread=$(api "/threads/$thread_id") &&
label_body=$(printf '%s' "$thread" | jq --arg id "$label_id" \
'{label_ids: ((.label_ids // []) + [$id] | unique)}') &&
api "/threads/$thread_id" -X PATCH \
-H 'Content-Type: application/json' -d "$label_body"The updated conversation now includes this label's ID. Projects use the same label_ids field. Read the latest object before changing its labels.
Label endpoints
| Method and path | Use |
|---|---|
GET /v1/agent/labels | Read the label registry. |
POST /v1/agent/labels | Create with name and optional hex color. |
PATCH /v1/agent/labels | Send id with a changed name, color, or order. |
DELETE /v1/agent/labels | Remove the query's id. Keep its conversations and files. |
Check runtime readiness
Input submission starts the runtime when needed. To check readiness without sending a message:
api /agent/runtime/status | jq '{status, busy, can_wake, can_stop}'Use can_wake and can_stop when offering those controls. A busy runtime can refuse a stop. Stop active work through its thread or run first. Respect Retry-After on temporary readiness errors.
Runtime endpoint reference
| Method and path | Use |
|---|---|
GET /v1/agent/runtime/status | Read execution and storage readiness. |
POST /v1/agent/runtime/wake | Start if needed, then wait for readiness without sending a chat message. |
POST /v1/agent/runtime/stop | Release compute while keeping saved workspace data. |
Reset an entire workspace
POST /v1/agent/workspace/reset is destructive. It clears conversations, projects, workspace files, and installed or custom workspace skills. It also retires schedules.
Saved Agents, their knowledge files, and account settings remain. Home is recreated automatically. Reassign Agents from removed projects before reopening their conversations. Reinstall the workspace skills they need.
Use individual file, thread, or project deletion for targeted cleanup.