> ## Documentation Index > Fetch the complete documentation index at: https://docs.guild.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1. > The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml). > Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer :`. See https://docs.guild.ai/api-reference/introduction#authentication. > To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers. > To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt. # List and search agents > No key required to see public agents. With a key holding `agents:read`, the results also include the account's own private agents. ## OpenAPI ````yaml /api-reference/openapi.yaml get /agents openapi: 3.0.3 info: title: Guild Public API version: 1.0.0 description: >- The Guild public API, served at https://api.guild.ai/v1. Authenticate with an account API key, sent as HTTP Basic (key id as the username, secret as the password) or as a Bearer token `:`, or with an OAuth 2.0 access token. Each operation lists the credentials it accepts and the scopes it needs; see https://docs.guild.ai/api-reference/introduction#scopes. Versions are path integers and v1 is the only one: a breaking change ships as a new version rather than changing v1. Lists page with `limit` and `offset` and report `pagination.has_more`. A session-events websocket also exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the same credentials on the handshake; OpenAPI cannot describe websockets, so it is not listed in paths. servers: - url: https://api.guild.ai/v1 description: Production security: [] tags: - name: accounts - name: agents - name: integrations - name: other - name: sessions - name: skills - name: triggers - name: workspaces paths: /agents: get: tags: - agents summary: List and search agents description: >- No key required to see public agents. With a key holding `agents:read`, the results also include the account's own private agents. operationId: list_agents parameters: - name: sort_by in: query required: false schema: default: null description: Column name to sort by; prefix with '-' for descending order. title: Sort By nullable: true type: string - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: search in: query required: false schema: default: null description: Words to match in name or description title: Search nullable: true type: string - name: fast in: query required: false schema: default: false title: Fast type: boolean - name: published_only in: query required: false schema: default: false title: Published Only type: boolean - name: is_public in: query required: false schema: default: false title: Is Public type: boolean - name: is_pinned in: query required: false schema: default: null title: Is Pinned nullable: true type: boolean - name: for_workspace in: query required: false schema: default: null title: For Workspace nullable: true type: string - name: tags in: query required: false schema: default: null title: Tags nullable: true type: string - name: categories in: query required: false schema: default: null title: Categories nullable: true type: string - name: agent_types in: query required: false schema: default: null title: Agent Types nullable: true type: string - name: owner in: query required: false schema: default: null description: >- Owning user or organization, by name or ID. Omit for every agent you can see. title: Owner nullable: true type: string - name: contributor in: query required: false schema: default: null title: Contributor nullable: true type: string description: >- Filter the list to items created, maintained, or authored by the specified user. responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Agent' pagination: $ref: '#/components/schemas/Pagination' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - {} - apiKey: [] - bearerApiKey: [] - oauth2: - agents:read components: parameters: Limit: name: limit in: query required: false schema: default: 20 description: Maximum number of items to return. maximum: 500 minimum: 0 title: Limit type: integer Offset: name: offset in: query required: false schema: default: 0 description: Number of items to skip before returning results. maximum: 9223372036854776000 minimum: 0 title: Offset type: integer schemas: Agent: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_type: type: string enum: - GUILD_TYPESCRIPT - GUILD_NATIVE - GOOSE - OPENCLAW - LANGGRAPH - ADK description: type: string maxLength: 8192 description: >- Manual description field. Can be empty; the effective description falls back to generated_description. is_public: type: boolean description: Whether the asset is visible to the community or only its owner. name: type: string maxLength: 100 description: Unique name identifying the asset within the owner account. owner_id: type: string format: uuid description: The account that owns this entity. cached_forks_count: type: integer description: A cached version of the forks count. Might not be up to date. cached_installs_count: type: integer description: A cached version of the installs count. Might not be up to date. cached_likes_count: type: integer description: A cached version of the likes count. Might not be up to date. is_pinned: type: boolean description: >- If true, it means the agent is pinned on the owner's account's profile. moderation_state: type: string enum: - ACTIVE - DEMOTED - UNLISTED - DISABLED - TAKEN_DOWN description: >- Operator-controlled moderation/curation state. Owners cannot change this; only operators can, via the hub kebab menu or ops tooling. status: type: string enum: - CREATED - GIT_REPOSITORY_CREATED - READY archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true avatar_url: type: string maxLength: 255 nullable: true category_id: type: string format: uuid nullable: true description: The category this agent is sorted in. creation_template: type: string enum: - LLM - AUTO_MANAGED_STATE - BLANK - GOOSE - GUILD_NATIVE - OPENCLAW - LANGGRAPH - ADK nullable: true description: >- If applicable, the template that was selected during the creation of this agent. Note: it doesn't mean the agent is still following the template now. creator_id: type: string format: uuid nullable: true description: >- The user, agent or API key that created this agent. Null for legacy rows created before creator attribution was recorded. forked_from_id: type: string format: uuid nullable: true description: >- If applicable, the ID of the agent version this agent was forked from. generated_description: type: string maxLength: 8192 nullable: true description: >- LLM-generated description based on agent code. Regenerated automatically on every commit. maintainer_id: type: string format: uuid nullable: true description: >- OPTIONAL. Refers to the person within an organization that is tasked with maintaining the agent. archived_by: {} category: {} creator: description: The user who created this agent. forks_count: type: integer description: Number of times this agent has been forked full_name: type: string description: Full agent name in format "owner_name/agent_name" git_url: type: string description: URL to the agent's git repository installs_count: type: integer description: Number of times this agent has been installed in workspaces is_description_autogenerated: {} last_updated_by: description: The user who pushed the newest version of this agent. latest_published_version: {} latest_version: {} likes_count: type: integer description: Number of likes this agent has received maintainer: type: object nullable: true description: Maintainer of the agent (for organization-owned agents) owner: $ref: '#/components/schemas/Account' public_profile_url: {} type: {} viewer_can_edit: type: boolean description: Whether the current viewer can edit this agent Pagination: type: object properties: total_count: description: Items matching the request across all pages. type: integer limit: description: Page size of this response. type: integer offset: description: Items skipped before this page. type: integer has_more: description: Whether another page follows; request it with offset + limit. type: boolean ErrorResponse: type: object properties: error: type: string message: type: string Account: oneOf: - $ref: '#/components/schemas/Organization' - $ref: '#/components/schemas/User' Organization: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time creator_id: type: string format: uuid description: >- The user who created this organization. Note that this does not give that user membership. name: type: string maxLength: 100 description: The unique name identifying this account. cached_forks_count: type: integer description: A cached version of the forks count. Might not be up to date. cached_forks_public_count: type: integer description: >- A cached version of the forks count for public agents. Might not be up to date. cached_installs_count: type: integer description: A cached version of the installs count. Might not be up to date. cached_installs_public_count: type: integer description: >- A cached version of the installs count for public agents. Might not be up to date. cached_likes_count: type: integer description: A cached version of the likes count. Might not be up to date. cached_likes_public_count: type: integer description: >- A cached version of the likes count for public agents. Might not be up to date. avatar_url: type: string maxLength: 255 nullable: true banner_url: type: string maxLength: 255 nullable: true bio: type: string maxLength: 255 nullable: true closure_requested_at: type: string format: date-time nullable: true description: >- Set when an admin asks support to close the account, so a repeated request does not email support again. closure_requested_by_id: type: string format: uuid nullable: true discord_url: type: string maxLength: 255 nullable: true email_domain: type: string maxLength: 100 nullable: true description: >- The email domain of the organization. Members will be automatically invited to this organization if they have an email with this domain. full_name: type: string maxLength: 100 nullable: true description: The display name of the account. github_url: type: string maxLength: 255 nullable: true linkedin_url: type: string maxLength: 255 nullable: true threads_url: type: string maxLength: 255 nullable: true website_url: type: string maxLength: 255 nullable: true x_url: type: string maxLength: 255 nullable: true youtube_url: type: string maxLength: 255 nullable: true member_count: {} viewer_membership_id: {} viewer_membership_public: {} viewer_role: type: string enum: - ADMIN - MEMBER nullable: true description: Current viewer's role in the organization (null if not a member) type: type: string enum: - organization description: Account type, always "organization" User: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time email: type: string maxLength: 100 name: type: string maxLength: 100 description: The unique name identifying this account. cached_forks_count: type: integer description: A cached version of the forks count. Might not be up to date. cached_forks_public_count: type: integer description: >- A cached version of the forks count for public agents. Might not be up to date. cached_installs_count: type: integer description: A cached version of the installs count. Might not be up to date. cached_installs_public_count: type: integer description: >- A cached version of the installs count for public agents. Might not be up to date. cached_likes_count: type: integer description: A cached version of the likes count. Might not be up to date. cached_likes_public_count: type: integer description: >- A cached version of the likes count for public agents. Might not be up to date. is_operator: type: boolean description: >- Whether or not the user is a Guild employee (or operator). BE VERY CAREFUL WITH THIS. notification_email_level: type: string enum: - NONE - IMPORTANT - ALL description: >- NONE = no emails, IMPORTANT = invitations and agent-ask only, ALL = all notification types. avatar_url: type: string maxLength: 255 nullable: true banner_url: type: string maxLength: 255 nullable: true bio: type: string maxLength: 255 nullable: true closed_at: type: string format: date-time nullable: true description: >- Set when an operator closes the account. A closed user cannot start a login session by any method. closure_requested_at: type: string format: date-time nullable: true description: >- Set when an admin asks support to close the account, so a repeated request does not email support again. closure_requested_by_id: type: string format: uuid nullable: true discord_url: type: string maxLength: 255 nullable: true full_name: type: string maxLength: 100 nullable: true description: The display name of the account. github_url: type: string maxLength: 255 nullable: true hubspot_synced_at: type: string format: date-time nullable: true linkedin_url: type: string maxLength: 255 nullable: true threads_url: type: string maxLength: 255 nullable: true username_set_at: type: string format: date-time nullable: true description: >- Set when the user picks their username during onboarding. Once set, the username cannot be changed. website_url: type: string maxLength: 255 nullable: true x_url: type: string maxLength: 255 nullable: true youtube_url: type: string maxLength: 255 nullable: true type: type: string enum: - user description: Account type, always "user" securitySchemes: apiKey: type: http scheme: basic description: >- API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes. bearerApiKey: type: http scheme: bearer bearerFormat: : description: >- The same API key as one Bearer token, `:`. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes. oauth2: type: oauth2 description: >- OAuth 2.0 authorization code flow with PKCE (S256). Discovery: https://api.guild.ai/.well-known/oauth-authorization-server. flows: authorizationCode: authorizationUrl: https://api.guild.ai/v1/oauth/authorize tokenUrl: https://api.guild.ai/v1/oauth/token refreshUrl: https://api.guild.ai/v1/oauth/token scopes: agents:read: Read agents agents:write: Read and change agents sessions:read: Read sessions sessions:write: Read and change sessions workspaces:read: Read workspaces workspaces:write: Read and change workspaces skills:read: Read skills skills:write: Read and change skills integrations:read: Read integrations integrations:write: Read and change integrations applications:read: Read applications applications:write: Read and change applications organizations:read: Read organizations organizations:write: Read and change organizations ````