Guest Machines
API referenceAgents

List agents

GET/api/v1/agents

List agents visible to the caller in the active organization. Private agents are visible to their owners and workspace admins; restricted agents are also visible to their grantees. Shared agents are visible to all active members.

Omit limit to return all visible matches. total counts every visible match after applying the search and filters. Results follow sort, with stable IDs breaking ties, before pagination.

Required access

Credentials: automation account, delegated token, user session, user API key

User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.

Scope: agents:read

Returns only agents the caller can see. Private agents are invisible to automation accounts regardless of scope, so a correctly scoped key against an unshared workspace returns an empty list rather than an error.

Authorization

AuthorizationBearer <token>

A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.

In: header

Query Parameters

include_inactive?Include Inactive

Include paused agents

Defaultfalse
is_active?|

Only active (true) or only paused (false) agents; overrides include_inactive

include_tools?Include Tools

Include assigned tool names for each agent

Defaulttrue
limit?|

Page size. Omit to return every visible agent.

offset?Offset
Range0 <= value
Default0
search?|

Search name or description

needs_owner?Needs Owner

Only agents in a shared workspace that nobody owns, which the workspace admins manage; combine with is_active for active or paused ones

Defaultfalse
owned_by_me?Owned By Me

Only agents the caller owns. An automation account owns none, so it gets an empty list

Defaultfalse
sort?ListSort

Order of the results, applied before paging: name (A to Z, the default), name_desc, newest (most recently created first), recently_run (most recently finished run first, never run last) or recently_updated. Ties fall back to the agent ID

Default"name"

Value in

  • "name"
  • "name_desc"
  • "newest"
  • "recently_run"
  • "recently_updated"

Header Parameters

X-Org-Id?|

Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/agents" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"
{  "agents": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",      "owner_user_ids": [        "53de0326-38a5-4c57-8d27-9211c8be4319"      ],      "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",      "visibility": "org_shared",      "name": "string",      "description": "string",      "executor_type": "claude",      "model": "string",      "system_prompt": "string",      "thinking_level": "high",      "temperature": 0.1,      "execution_environment": "gsmc_runtime",      "computer_use_enabled": false,      "environment_config": {},      "input_schema": {},      "output_schema": {},      "is_active": true,      "completion_contract": {        "version": 1,        "input_roots": [          "string"        ],        "checks": [          {            "id": "string",            "description": "string",            "when": [              {                "value": {                  "source": "input",                  "path": "",                  "value": null,                  "parts": [                    {}                  ],                  "required": true,                  "fallback": null,                  "transform": "identity"                },                "one_of": [                  null                ]              }            ],            "kind": "field_match",            "actual": {              "source": "input",              "path": "",              "value": null,              "parts": [                {}              ],              "required": true,              "fallback": null,              "transform": "identity"            },            "expected": {              "source": "input",              "path": "",              "value": null,              "parts": [                {}              ],              "required": true,              "fallback": null,              "transform": "identity"            }          }        ],        "correction_attempts": 2      },      "can_duplicate": false,      "allowed_invocable_ids": [        "812b7eff-ee45-4be1-8779-fa59b3cf4527"      ],      "allowed_invocable_targets": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "kind": "agent",          "name": "string"        }      ],      "allowed_invocables": [        "string"      ],      "knowledge_scope": {        "folder_ids": [          "c9c54c2c-7793-4b70-8b93-7e3771bbc0c0"        ],        "file_ids": [          "1c0f12fe-c5bf-4fbd-ba1b-466cb232eca5"        ]      },      "avatar_blob_name": "string",      "avatar_sas_url": "string",      "avatar_expires_at": "2019-08-24T14:15:22Z",      "configured_tools": [        {          "origin": "builtin",          "source_id": "string",          "canonical_name": "string",          "display_name": "string",          "enabled": true,          "owned_by_caller": true        }      ],      "hidden_configured_tool_count": 0,      "allowed_tools": [        "string"      ],      "mcp_server_ids": [        "6645753c-0a13-4667-8dd3-d80a8e4fd76f"      ],      "tool_approval_modes": {        "property1": "auto",        "property2": "auto"      },      "unattended_preapproved_tools": [        "string"      ],      "config_revision": 0,      "config_digest": "0000000000000000000000000000000000000000000000000000000000000000",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "total": 0}

Attach a local MCP connector POST

Attach a synchronized connector directly in local execution mode. This path does not require the selected model to support a hosted MCP connector; it uses that model's registered function-tool encoder.

Create an agent POST

Create an agent owned by the user represented by the delegated token. The response returns the saved configuration.