> ## 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. # Update an agent's visibility, archive state or pin ## OpenAPI ````yaml /api-reference/openapi.yaml patch /agents/{agent_id_or_name} 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/{agent_id_or_name}: patch: tags: - agents summary: Update an agent's visibility, archive state or pin operationId: update_agent parameters: - name: agent_id_or_name in: path required: true schema: type: string requestBody: required: false content: application/json: schema: properties: is_public: default: null title: Is Public nullable: true type: boolean is_archived: default: null title: Is Archived nullable: true type: boolean is_pinned: default: null title: Is Pinned nullable: true type: boolean avatar_url: default: null title: Avatar Url nullable: true type: string maintainer_id: default: null title: Maintainer Id nullable: true format: uuid type: string category: default: null description: Category ID or name title: Category nullable: true type: string tags: default: null description: Tag names; tags other than Guild's need a category title: Tags nullable: true items: type: string type: array title: UpdateAgentInput type: object responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - oauth2: - agents:write components: 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 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: 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 ````