> ## 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. # Activate a trigger ## OpenAPI ````yaml /api-reference/openapi.yaml post /triggers/{trigger_id}/activate 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: /triggers/{trigger_id}/activate: post: tags: - triggers summary: Activate a trigger operationId: activate_trigger parameters: - name: trigger_id in: path required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/WorkspaceTrigger' '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' security: - oauth2: - workspaces:write components: schemas: WorkspaceTrigger: oneOf: - $ref: '#/components/schemas/WorkspaceTriggerApi' - $ref: '#/components/schemas/WorkspaceTriggerTime' - $ref: '#/components/schemas/WorkspaceTriggerWebhook' ErrorResponse: type: object properties: error: type: string message: type: string WorkspaceTriggerApi: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid description: The workspace agent to run when the trigger is activated. name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. workspace_id: type: string format: uuid creator_id: type: string format: uuid nullable: true description: >- The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. type: type: string enum: - api description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_agent: $ref: '#/components/schemas/WorkspaceAgent' WorkspaceTriggerTime: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid description: The workspace agent to run when the trigger is activated. agent_input: type: object description: >- The input that should be passed to the agent when the trigger is executed. It must match the input schema of the agent being triggerred. frequency: type: string enum: - HOURLY - DAILY - WEEKLY - MONTHLY - CRON name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. next_run_at: type: string format: date-time description: When should the next run happen? workspace_id: type: string format: uuid creator_id: type: string format: uuid nullable: true description: >- The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. cron_expression: type: string maxLength: 100 nullable: true description: Standard 5-field cron expression. Only used with CRON frequency. cron_timezone: type: string maxLength: 50 nullable: true description: >- IANA timezone for cron evaluation (e.g. America/Los_Angeles). If omitted or None, cron evaluation uses UTC. days_of_month: type: array items: {} nullable: true description: 'None for non-MONTHLY frequency. List of days: [1, 8, 16].' days_of_week: type: array items: {} nullable: true description: 'None for non-WEEKLY frequency. List of days: ["MONDAY", "TUESDAY"].' deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. minutes_of_hour: type: array items: {} nullable: true description: >- For HOURLY frequency only. Defaults to on the hour. List of minutes: [0, 15, 30, 45]. time_of_day: nullable: true description: None for `HOURLY` frequency. If not provided, will default to 9am. type: type: string enum: - time description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_aget: $ref: '#/components/schemas/WorkspaceAgent' WorkspaceTriggerWebhook: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid description: The workspace agent to run when the trigger is activated. name: type: string maxLength: 255 description: Human-readable label identifying the trigger within its workspace. webhook_config_id: type: string format: uuid workspace_id: type: string format: uuid action: type: string maxLength: 100 nullable: true description: Optional action filter. If null, matches all actions. agent_input: type: object nullable: true creator_id: type: string format: uuid nullable: true description: >- The actor (a user or an account API key) that created this trigger. Null for legacy rows created before creator attribution was recorded. credentials_id: type: string format: uuid nullable: true deactivated_at: type: string format: date-time nullable: true description: If set, indicates when the trigger has been deactivated. event_type: type: string maxLength: 100 nullable: true description: |- The type of webhook event (e.g., 'pull_request', 'push'). If null, matches all events. service_config: type: object nullable: true integration: {} type: type: string enum: - webhook description: Trigger type discriminator agent: $ref: '#/components/schemas/Agent' workspace_aget: $ref: '#/components/schemas/WorkspaceAgent' 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 WorkspaceAgent: 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 or API key that added this agent version to the workspace. version_id: type: string format: uuid workspace_id: type: string format: uuid is_default_chat_agent: type: boolean description: >- If True, this workspace agent is used for new chat sessions when no explicit agent is provided. should_autoupdate: type: boolean description: >- If True, the agent will automatically update when a new version is published. archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true profile_name: type: string maxLength: 100 nullable: true description: >- Set when this install is an MCP gateway profile, addressed as /workspaces//mcp/. Unset on ordinary agent installs. required_credentials_mode: type: string enum: - SHARED - MEMBER nullable: true description: >- Whose credentials this agent may run with: SHARED = only org-side credentials serve, MEMBER = only the acting member's own. Unset = the workspace's declaration applies, and no requirement when that is unset too. agent: $ref: '#/components/schemas/Agent' agent_version: $ref: '#/components/schemas/AgentVersion' creator: $ref: '#/components/schemas/User' workspace: $ref: '#/components/schemas/Workspace' Account: oneOf: - $ref: '#/components/schemas/Organization' - $ref: '#/components/schemas/User' AgentVersion: oneOf: - $ref: '#/components/schemas/AgentVersionCommitted' - $ref: '#/components/schemas/AgentVersionEphemeral' 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" Workspace: 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 name: type: string maxLength: 100 owner_id: type: string format: uuid description: The account that owns this entity. restrict_account_credentials: type: boolean description: >- When true, tasks in this workspace may not fall back to the owning account's shared credential pool: a resolution that would reach the account default is refused so the workspace must rely on credentials granted or connected to its agents. should_restrict_members: type: boolean description: >- When true, only workspace members (plus org admins of the owning org) can access this workspace; when false, it is open to the whole owning org. unlimited_power_mode: type: boolean description: >- When true, this workspace's execution-tree fan-out limits are raised to the platform ceilings instead of the default budgets. The limits are raised, not removed. https://i.ibb.co/5XsvmfKg/CFD5-C99-C-B322-46-A2-9892-AFDF484-D28-E1-1.webp archived_at: type: string format: date-time nullable: true archived_by_id: type: string format: uuid nullable: true required_credentials_mode: type: string enum: - SHARED - MEMBER nullable: true description: >- Whose credentials agents in this workspace may run with: SHARED = only org-side credentials serve, MEMBER = only the acting member's own. Unset = no requirement. A workspace agent's own declaration overrides this one. archived_by: {} creator: {} full_name: type: string description: Full workspace name in format "owner_name~workspace_name" is_viewer_member: {} owner: $ref: '#/components/schemas/Account' unlimited_power_mode_enabled: {} 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" AgentVersionCommitted: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid author_id: type: string format: uuid validation_status: type: string enum: - SKIPPED - PENDING - RUNNING - PASSED - FAILED dependencies: type: object nullable: true description: npm package.json dependencies description: type: string maxLength: 8192 nullable: true description: Description for the agent extracted from the agent code. env_references: type: array items: {} nullable: true description: >- Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time input_schema: type: object nullable: true description: JSON Schema from Zod input llm_models: type: array items: {} nullable: true description: >- Acceptable provider/model pairs from guild.yaml `models`, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}] output_schema: type: object nullable: true description: JSON Schema from Zod output published_at: type: string format: date-time nullable: true publishing_started_at: type: string format: date-time nullable: true raw_tools: type: array items: {} nullable: true description: >- Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin). runtime_environment_id: type: string format: uuid nullable: true sha: type: string maxLength: 40 nullable: true description: >- Git commit SHA (40-character hexadecimal). For agents: set on version creation. For integrations: set after code is stored in GitHub. summary: type: string maxLength: 500 nullable: true description: >- Commit message summary. For agents: set on version creation. For integrations: set after code is stored in GitHub. tools: type: array items: {} nullable: true version_number: type: string maxLength: 100 nullable: true description: >- The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version agent: {} author: {} status: {} version_type: {} AgentVersionEphemeral: type: object properties: id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time agent_id: type: string format: uuid author_id: type: string format: uuid files: type: object description: >- The files for this version and their content. Format: {[key: filename]: content} validation_status: type: string enum: - SKIPPED - PENDING - RUNNING - PASSED - FAILED dependencies: type: object nullable: true description: npm package.json dependencies description: type: string maxLength: 8192 nullable: true description: Description for the agent extracted from the agent code. env_references: type: array items: {} nullable: true description: >- Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time input_schema: type: object nullable: true description: JSON Schema from Zod input llm_models: type: array items: {} nullable: true description: >- Acceptable provider/model pairs from guild.yaml `models`, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}] output_schema: type: object nullable: true description: JSON Schema from Zod output raw_tools: type: array items: {} nullable: true description: >- Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin). runtime_environment_id: type: string format: uuid nullable: true tools: type: array items: {} nullable: true version_number: type: string maxLength: 100 nullable: true description: >- The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version agent: {} author: {} published_at: {} publishing_started_at: {} sha: {} status: {} summary: {} version_type: {} 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 ````